llm.txt

# agcli — LLM/Agent Reference

## Tier 1: Quick Reference Card

### What is agcli?
Rust CLI + SDK for Bittensor. Manage wallets, stake TAO, transfer tokens, register on subnets, set weights, query chain state, monitor subnets. All commands: `--output json|csv`, `--batch` for hard errors, `--yes` to skip prompts.

### Install
```bash
cargo install --git https://github.com/unconst/agcli
```

### Common Tasks (intent → command)
```
Check my balance          → agcli balance   # e2e Phase 20 `balance_preflight` in tests/e2e_test.rs
Check someone's balance   → agcli --output json balance --address 5Gx...
List all subnets          → agcli --output json subnet list
Subnet summary (pools)    → agcli subnet show --netuid 1   # alias: subnet info
View subnet metagraph     → agcli --output json subnet metagraph --netuid 1   # unknown netuid → exit 12 (validation), like subnet show
Check one neuron          → agcli --output json subnet metagraph --netuid 1 --uid 0
Subnet hyperparameters    → agcli subnet hyperparams --netuid 1 [--at-block N]   # unknown netuid → exit 12 (validation), like subnet show
Registration cost         → agcli subnet cost --netuid 1   # unknown netuid → exit 12 (validation), like subnet show
Subnet health check       → agcli subnet health --netuid 1   # unknown netuid → exit 12, like subnet show/cost
Subnet liquidity/AMM      → agcli subnet liquidity --netuid 1
Live tempo countdown      → agcli subnet watch --netuid 1
Snipe registration slot   → agcli subnet snipe --netuid 97 --fast --max-cost 2.0
Monitor registration      → agcli subnet snipe --netuid 97 --watch --max-cost 1.5
Monitor subnet UIDs       → agcli subnet monitor --netuid 1 --json
Per-UID emissions         → agcli subnet emissions --netuid 1   # unknown netuid → exit 12, like subnet show/cost
Pending weight commits    → agcli subnet commits --netuid 1
Create wallet             → agcli wallet create --name w1 --password p --yes
Import from mnemonic      → agcli wallet import --name w1 --mnemonic "..." --password p
List wallets              → agcli --output json wallet list
Stake TAO on subnet       → agcli stake add --amount 10 --netuid 1 --password p --yes   # e2e Phase 20 `stake_add_preflight` in tests/e2e_test.rs; full add/remove Phase 8 `test_add_remove_stake`
Unstake                   → agcli stake remove --amount 5 --netuid 1 --password p --yes   # e2e Phase 20 `stake_remove_preflight` in tests/e2e_test.rs; full add/remove Phase 8 `test_add_remove_stake`
Move alpha SN→SN         → agcli stake move --amount 1 --from 1 --to 2 --password p --yes   # e2e Phase 20 `stake_move_preflight` in tests/e2e_test.rs
Swap alpha SN→SN (AMM)    → agcli stake swap --amount 1 --from 1 --to 2 --password p --yes   # e2e Phase 20 `stake_swap_preflight` in tests/e2e_test.rs
Unstake all (one hotkey)  → agcli stake unstake-all --password p --yes   # e2e Phase 20 `stake_unstake_all_preflight` in tests/e2e_test.rs
View all stakes           → agcli --output json stake list   # e2e Phase 20 `stake_list_preflight` in tests/e2e_test.rs
Full portfolio            → agcli --output json view portfolio   # e2e Phase 20 `view_portfolio_preflight` in tests/e2e_test.rs; docs/commands/view.md
Transfer TAO              → agcli transfer --dest 5FHn... --amount 10 --password p --yes   # e2e Phase 20 `transfer_preflight`; see docs/commands/transfer.md
Show on-chain weights     → agcli weights show --netuid 1
Set weights               → agcli weights set --netuid 1 --weights "0:100,1:200" --dry-run
Commit weights (CR p1)    → agcli weights commit --netuid 1 --weights "0:100,1:200"
Reveal weights (CR p2)    → agcli weights reveal --netuid 1 --weights "0:100,1:200" --salt mysecret
Commit-reveal weights     → agcli weights commit-reveal --netuid 1 --weights "0:100,1:200" --wait
Weight commit status      → agcli weights status --netuid 1
Dynamic TAO prices        → agcli --output json view dynamic
Simulate TAO→Alpha swap   → agcli --output json view swap-sim --netuid 1 --tao 10
Subscribe to events       → agcli subscribe events --filter staking --netuid 1
Historical query          → agcli --network archive subnet list --at-block 3500000
Stream blocks             → agcli subscribe blocks
Explain a concept         → agcli explain --topic tempo
Weight flow cheat sheet   → agcli explain --topic weights (aliases: settingweights, setweights); `--full` → `docs/commands/weights.md` when present
Alpha↔TAO conversion      → agcli utils convert --tao 10 --netuid 1
                          → agcli utils convert --alpha 500 --netuid 1
Set commitment (miner)    → agcli commitment set --netuid 1 --data "endpoint:http://..."
Read commitments          → agcli --output json commitment get --netuid 1 --hotkey-address 5H...
All commitments on SN     → agcli --output json commitment list --netuid 1
Set hyperparam (owner)    → agcli subnet set-param --netuid 1 --param tempo --value 100
Start local chain         → agcli localnet start --output json
Stop local chain          → agcli localnet stop
Local chain status        → agcli localnet status --output json
Reset local chain         → agcli localnet reset
Local chain logs          → agcli localnet logs --tail 100
Smoke-check install + RPC → agcli doctor [--network local]   # per-row OK/FAIL; process exit 0 unless clap error; see docs/commands/doctor.md
Scaffold test env         → agcli localnet scaffold --output json
Scaffold with config      → agcli localnet scaffold --config scaffold.toml --output json
Set tempo (sudo)          → agcli admin set-tempo --netuid 1 --tempo 100 --sudo-key //Alice --network local
Set max validators (sudo) → agcli admin set-max-validators --netuid 1 --max 8 --sudo-key //Alice --network local
Set min weights (sudo)    → agcli admin set-min-weights --netuid 1 --min 1 --sudo-key //Alice --network local
Set weights rate (sudo)   → agcli admin set-weights-rate-limit --netuid 1 --limit 0 --sudo-key //Alice --network local
Disable commit-reveal     → agcli admin set-commit-reveal --netuid 1 --enabled false --sudo-key //Alice --network local
Generic admin call        → agcli admin raw --call sudo_set_bonds_moving_average --args '[1, 900000]' --sudo-key //Alice --network local
List admin params         → agcli admin list --output json
```

### Global Flags
| Flag | Env | Short |
|------|-----|-------|
| `--output json\|csv\|table` | — | Machine-readable output |
| `--pretty` | — | Pretty-print JSON |
| `--batch` | `AGCLI_BATCH=1` | Hard-error mode (no stdin) |
| `--yes` / `-y` | `AGCLI_YES=1` | Skip confirmations |
| `--password PW` | `AGCLI_PASSWORD` | Wallet password |
| `--network NET` | `AGCLI_NETWORK` | finney\|test\|local\|archive |
| `--endpoint URL` | `AGCLI_ENDPOINT` | Custom WS endpoint |
| `-w NAME` | `AGCLI_WALLET` | Wallet name |
| `--hotkey` / `--hotkey-name NAME` | `AGCLI_HOTKEY` | Wallet hotkey file name |
| `--wallet-dir DIR` | `AGCLI_WALLET_DIR` | Wallet dir |
| `--proxy SS58` | `AGCLI_PROXY` | Proxy account |
| `--live [SECS]` | — | Live polling (default 12s) |
| `--dry-run` | — | Preview without signing |
| `--mev` | — | ML-KEM-768 encrypted submission |
| `--at-block N` | — | Historical query |
| `--timeout SECS` | — | Operation timeout |
| `--verbose` / `-v` | — | Show connection info |

### Exit Codes
- 0 = success, 1 = error
- Batch/JSON mode: `{"error": true, "message": "..."}` on stderr

### Key Concepts
- **TAO** = native token, 1 TAO = 1e9 RAO (u64)
- **Subnet** = independent network, netuid (u16), 0 = root
- **Coldkey** = encrypted signing key, **Hotkey** = automated plaintext key
- **Weights** = validators score miners, u16 values normalized to [0,1]
- **Dynamic TAO** = each subnet has alpha token with AMM (constant-product pool)
- **Commit-reveal** = privacy weight setting (blake2 hash → reveal)
- **Commitment** = miner endpoint publication (replaces Axon)

---

## Tier 2: Full Command Reference

Detailed per-command docs: `docs/commands/*.md` (on-chain behavior, pallet refs, storage keys, events, error codes).

### Command Groups

| Group | File | Key Commands |
|-------|------|-------------|
| Wallet | [wallet.md](commands/wallet.md) | create, list, show, import, sign, verify, derive |
| Balance | [balance.md](commands/balance.md) | one-shot / `--at-block` / `--watch` + `--threshold`; e2e Phase 20 `balance_preflight` |
| Transfer | [transfer.md](commands/transfer.md) | `transfer` (allow_death), `transfer-all`, `transfer-keep-alive`; e2e Phase 20 `transfer_preflight` + Phase 2 `test_transfer` + Phase 16 `test_transfer_all` |
| Stake | [stake.md](commands/stake.md) | **`stake list`** (e2e `stake_list_preflight`); **`stake add`** (e2e `stake_add_preflight` + Phase 8 `test_add_remove_stake`); **`stake remove`** (e2e `stake_remove_preflight` + same Phase 8); **`stake move`** (e2e `stake_move_preflight`); **`stake swap`** (e2e `stake_swap_preflight`); **`stake unstake-all`** (e2e `stake_unstake_all_preflight`); wizard, limits, childkeys |
| Subnet | [subnet.md](commands/subnet.md) | list, show, metagraph, register, register-leased, register-neuron, pow, snipe, hyperparams, watch, monitor, health, emissions, cost, liquidity, set-param, set-symbol, trim, terminate-lease |
| Weights | [weights.md](commands/weights.md) | show, set, commit, reveal, commit-reveal, status |
| Commitment | [commitment.md](commands/commitment.md) | set, get, list |
| View | [view.md](commands/view.md) | portfolio, dynamic, network, neuron, validators, account, swap-sim, analytics |
| Delegate | [delegate.md](commands/delegate.md) | list, show, decrease-take, increase-take |
| Identity | [identity.md](commands/identity.md) | show, set, set-subnet |
| Root | [root.md](commands/root.md) | register, weights |
| Serve | [serve.md](commands/serve.md) | axon |
| Subscribe | [subscribe.md](commands/subscribe.md) | blocks, events |
| Config | [config.md](commands/config.md) | show, set, unset, path |
| Block | [block.md](commands/block.md) | latest, info, range |
| Diff | [diff.md](commands/diff.md) | portfolio, subnet, network, metagraph |
| Proxy | [proxy.md](commands/proxy.md) | add, remove, list |
| Multisig | [multisig.md](commands/multisig.md) | address, submit, approve |
| Batch | [batch.md](commands/batch.md) | --file (atomic/non-atomic) |
| Swap | [swap.md](commands/swap.md) | hotkey, coldkey |
| Crowdloan | [crowdloan.md](commands/crowdloan.md) | contribute, withdraw, finalize |
| Localnet | [localnet.md](commands/localnet.md) | start, stop, status, reset, logs, scaffold |
| Admin | [admin.md](commands/admin.md) | set-tempo, set-max-validators, set-max-uids, set-min-weights, set-weights-rate-limit, set-commit-reveal, raw, list |
| Doctor | [doctor.md](commands/doctor.md) | top-level smoke: version, network, WS connect, block height, subnet count, 3×RPC ping, disk cache, default wallet |
| Utils | [utils.md](commands/utils.md) | convert (alpha↔TAO), latency; top-level `completions`, `update` (see utils.md) |
| Explain | [explain.md](commands/explain.md) | 32 built-in topics |

### Agent / Non-Interactive Mode

Every command is fully scriptable with zero stdin blocking when all required args are provided. All flags use `--flag` syntax (no positional args).

```bash
# Hard-error mode: missing required args = error with hint, never prompt stdin
agcli --batch --output json wallet create --name w1 --password mypass --yes

# Persistent batch mode via config
agcli config set --key batch --value true

# Spending limits for safety
agcli config set --key spending_limit.97 --value 100.0    # Max 100 TAO on SN97
agcli config set --key spending_limit.* --value 500.0     # Global max
```

### Wallet Commands
- `wallet create --name NAME [--password PW]` → `{"name","coldkey","hotkey"}`
- `wallet list` → `[{"name","coldkey"}]`
- `wallet show [--all]` → `[{"name","coldkey","hotkeys":[...]}]`
- `wallet import --name NAME [--mnemonic "..."] [--password PW]` → `{"name","coldkey"}`
- `wallet regen-coldkey [--mnemonic "..."] [--password PW]` → `{"coldkey"}`
- `wallet regen-hotkey --name NAME [--mnemonic "..."]` → `{"name","hotkey"}`
- `wallet new-hotkey --name NAME` → `{"name","hotkey"}`
- `wallet sign --message MSG [--password PW]` → `{"signer","message","signature"}`
- `wallet verify --message MSG --signature 0x... [--signer SS58]` → exit 0=valid
- `wallet derive --input INPUT` → SS58 from pubkey/mnemonic
- Reads Python bittensor-wallet keyfiles (NaCl SecretBox + JSON)

### Balance & Transfer
- `balance [--address SS58]` → `{"address","balance_rao","balance_tao"}`
- `balance --watch [N] --threshold T` → streaming JSON with alerts
- `transfer --dest SS58 --amount TAO` → `{"tx_hash","message"}`
- `transfer-all --dest SS58 [--keep-alive]`

### Staking
- `stake add --amount AMT --netuid N [--hotkey-address SS58] [--max-slippage PCT]` → validate_netuid → validate_amount (`stake amount`) → check_spending_limit → unlock → get_balance → optional `try_join` slippage sim (`current_alpha_price` + `sim_swap_tao_for_alpha`); e2e `stake_add_preflight`
- `stake remove --amount AMT --netuid N [--hotkey-address SS58] [--max-slippage PCT]` → validate_netuid → validate_amount (`unstake amount`) → unlock → optional `try_join` (`current_alpha_price` + `sim_swap_alpha_for_tao`); no spending-limit preflight; e2e `stake_remove_preflight`
- `stake list [--address SS58] [--at-block N]` → JSON array of `StakeInfo` (latest or pinned); archive for old heights; e2e `stake_list_preflight`
- `stake move --amount AMT --from SRC --to DST [--hotkey-address SS58]` → validate_netuid×2 → reject same from/to → validate_amount (`move amount`) → check_spending_limit(**destination** `--to`) → unlock → move_stake; no balance/slippage RPC preflight; e2e `stake_move_preflight`
- `stake swap --amount AMT --from SRC --to DST [--hotkey-address SS58]` → same pre-wallet order as `stake move` but **`swap amount`** + **`swap_stake_mev`**; e2e `stake_swap_preflight`
- `stake unstake-all [--hotkey-address SS58]` → **`unlock_and_resolve`** only (optional **`validate_ss58`(`hotkey-address`)**); no netuid/amount/spending-limit pre-read; e2e `stake_unstake_all_preflight`
- `stake claim-root --netuid N` (uses wallet hotkey)
- `stake add-limit / remove-limit --amount AMT --netuid N --price P [--partial]`
- `stake childkey-take --take PCT --netuid N`
- `stake set-children --netuid N --children "proportion:hotkey,..."`
- `stake recycle-alpha / burn-alpha --amount AMT --netuid N`
- `stake unstake-all-alpha` — all subnets
- `stake wizard [--netuid N] [--amount X]` — guided staking

### Subnets
- `subnet list [--at-block N]` → `[{"netuid","name","n","max_n","tempo","emission","burn_rao","owner"}]`; no `--netuid` / no exit **12** for unknown SN; e2e `subnet_list` calls `list_subnets` (`pin_latest` + `get_all_subnets_at_block` + `get_all_dynamic_info_at_block`)
- `subnet show --netuid N [--at-block N]` → full details + Dynamic TAO pricing
- `subnet metagraph --netuid N [--uid UID] [--full] [--save] [--at-block N]`
- `subnet hyperparams --netuid N [--at-block B]` → all hyperparameters
- `subnet register` — create new subnet (burn lock cost); no `--netuid` / no exit **12**; lock amount via `subnet create-cost`; e2e **`subnet_register_plain`** reuses same `get_subnet_registration_cost` log as **`subnet_create_cost`**
- `subnet register-with-identity --name ...` — register + subnet identity in one call; optional `--github` / `--url` / etc.; pre-unlock validation like `identity set-subnet`; no `--netuid`; e2e `subnet_register_with_identity` uses `get_subnet_identity`
- `subnet create-cost` — read-only subnet creation lock (TAO) for `register` / `register-leased`; no `--netuid`; RPC/runtime API read errors only
- `subnet register-leased [--end-block N]` — create leased subnet; no unknown-netuid preflight; lock amount via `subnet create-cost`; pair with `subnet terminate-lease`
- `subnet register-neuron --netuid N` — burn registration; unknown netuid → exit **12** before hotkey unlock (same as `subnet show`)
- `subnet pow --netuid N [--threads 8]` — POW registration; unknown netuid → exit **12** before hotkey unlock; `--threads 0` → exit **1**; no solution found → message, exit **0**
- `subnet dissolve --netuid N` — schedule dissolve (owner); unknown netuid → exit **12** before wallet; confirm unless `--yes`; decline → exit **0**
- `subnet root-dissolve --netuid N` — root-only removal; same **`require_subnet_exists`** preflight → exit **12** before wallet
- `subnet terminate-lease --netuid N` — owner ends a leased subnet early; same preflight → exit **12** before wallet
- `subnet watch --netuid N [--interval 12]` — live tempo / rate-limit TUI (latest head each tick); unknown netuid → exit **12** like `subnet show`; no `--output json`
- `subnet monitor --netuid N [--interval 24] [--json]` — metagraph diff / event stream (latest head each tick); unknown netuid → exit **12** like `subnet show`; JSON via `--json` on the subcommand (not global `--output json`)
- `subnet health --netuid N` — miner/validator status
- `subnet emissions --netuid N` — per-UID emissions
- `subnet cost --netuid N` — registration cost
- `subnet liquidity [--netuid N]` — AMM depth, slippage estimates; with `--netuid`, unknown SN → exit **12** like `subnet show`; omit `--netuid` to scan all subnets with pool depth
- `subnet commits --netuid N [--hotkey-address SS58]` — pending weight commits; unknown netuid → exit **12** like `subnet show`; if CR disabled → notice / JSON and exit **0**
- `subnet set-param --netuid N --param list|NAME [--value V]` — list catalog (`--output json` for list) or set hyperparam (owner); unknown netuid → exit **12** before list / wallet (same as `subnet show`)
- `subnet set-symbol --netuid N --symbol "SYM"` — set token symbol (owner); invalid symbol → exit **1**; unknown netuid → exit **12** before wallet (same as `subnet set-param`)
- `subnet trim --netuid N --max-uids M` — lower max UIDs / trim metagraph capacity (owner); unknown netuid → exit **12** before wallet; confirm prompt unless `--yes`
- `subnet probe --netuid N [--uids "0,1,2"]` — HTTP axon reachability (`GET /`); unknown netuid → exit **12** like `subnet show`; pinned lite+full neuron snapshot
- `subnet check-start --netuid N` — read-only: active flag, neuron count, `can_start`, tempo; unknown netuid → exit **12** like `subnet show`
- `subnet start --netuid N` — owner starts emission schedule; unknown netuid → exit **12** before wallet (same preflight as `check-start`)
- `subnet snipe --netuid N [--fast] [--watch] [--all-hotkeys] [--max-cost TAO] [--max-attempts N]` — block-level registration sniper; unknown netuid → exit **12** before streaming / wallet
- `subnet cache-list|cache-load|cache-diff|cache-prune --netuid N` — metagraph disk snapshots (`metagraph --save`); unknown netuid → exit **12** like `subnet show`; missing cache files → tip / empty JSON and exit **0** (see `docs/commands/subnet.md`)
- `subnet emission-split --netuid N` — mechanism emission weights (`MechanismEmissionSplit`); unknown netuid → exit **12** like `subnet show`; no custom split → notice or JSON `configured: false`, exit **0**
- `subnet mechanism-count --netuid N` — `MechanismCountCurrent` (default 1 if unset); unknown netuid → exit **12** like `subnet show`
- `subnet set-mechanism-count --netuid N --count K` — owner `sudo_set_mechanism_count`; unknown netuid → exit **12** before wallet; e2e **`subnet_owner_mechanism_writes`**
- `subnet set-emission-split --netuid N --weights "a,b,..."` — owner `sudo_set_mechanism_emission_split`; invalid weights → exit **1** before wallet; unknown netuid → **12** after parse; confirm unless `--yes`

### Weights
- `weights show --netuid N [--hotkey-address SS58] [--limit L]` — read-only on-chain weights; no wallet; unknown SN → same bail as `subnet show` (exit **12**); flaky hyperparams RPC → warn and continue; e2e **`weights_show_preflight`** + read bundle in Phase 37 `test_all_weights`
- `weights set --netuid N --weights "uid:weight,..." [--version-key K] [--dry-run]` — unknown SN → same "Subnet N not found" + `subnet list` as `subnet show` (exit **12**); e2e `weights_set_preflight` + Phase 7 `set_weights`; `--dry-run` still unlocks wallet for stake check; on-chain `WeightVecLengthIsLow` when vector shorter than `min_allowed_weights` (see `subnet hyperparams`)
- `weights commit --netuid N --weights "uid:weight,..." [--salt S]` — unknown SN → same bail as `subnet show` (exit **12**) before wallet; e2e **`weights_commit_preflight`** + Phase 17 `commit_weights` (no pre-submit stake check unlike `weights set`)
- `weights reveal --netuid N --weights "uid:weight,..." --salt S` — same unknown-SN pre-check as `commit`; e2e **`weights_reveal_preflight`** + Phase 17 `reveal_weights` (`test_reveal_weights_rejected_without_prior_commit` and follow-on reveal cases)
- `weights commit-reveal --netuid N --weights "uid:weight,..." [--version-key K] [--wait]` — atomic commit+wait+reveal (or `set_weights` when CR off); unknown SN → exit **12** before wallet; hyperparams RPC failure aborts (unlike commit/reveal/status); e2e **`weights_commit_reveal_preflight`** in Phase 17 `test_commit_weights_rejected_when_commit_reveal_disabled`
- `weights status --netuid N` — pending commit-reveal rows for default hotkey (`get_weight_commits` + head + hyperparams + `reveal_period_epochs`); unknown SN → same hyperparams preflight (exit **12**) before wallet; RPC warn+continue on preflight; e2e **`weights_status_preflight`** in Phase 17 `test_reveal_weights_rejected_without_prior_commit`
- `weights commit-timelocked --netuid N --weights "..." --round R` — drand timelock commit; unknown SN → exit **12** before wallet (same hyperparams preflight as `weights commit`; RPC warn+continue); SDK reads `CommitRevealWeightsVersion` at submit; e2e **`weights_commit_timelocked_preflight`** in Phase 17 `test_commit_timelocked_weights_rejected_when_incorrect_commit_reveal_version`; on-chain **111** = version mismatch (rare with current CLI)
- `weights set-mechanism --netuid N --mechanism-id M --weights "..." [--version-key K]` — `set_mechanism_weights`; unknown SN → exit **12** before wallet (`require_subnet_exists_for_weights_cmd`; RPC warn+continue); **`--dry-run`** = JSON only, no wallet; e2e **`weights_set_mechanism_preflight`** in Phase 5 `test_set_mechanism_weights`
- `weights commit-mechanism --netuid N --mechanism-id M --hash H` — `commit_mechanism_weights`; same preflight as `set-mechanism`; **`H`** = 32-byte hex (blake2 over uids+weights+salt like `weights commit`); invalid length/hex → exit **1** before RPC; e2e **`weights_commit_mechanism_preflight`** in Phase 5 `test_commit_mechanism_weights`
- `weights reveal-mechanism --netuid N --mechanism-id M --weights "..." --salt S [--version-key K]` — `reveal_mechanism_weights`; same preflight as `set-mechanism` / `commit-mechanism`; **`S`** → little-endian u16 pairs like **`weights reveal`**; bad **`--weights`** → exit **1** before RPC; e2e **`weights_reveal_mechanism_preflight`** in Phase 5 `test_reveal_mechanism_weights`

### Block
- `block latest` — read-only head (no wallet); `get_block_number` → `get_block_hash` → extrinsic count + timestamp; e2e **`block_latest_preflight`** in Phase 20 `test_block_queries`; network **10** / timeout **15** / generic **1**; head \> `u32::MAX` → **1** (theoretical)
- `block info --number N` — `get_block_hash` → header + extrinsic count + timestamp; e2e **`block_info_preflight`** in Phase 20 `test_block_queries`; same exit classification as `block latest`
- `block range --from A --to B` — local span ≤1000 and `from` ≤ `to` (else exit **1**); concurrent `get_block_hash` then concurrent per-block ext+timestamp; e2e **`block_range_preflight`** in Phase 20 `test_block_queries`

### Commitment (Miner Endpoints)
- `commitment set --netuid N --data "key:value,..."` — publish miner commitment
- `commitment get --netuid N --hotkey-address SS58` → `{"hotkey","netuid","data"}`
- `commitment list --netuid N` → `[{"hotkey","data"}]`

### View / Query
- `view portfolio [--address SS58]` → full stake portfolio with prices
- `view dynamic` → Dynamic TAO prices, pools, volumes, emissions
- `view network` → block, issuance, stake, emission
- `view neuron --netuid N --uid UID` → full neuron detail
- `view validators [--netuid N] [--limit 50]` → top validators
- `view history [--address SS58] [--limit 20]` → recent extrinsics (Subscan)
- `view account [--address SS58]` → comprehensive account explorer
- `view subnet-analytics --netuid N` → detailed subnet analysis
- `view staking-analytics [--address SS58]` → APY estimates
- `view swap-sim --netuid N [--tao X | --alpha X]` → swap simulation
- `view nominations --hotkey-address SS58` → who delegates to a validator

### Identity
- `identity show --address SS58` → on-chain identity
- `identity set --name "..." [--url "..."] [--github "..."]` → set identity
- `identity set-subnet --netuid N --name "..." [--url "..."]` → subnet identity

### Other Commands
- `delegate list/show/decrease-take/increase-take` — validator delegation
- `root register / root weights` — root network (SN0)
- `serve axon --netuid N --ip IP --port PORT` — miner endpoint
- `subscribe blocks / events [--filter F] [--netuid N] [--account SS58]` — WebSocket finalized stream; events: filters incl. delegation, keys, swap, governance, crowdloan; invalid `--filter` → exit **12**; e2e Phase 26 `test_subscribe_blocks` + `test_subscribe_events_preflight` (`docs/commands/subscribe.md`)
- `proxy add/remove/list` — proxy account delegation
- `multisig address/submit/approve` — multi-signature
- `swap hotkey/coldkey` — key rotation
- `batch --file calls.json [--no-atomic]` — bulk extrinsics
- `crowdloan contribute/withdraw/finalize`
- `config show/set/unset/path` — persistent settings
- `block latest / block info --number N / block range` — block explorer
- `diff portfolio|subnet|network|metagraph --block1 A --block2 B` — historical comparison at two heights (`--netuid` on subnet/metagraph); archive endpoint if pruned; e2e Phase 20 `test_diff_queries` (`diff_*_preflight` logs)
- `utils convert --tao X --netuid N / --alpha X --netuid N` — alpha↔TAO conversion
- `utils latency` — endpoint latency test
- `completions --shell bash|zsh|fish` — shell completions
- `update` — self-update
- `doctor` — diagnostic checks
- `explain [--topic T]` — 32 built-in concept explanations

### Localnet (Local Chain Management)
- `localnet start [--image TAG] [--port N] [--container NAME] [--wait false] [--timeout 120]` → `{"status","container_name","container_id","image","endpoint","port","block_height","dev_accounts"}`
- `localnet stop [--container NAME]` → `{"status":"stopped","container_name"}`
- `localnet status [--container NAME] [--port N]` → `{"running","container_name","container_id","image","endpoint","block_height"}`
- `localnet reset [--image TAG] [--port N] [--timeout 120]` → `{"status":"reset","container_name","endpoint","block_height"}`
- `localnet logs [--container NAME] [--tail N]`
- `localnet scaffold [--config scaffold.toml] [--image TAG] [--port N] [--no-start]` — one-command test env: start chain + register subnets + fund accounts + set hyperparams + register neurons → JSON manifest
  - Default: 1 subnet (tempo=100, max_val=8), 3 neurons (validator1@1000 TAO, miner1@100 TAO, miner2@100 TAO)
  - Uses TOML config with `[chain]`, `[[subnet]]`, `[[subnet.neuron]]` sections
  - Output: `{"endpoint","container","block_height","subnets":[{"netuid","hyperparams","neurons":[{"name","ss58","seed","uid","balance_tao"}]}]}`

### Admin (Sudo AdminUtils)
- `admin set-tempo --netuid N --tempo T [--sudo-key //Alice] [--network local]`
- `admin set-max-validators --netuid N --max M [--sudo-key //Alice]`
- `admin set-max-uids --netuid N --max M [--sudo-key //Alice]`
- `admin set-immunity-period --netuid N --period P [--sudo-key //Alice]`
- `admin set-min-weights --netuid N --min M [--sudo-key //Alice]`
- `admin set-max-weight-limit --netuid N --limit L [--sudo-key //Alice]`
- `admin set-weights-rate-limit --netuid N --limit L [--sudo-key //Alice]`
- `admin set-commit-reveal --netuid N --enabled true|false [--sudo-key //Alice]`
- `admin set-difficulty --netuid N --difficulty D [--sudo-key //Alice]`
- `admin set-activity-cutoff --netuid N --cutoff C [--sudo-key //Alice]`
- `admin raw --call EXTRINSIC --args '[N, V]' [--sudo-key //Alice]` — generic escape hatch
- `admin list` → all known AdminUtils parameters with descriptions and arg types

### Live Mode
```bash
agcli --live view dynamic          # poll prices with delta tracking
agcli --live 30 subnet metagraph --netuid 1  # neuron changes every 30s
agcli --live view portfolio        # watch portfolio
```

### Historical Queries (--at-block)
12 commands support `--at-block N` (use `--network archive` for old blocks):
balance, stake list, subnet list/show/metagraph, view portfolio/network/dynamic/neuron/validators/account

### Output Formats
```bash
agcli --output json subnet list            # JSON array
agcli --output json --pretty view dynamic  # pretty-printed JSON
agcli --output csv view dynamic            # CSV
agcli --output csv subnet metagraph --netuid 1
```

### Error Handling
Batch/JSON: structured `{"error": true, "message": "..."}` on stderr. Exit 1.

### Spending Limits
```bash
agcli config set --key spending_limit.97 --value 100.0   # per-subnet
agcli config set --key spending_limit.* --value 500.0     # global
```

### SDK Usage (Rust)
```rust
use agcli::{Client, Config, Wallet, Balance};
let client = Client::connect("wss://entrypoint-finney.opentensor.ai:443").await?;
let balance = client.get_balance_ss58("5Gx...").await?;
let subnets = client.get_all_subnets().await?;
let metagraph = client.get_metagraph(1.into()).await?;

// Localnet SDK
use agcli::localnet::{self, LocalnetConfig};
let info = localnet::start(&LocalnetConfig::default()).await?;  // start Docker chain
let status = localnet::status("agcli_localnet", 9944).await?;   // check status
localnet::stop("agcli_localnet")?;                               // stop chain

// Scaffold SDK — one call for full test environment
use agcli::scaffold::{self, ScaffoldConfig};
let result = scaffold::run(&ScaffoldConfig::default()).await?;
// result.endpoint, result.subnets[0].netuid, result.subnets[0].neurons[0].ss58

// Admin SDK
use agcli::admin;
let alice = sp_core::sr25519::Pair::from_string("//Alice", None)?;
admin::set_tempo(&client, &alice, 1, 100).await?;
admin::set_max_allowed_validators(&client, &alice, 1, 8).await?;
admin::raw_admin_call(&client, &alice, "sudo_set_bonds_moving_average", vec![Value::u128(1), Value::u128(900000)]).await?;
```

### Networks
| Name | URL |
|------|-----|
| finney | wss://entrypoint-finney.opentensor.ai:443 |
| test | wss://test.finney.opentensor.ai:443 |
| local | ws://127.0.0.1:9944 |
| archive | wss://bittensor-finney.api.onfinality.io/public-ws |