Skip to main content

CLI Reference

aetron-miner is the reference client a miner runs locally. It is a thin command-line wrapper over a background daemon: the CLI sends requests over a local RPC socket, and the daemon holds the identity, the chain connection, and the engine that picks up jobs. This page lists every command group, what each subcommand does, its syntax, and a typical example. For a first-time setup walk-through, read How to Start Mining.

Invocation and Global Options​

aetron-miner [--lang <en|ru>] [COMMAND] [ARGS]

--lang is global and can be placed on any command. It accepts en and ru. When it is omitted, the interface language is auto-detected from the operating system. The flag takes priority over the AETRON_LANG environment variable, and the choice is frozen for the rest of the process.

Running aetron-miner with no command behaves differently depending on where it runs:

  • In a terminal (both stdin and stdout are a TTY) it opens the interactive TUI, a full-screen dashboard for the same operations described below.
  • In a pipe, a script, or CI it prints the standard help text and exits instead of hanging on an interactive screen.
aetron-miner                 # interactive TUI
aetron-miner --lang ru status
aetron-miner | cat           # prints help, no TUI

State lives under ~/.aetron-miner/: config.toml for configuration, daemon.sock for the RPC socket, daemon.log for logs, and keystore/ for keys.

Setup and Lifecycle​

init​

Interactive wizard that creates ~/.aetron-miner/config.toml. If the file already exists, it asks before overwriting. When stdin is not a TTY it falls back to reading answers line by line, so it works in scripts.

aetron-miner init

The wizard asks for the wallet path, the Neuronet ID, the model file path, an optional GPU limit from 0 to 100 percent (empty means no limit), the cache directory for models and datasets, and a maximum cache size in GB as a soft limit where 0 means unlimited. For the cache size it suggests half of the free space on the volume holding the cache directory. It then asks for the network (mainnet, testnet, or local, default testnet), and for local it additionally asks for the Substrate WebSocket node URL and the task ID.

start​

Brings the whole miner up in one step: it starts the background daemon, waits for its RPC socket, then starts the engine event loop. It is equivalent to daemon start followed by engine start.

aetron-miner start

stop​

Stops the engine first (gracefully, letting the current job finish) and then stops the daemon.

aetron-miner stop

status​

Prints whether the config file exists, then queries the daemon over RPC for a live snapshot: PID, uptime, the configured network, which chain backend the daemon actually built, mining state, and completed job count. If the daemon is not running, it falls back to what can be read locally and tells you how to bring it up.

aetron-miner status

logs​

Streams ~/.aetron-miner/daemon.log, printing existing content first and then following it like tail -f. It handles log rotation by re-reading from the start when the file shrinks. If the file does not exist, it says so rather than waiting.

aetron-miner logs

daemon​

Lifecycle of the background process. start spawns a detached daemon which writes a pidfile and opens the Unix socket; the CLI waits up to 3 seconds for both to appear before reporting success. stop reads the pidfile, sends SIGTERM, waits up to 5 seconds for a graceful exit, then sends SIGKILL. restart is stop followed by start, which is how you apply an edited config. status sends a ping and prints the PID and uptime, or reports that nothing is running.

aetron-miner daemon start
aetron-miner daemon stop
aetron-miner daemon restart   # apply changes made to config.toml
aetron-miner daemon status

engine​

Controls the event loop inside a running daemon. All five subcommands require the daemon to be up, otherwise the CLI tells you to run daemon start first.

  • start begins picking up jobs.
  • stop requests a graceful shutdown and waits for the current job.
  • pause suspends the loop without tearing anything down.
  • resume takes it off pause.
  • status prints an engine snapshot: mode, jobs completed, jobs failed, average latency in milliseconds, the current job ID if one is running, the last error if there was one, completed Pulse cycles, Pulse validations done, the Pulse tier, and the active inference backend.
aetron-miner engine start
aetron-miner engine stop
aetron-miner engine pause     # free the GPU without losing daemon state
aetron-miner engine resume
aetron-miner engine status

env​

The runner's Python environment: the PyTorch stack the compute side needs. The runner binary itself carries no ML stack, so this environment is what makes it able to run at all.

aetron-miner env install  [--manifest <path|url>] [--profile <name>] [--skip-selftest]
aetron-miner env update   [--manifest <path|url>] [--profile <name>]
aetron-miner env status   [--json]
aetron-miner env verify
aetron-miner env rollback
  • install reads a signed version manifest, detects your hardware, picks the matching profile (a CUDA build, Apple Silicon MPS, or CPU), and installs the pinned wheel set. Nothing is resolved on your machine: the lock file lists every package with its hash. --profile forces a profile instead of auto-detection, which is how you test a stack your GPU would not have been given.
  • update builds the new environment beside the current one and switches only after its self-test passes. The old environment stays on disk.
  • status reports the active profile, the installed versions, and the last self-test result. --json makes it machine readable.
  • verify re-runs the runner self-test against the current environment.
  • rollback points current back at the previous environment. It is the way out of a bad update.

--skip-selftest activates an environment that has not proven itself. It exists for debugging and should be treated as such: an environment whose numbers differ from the pinned stack produces results that fail verification.

aetron-miner env install
aetron-miner env status --json
aetron-miner env rollback

config​

Local client settings that do not belong in config.toml. At present this is the HuggingFace token, which speeds up model downloads and is required for gated weights.

aetron-miner config set-hf-token [<token>]
aetron-miner config show-hf-token
aetron-miner config clear-hf-token

Passing the token as an argument works in scripts; on a terminal, omit it and the CLI asks for it with hidden input. show-hf-token prints where the token was resolved from and a masked value, never the token itself. clear-hf-token removes ~/.aetron-miner/hf_token and leaves environment variables and a huggingface-cli login file alone.

wallet​

Keystore management. Every subcommand talks to the running daemon, which holds the unlocked key in memory until it stops. Passwords are read without echo when the terminal is interactive.

aetron-miner wallet generate    [--name <label>]
aetron-miner wallet import-seed [--name <label>]
aetron-miner wallet import-json <json_path> [--name <label>]
aetron-miner wallet unlock
aetron-miner wallet info
  • generate creates a new sr25519 keystore from a random BIP-39 seed and prints the seed phrase once. --name sets the label stored in the keystore metadata and defaults to miner-hotkey.
  • import-seed imports an existing BIP-39 seed phrase of 12 or 24 words, read from stdin, and encrypts it under a password you enter twice.
  • import-json imports a polkadot-js JSON keystore export. It asks for the password the export was encrypted with, then for a new password to store it under locally.
  • unlock decrypts the keystore and hands the key to the daemon, which caches it in memory until it is stopped.
  • info prints the address, whether the keystore is locked or unlocked, and its name.
aetron-miner wallet generate --name my-hotkey
aetron-miner wallet unlock
aetron-miner wallet info

neuronets​

Reads the on-chain Neuronet registry and registers the miner. These commands need a running daemon connected to a node, since the registry is read from the chain.

list​

Lists available Neuronets with the ID, name, both privacy badges (security mode, Standard or Confidential with TEE, and approval mode, Auto, Manual, or Open), stake in AET, used and total slots, the Owner fee percentage, the task kinds, and your own status for that Neuronet under your hotkey.

aetron-miner neuronets list

show​

Details for a single Neuronet: its tasks, miners, economics, and any invitation that applies to you.

aetron-miner neuronets show <id>

register​

Registers the miner in a (neuronet_id, task_id) pair. task_id is positional and defaults to 0. Registration is not free: it burns AET and, when bond enforcement is on, reserves collateral on top. On success the daemon writes the Neuronet ID and task ID into the config. Neuronets in Manual approval mode are invite-only, so registration succeeds only while an invitation is active, which neuronets list shows in your status column.

aetron-miner neuronets register <neuronet_id> [task_id]
aetron-miner neuronets register 3 0      # example

register-prepare​

For a cold/hot split, where the coldkey that pays is not on this machine. It prints the parameters of the burned_register extrinsic for you to sign from your own wallet, while the daemon contributes the signature proving it controls the hotkey. Use it instead of register whenever the coldkey lives elsewhere.

aetron-miner neuronets register-prepare <neuronet_id> [task_id] [--coldkey <ss58>]

--coldkey overrides the coldkey_ss58 value from the config.

deregister​

Leaves a (neuronet_id, task_id) pair. The collateral is not returned on the spot: it enters the unbonding window first, and the registration burn never comes back.

aetron-miner neuronets deregister <neuronet_id> [task_id]

models and datasets​

Both groups manage the local artifact cache and take the same subcommands; the only difference is which kind of artifact they act on. Artifacts are addressed by a hash prefix of at least 6 hex characters.

list​

Shows a table of cached artifacts. It asks the daemon first and falls back to scanning the local cache directory when the daemon is not running, so it works offline.

aetron-miner models list
aetron-miner datasets list

show​

Prints details for a single artifact resolved from its hash prefix.

aetron-miner models show <hash_prefix>

verify​

Re-checks an artifact. The default is a light check over metadata only. With --full it re-hashes every file listed in the manifest with SHA-256, which is slower but catches on-disk corruption.

aetron-miner models verify <hash_prefix> [--full]

delete​

Removes an artifact from the cache after a confirmation prompt. --yes skips the prompt for scripted use.

aetron-miner models delete <hash_prefix> [--yes]

download​

Fetches an artifact into the cache from a source you name. The daemon pulls manifest.json from the base URL, downloads each file, verifies its SHA-256, and publishes the result atomically, so the daemon must be running. --from is required, because the chain does not carry a per-model list of mirrors and the operator has to point at one explicitly. --model-hash turns on an integrity gate: when you pass the expected on-chain model hash, the manifest's Merkle root over files must match it or the download is rejected, which closes the door on a forged mirror.

aetron-miner models download --from <base_url> [--model-hash <hex>]
aetron-miner models list
aetron-miner models verify a1b2c3 --full
aetron-miner models download --from https://host/models/a1b2c3 --model-hash 0xa1b2...
aetron-miner datasets delete a1b2c3 --yes

Where to Go Next​

Last updated on