name: btcli
description: This skill should be used when interacting with the Bittensor network via CLI, managing wallets and keys, registering miners or validators, staking TAO, or checking subnet status. Essential for all Bittensor network operations.

Bittensor CLI (btcli)

Overview

btcli is the command-line interface for interacting with the Bittensor network. It handles wallet management, subnet registration, staking, and all blockchain operations needed for mining and validation.

When to Use This Skill

• Creating or managing Bittensor wallets
• Registering as a miner or validator on a subnet
• Staking or unstaking TAO
• Checking balances, metagraph, or subnet status
• Managing coldkeys and hotkeys
• Transferring TAO between wallets

Installation

pip (Recommended)

pip install bittensor-cli

Homebrew (macOS/Linux)

brew install btcli

From Source

git clone https://github.com/opentensor/btcli.git
cd btcli
pip3 install .

Verify Installation

btcli --version

Requirements: Python 3.9-3.12

Quick Reference

Command Structure

btcli <command> <subcommand> [options]

Main Commands

Common Options

--wallet.name <name>     # Wallet/coldkey name
--wallet.hotkey <name>   # Hotkey name
--netuid <id>            # Subnet ID
--network <name>         # Network (finney, test, local)
--no-prompt              # Skip confirmations
--json-output            # JSON format output

Core Workflows

1. Wallet Setup (New User)

Create a new wallet with coldkey and hotkey:

btcli wallet create --wallet.name mywallet --wallet.hotkey default

This creates:
- Coldkey at ~/.bittensor/wallets/mywallet/coldkey
- Hotkey at ~/.bittensor/wallets/mywallet/hotkeys/default

CRITICAL: Save your mnemonic phrases securely!
- If someone has your mnemonic, they own your TAO
- You cannot recover wallets without the mnemonic
- Passwords alone are NOT sufficient for recovery

Create coldkey only:

btcli wallet new_coldkey --wallet.name mywallet

Create additional hotkey:

btcli wallet new_hotkey --wallet.name mywallet --wallet.hotkey mining

2. Check Your Wallet

List all wallets:

btcli wallet list

Check balance:

btcli wallet balance --wallet.name mywallet

Check balance for all wallets:

btcli wallet balance --all

Get wallet address (SS58):

btcli wallet address --wallet.name mywallet

3. Register on a Subnet

Check available subnets:

btcli subnets list

Register on a subnet:

btcli subnet register \
  --netuid <subnet_id> \
  --wallet.name mywallet \
  --wallet.hotkey default

Common subnet IDs:
- 3 - Templar (decentralized training)
- 68 - MetaNova (molecular search)
- 81 - Grail (GRPO training)

POW registration (if available):

btcli subnet pow-register \
  --netuid <subnet_id> \
  --wallet.name mywallet \
  --wallet.hotkey default

4. Staking TAO

Add stake to your hotkey:

btcli stake add \
  --wallet.name mywallet \
  --wallet.hotkey default \
  --amount 100

Stake all available TAO:

btcli stake add \
  --wallet.name mywallet \
  --wallet.hotkey default \
  --all

Remove stake:

btcli stake remove \
  --wallet.name mywallet \
  --wallet.hotkey default \
  --amount 50

View your stake:

btcli stake list --wallet.name mywallet

5. Check Subnet Status

View metagraph (all neurons on a subnet):

btcli subnets metagraph --netuid <subnet_id>

Show subnet details:

btcli subnets show --netuid <subnet_id>

Check your neuron's status:

btcli subnets show --netuid <subnet_id> --wallet.name mywallet

6. Transfer TAO

Send TAO to another address:

btcli wallet transfer \
  --wallet.name mywallet \
  --dest <destination_ss58_address> \
  --amount 10

Key Concepts

Coldkeys vs Hotkeys

Security Rule: Your coldkey mnemonic is your master key. Store it offline, never share it, never store it digitally in plain text.

Registration and UIDs

When you register on a subnet:
1. You receive a UID (0-255) on that subnet
2. Your hotkey is associated with that UID
3. You can be deregistered if your performance is lowest when all slots are full
4. New registrations have immunity period (~13.7 hours / 4096 blocks)

Staking Mechanics

• Stake determines your influence/weight in the subnet
• Validators need minimum 1000 stake-weight for permits
• Stake is converted to subnet's alpha tokens via AMM
• Unstaking converts alpha back to TAO at current rate
• Default validator take is 18% of delegated emissions

Common Operations

Regenerate Keys from Mnemonic

Regenerate coldkey:

btcli wallet regen_coldkey \
  --wallet.name mywallet \
  --mnemonic "word1 word2 word3 ... word12"

Regenerate hotkey:

btcli wallet regen_hotkey \
  --wallet.name mywallet \
  --wallet.hotkey default \
  --mnemonic "word1 word2 word3 ... word12"

Configuration

Set default wallet:

btcli config set --wallet.name mywallet --wallet.hotkey default

View current config:

btcli config get

Config file location: ~/.bittensor/config.yml

Safe Staking (Prevent Slippage)

btcli stake add \
  --wallet.name mywallet \
  --wallet.hotkey default \
  --amount 100 \
  --safe \
  --tolerance 5  # Max 5% rate change

Troubleshooting

Common Issues

"Wallet not found"

# List available wallets
btcli wallet list

# Check wallet path
ls ~/.bittensor/wallets/

"Not registered on subnet"

# Check registration status
btcli subnets metagraph --netuid <id> | grep <your_hotkey_ss58>

# Re-register if needed
btcli subnet register --netuid <id> --wallet.name <name> --wallet.hotkey <hotkey>

"Insufficient balance"

# Check coldkey balance
btcli wallet balance --wallet.name <name>

# Check staked amounts
btcli stake list --wallet.name <name>

"Transaction failed"
- Check network connectivity
- Ensure sufficient TAO for transaction fees
- Try with --no-prompt to see full error
- Check debug log: ~/.bittensor/debug.txt

Debug Mode

# Enable verbose output
btcli <command> --verbose

# Check debug logs
cat ~/.bittensor/debug.txt

Environment Variables

Wallet File Locations

~/.bittensor/
├── wallets/
│   └── <wallet_name>/
│       ├── coldkey           # Encrypted coldkey
│       ├── coldkeypub.txt    # Public key
│       └── hotkeys/
│           └── <hotkey_name> # Hotkey file
├── config.yml                # CLI configuration
└── debug.txt                 # Debug logs

Safety Checklist

Before any major operation:

• [ ] Verify wallet name is correct
• [ ] Confirm you have mnemonic backed up
• [ ] Check you're on correct network (finney vs test)
• [ ] Verify destination address for transfers
• [ ] Understand transaction fees will apply
• [ ] Use --no-prompt only when confident

Resources

References

• references/command_reference.md - Complete command documentation
• references/staking_guide.md - Advanced staking operations
• references/subnet_operations.md - Subnet management

External Resources

• Official Docs: https://docs.learnbittensor.org/btcli
• GitHub: https://github.com/opentensor/btcli
• Taostats: https://taostats.io/ (network explorer)

Related Skills

• templar-miner-claude-skill - Templar subnet mining
• grail-miner-claude-skill - Grail subnet mining
• basilica-cli-helper - GPU rentals for mining