Skip to content

Latest commit

 

History

History
284 lines (203 loc) · 8.97 KB

02-btcli-basics.md

File metadata and controls

284 lines (203 loc) · 8.97 KB

Tutorial 02 — btcli Basics for Confident Navigation

btcli is your friendly control tower for everything Bittensor—wallets, subnets, validators, axons, you name it. In this tutorial we’ll demystify the command structure, sprinkle in real-world tips, and show how to capture output for dashboards or scripts.

btcli command overview placeholder

Table of Contents

🎯 Learning goals

  • Understand how btcli <object> <action> [flags] fits together.
  • Explore the most useful objects: subnet, wallet, stake, root, axon.
  • Export command output for dashboards, alerting, or automation.
  • Cross-check GPU readiness so CLI commands map to actual hardware.
  • Capture verification commands and keep logs for future troubleshooting.

🧠 Prerequisites

  • Tutorial 01 complete with a working /opt/tensorium/bittensor/.venv.
  • At least one wallet created (even a demo coldkey/hotkey).
  • Internet reachability to Bittensor peers.

💡 Tip: Run this tutorial from inside the venv (tensorium alias) so you don’t need to retype full paths.

1. Command anatomy

btcli <object> <action> [flags]
  • Object — the subsystem (e.g., wallet, subnet, stake, axon).
  • Action — what you want (list, show, new, register, etc.).
  • Flags — context like --wallet-name, --netuid, --json.
# See full help for any object
btcli subnet --help

# Request verbose logs
btcli subnet list -vv

# JSON output (great for jq or scripts)
btcli subnet show --netuid 1 --json

⚠️ Warning: Some actions (like wallet creation) prompt for passphrases. Make sure you’re on a secure terminal before entering secrets.

2. Inspecting subnet data

# Top 10 subnets with summary stats
btcli subnet list --max-rows 10

# Deep dive into netuid 1
btcli subnet show --netuid 1

# Grab neuron details in JSON and pretty-print with jq
btcli subnet neurons --netuid 1 --max-rows 5 --json | jq '.neurons[] | {uid, incentive}'

Key metrics:

  • incentive: Miner rewards per block.
  • dividends: Delegator rewards per block.
  • tempo: Target block time (lower = faster updates).
  • difficulty: Indicates the mining effort required.

subnet dashboard placeholder

3. Wallet operations

# List coldkeys/hotkeys on this host
btcli wallet list

# Create a new wallet + default hotkey (follow prompts)
btcli wallet new --wallet-name tensorium --wallet-hotkey default

# Check balances using a friendly name
btcli wallet balance --wallet-name tensorium

# Export coldkey for offline backup (encrypt afterward!)
btcli wallet export-coldkey \
  --wallet-name tensorium \
  --output-file ~/tensorium-coldkey.json

💡 Tip: Immediately move exported coldkeys to encrypted storage (GPG, Bitwarden, 1Password). Delete plaintext copies: shred -u ~/tensorium-coldkey.json.

4. Delegation and staking

# Delegate 20 TAO to a trusted validator
btcli stake add-delegation \
  --wallet-name tensorium \
  --hotkey default \
  --delegate 6hq7RMnkJUXJ3qvBAYCq... \
  --amount 20

# Inspect current stake positions
btcli stake list --wallet-name tensorium --json | jq '.stakes[] | {delegate, amount}'

# Remove delegation (partial or full)
btcli stake remove-delegation \
  --delegate 6hq7RMnkJUXJ3qvBAYCq... \
  --amount 20

⚠️ Warning: Delegations may incur lock periods. Always double-check the validator’s commission and track record with btcli stake show --delegate <ss58>.

5. Root network monitoring

Validators keep an eye on the root network to ensure consensus stays healthy.

# Count active neurons (great for detecting major outages)
btcli root metagraph --netuid 0 --json | jq '.neurons | length'

# Tabular view with trust/consensus scores
btcli root network --netuid 0 --max-rows 10

Important columns:

  • trust: Weight assigned by other validators.
  • consensus: Agreement level with network majority.
  • validator_permit: Whether the neuron can validate the root chain.

6. Axon health for miners

Axons are the endpoints miners expose. Validate yours before opening firewall ports.

# Inspect your axon registration status
btcli axon info --netuid 1 --wallet-name tensorium --wallet-hotkey default

# Ping a remote axon directly (helpful for debugging connections)
btcli axon ping --address 1.2.3.4 --port 8091

Pair this with scripts/detect_gpu.sh to ensure the hardware layer is ready.

7. Optional: GPU helpers (quick recap)

If you skipped the GPU section in Tutorial 01, here’s the condensed version relevant to btcli monitoring:

sudo ubuntu-drivers autoinstall    # pick best NVIDIA driver
sudo reboot

# After reboot
nvidia-smi                         # verify driver + CUDA
scripts/detect_gpu.sh              # Tensorium helper (logs nicely)

When exporting miner statistics, include GPU details so dashboards correlate incentives with hardware performance.

8. Exporting JSON for dashboards

# Snapshot subnet neurons to JSON
btcli subnet neurons --netuid 1 --json > /opt/tensorium/logs/subnet-1.json

# Hourly cron job (crontab -e)
0 * * * * source /opt/tensorium/bittensor/.venv/bin/activate && \
btcli subnet neurons --netuid 1 --json > /opt/tensorium/logs/subnet-1-$(date +\%H%M).json

Suggested pipeline:

  1. btcli ... --json → jq for filtering.
  2. Push to Prometheus Pushgateway or drop into S3/log storage.
  3. Visualize in Grafana (drag JSON data source or ingest via Loki).

dashboard placeholder

9. Verification & logging checklist

Whenever you finish a btcli workflow, run these quick commands:

# Ensure btcli still responds
btcli --version

# Confirm wallets accessible
btcli wallet list --wallet-name tensorium

# Minimal subnet check
btcli subnet list --max-rows 3

# Append to your logbook
echo "$(date -u) btcli sanity check OK" >> /opt/tensorium/logs/btcli.log

If any command stalls or errors, note the timestamp and what changed (new firewall rule, VPN, etc.). Observability begins with honest notes.

📘 Example Output

(.venv) $ btcli subnet show --netuid 1
Subnet 1 — nakamoto
Tempo: 12    Difficulty: 23.4    Validators: 128    Miners: 256
 ├─ Incentive: 18.44 %
 ├─ Dividends: 11.02 %
 ├─ Emission: 220 TAO / day
 └─ Last update: 2025-11-17 08:52:10 UTC

(.venv) $ btcli wallet balance --wallet-name tensorium
Wallet: tensorium
 ├─ Coldkey: 5DyV...sSxk
 ├─ Hotkeys:
 │   • default — 12.5 TAO (liquid), 40 TAO (staked)
 └─ Unclaimed rewards: 1.2 TAO

(.venv) $ btcli stake list --wallet-name tensorium --json | jq '.stakes[0]'
{
  "delegate": "6hq7RMnkJUXJ3qvBAYCq...",
  "amount": "20.0000 TAO",
  "apy": "18.02",
  "last_update": "2025-11-16T21:05:44Z"
}

✅ Summary

  • Treat btcli like a structured API: object + action + flags.
  • Export JSON early so dashboards and monitoring pipelines can reuse the same data.
  • Keep wallet backups encrypted and offline; hotkeys are easy to replace, coldkeys are not.
  • Verification snippets (btcli --version, subnet checks) make troubleshooting much faster.

📝 Review questions

  1. What is the general syntax of a btcli command, and what does each component represent?
  2. Which subcommand reveals validator incentives for a specific subnet, and how can you export the data to JSON?
  3. What steps do you take to back up a cold key, and why should it never stay on the mining host?
  4. How do you confirm that a delegation was added correctly?
  5. Which metrics from btcli root metagraph tell you about overall network health?

Answers

  1. btcli <object> <action> [flags]; the object is the domain (wallet/subnet), the action is the operation (list/show), and flags supply parameters like wallet names or netuids.
  2. btcli subnet show --netuid <id> plus --json (and optionally piping to jq or redirecting to a file).
  3. Run btcli wallet export-coldkey --wallet-name <name> --output-file <path> and move the file to encrypted offline storage; losing the cold key compromises ownership.
  4. Use btcli stake list --wallet-name <name> or --json to confirm the delegate address and amount now appear.
  5. trust, consensus, validator_permit, and total neuron counts highlight participation and agreement levels.