Bittensor CLI: btcli
Reference Document
Command line interface (CLI) for Bittensor. Uses the values in the configuration file. These values can be overriden by passing them explicitly in the command line.
See Getting Started to install btcli
.
Many BTCLI operations incur transaction fees. See Transaction Fees in Bittensor for details.
Command line interface (CLI) for Bittensor. Uses the values in the configuration file. These values can be overriden by passing them explicitly in the command line.
Usage:
btcli [OPTIONS] COMMAND [ARGS]...
Options:
--version
: Show BTCLI version.--commands
: Show BTCLI commands.--debug
: Saves the debug log from the last used command.--install-completion
: Install completion for the current shell.--show-completion
: Show completion for the current shell, to copy it or customize the installation.--help
: Show this message and exit.
Commands:
config
: Config commands, aliases:c
,conf
wallet
: Wallet commands, aliases:wallets
,w
stake
: Stake commands, alias:st
sudo
: Sudo commands, alias:su
subnets
: Subnets commands, alias:s
,subnet
weights
: Weights commands, aliases:wt
,weight
utils
view
: HTML view commandsliquidity
: Liquidity commands, aliases:l
btcli config
Usage:
btcli config [OPTIONS] COMMAND [ARGS]...
aliases: conf, c
Options:
--help
: Show this message and exit.
Commands:
set
: Sets or updates configuration values in the BTCLI config file.get
: Prints the current config file in a table.clear
: Clears the fields in the config file and sets them to 'None'.
btcli config set
Sets or updates configuration values in the BTCLI config file.
This command allows you to set default values that will be used across all BTCLI commands.
Usage:
Interactive mode:
btcli config set
Set specific values:
btcli config set --wallet-name default --network finney
btcli config set --safe-staking --rate-tolerance 0.1
Note:
- Network values can be network names (e.g., 'finney', 'test') or websocket URLs
- Rate tolerance is specified as a decimal (e.g., 0.05 for 0.05%)
- Changes are saved to
~/.bittensor/btcli.yaml
- Use
btcli config get
to view current settings
Usage:
btcli config set [OPTIONS]
Options:
Option | Type | Description |
---|---|---|
--wallet-name , --name , --wallet_name , --wallet.name | TEXT | Name of the wallet. |
-p , --wallet-path , --wallet_path , --wallet.path | TEXT | Path where the wallets are located. For example: /Users/btuser/.bittensor/wallets . |
-H , --hotkey , --wallet_hotkey , --wallet-hotkey , --wallet.hotkey | TEXT | Hotkey of the wallet |
--network , --subtensor.network , --chain , --subtensor.chain_endpoint | TEXT | The subtensor network to connect to. Default: finney. |
--cache , --cache /--no-cache , --no_cache | Disable caching of some commands. This will disable the --reuse-last and --html flags on commands such as subnets metagraph , stake show and subnets list . | |
--tolerance | FLOAT | Set the rate tolerance percentage for transactions (e.g. 0.1 for 0.1%) |
--safe-staking , --safe /--no-safe-staking , --unsafe | Enable or disable safe staking mode. | |
--allow-partial-stake , --partial , --allow /--no-allow-partial-stake , --no-partial , --not-allow | Allow or prevent partial stakes | |
--dashboard-path , --dashboard_path , --dash_path , --dash.path | TEXT | Path to save the dashboard HTML file. For example: ~/.bittensor/dashboard . |
--help | Show this message and exit. |
btcli config get
Prints the current config file in a table.
Usage:
btcli config get [OPTIONS]
Options:
Option | Type | Description |
---|---|---|
--help | Show this message and exit. |
btcli config clear
Clears the fields in the config file and sets them to 'None'.
-
To clear the 'chain' and 'network' fields:
btcli config clear --chain --network
-
To clear your config entirely:
btcli config clear --all
Usage:
btcli config clear [OPTIONS]
Options:
Option | Type | Description |
---|---|---|
--wallet-name , --name , --wallet_name , --wallet.name | TEXT | Name of the wallet. |
-p , --wallet-path , --wallet_path , --wallet.path | TEXT | Path where the wallets are located. For example: /Users/btuser/.bittensor/wallets . |
-H , --hotkey , --wallet_hotkey , --wallet-hotkey , --wallet.hotkey | TEXT | Hotkey of the wallet |
--network , --subtensor.network , --chain , --subtensor.chain_endpoint | TEXT | The subtensor network to connect to. Default: finney. |
--cache | Disable caching of some commands. This will disable the --reuse-last and --html flags on commands such as subnets metagraph , stake show and subnets list . | |
--tolerance | ||
--safe-staking , --safe /--no-safe-staking , --unsafe | Enable or disable safe staking mode. | |
--allow-partial-stake , --partial , --allow /--no-allow-partial-stake , --no-partial , --not-allow | Allow or prevent partial stakes | |
--all | Clears the entire config. | |
--dashboard-path , --dashboard_path , --dash_path , --dash.path | TEXT | Path to save the dashboard HTML file. For example: ~/.bittensor/dashboard . |
--help | Show this message and exit. |
btcli view
Display html dashboard with subnets list, stake, and neuron information.
Usage:
btcli view [OPTIONS] COMMAND [ARGS]...
Options:
--help
: Show this message and exit.
Commands:
dashboard
: Display html dashboard with subnets list, stake, and neuron information.
btcli view dashboard
Display html dashboard with subnets list, stake, and neuron information.
Usage:
btcli view dashboard
Options:
Option | Type | Description |
---|---|---|
--help | Show this message and exit. |
btcli wallet
Usage:
btcli wallet [OPTIONS] COMMAND [ARGS]...
aliases: w, wallets
Options:
--help
: Show this message and exit.
Commands:
list
: Displays all the wallets and their corresponding hotkeys that are located in the wallet path specified in the config.associate_hotkey
: Associate a hotkey with a wallet(coldkey).swap-hotkey
: Swap hotkeys of a given wallet on the blockchain.swap-coldkey
: Schedule a coldkey swap for a wallet.swap-check
: Check the status of scheduled coldkey swaps.regen-coldkey
: Regenerate a coldkey for a wallet on the Bittensor blockchain network.regen-coldkeypub
: Regenerates the public part of a coldkey (coldkeypub.txt
) for a wallet.regen-hotkey
: Regenerates a hotkey for a wallet.regen-hotkeypub
: Regenerates the public part of a hotkey (hotkeypub.txt
) for a wallet.new-hotkey
: Create a new hotkey for a wallet.new-coldkey
: Create a new coldkey.create
: Create a complete wallet by setting up both coldkey and hotkeys.balance
: Check the balance of the wallet.overview
: Displays a detailed overview of the user's registered accounts on the Bittensor network.transfer
: Send TAO tokens from one wallet to another wallet on the Bittensor network.set-identity
: Create or update the on-chain identity of a coldkey or a hotkey on the Bittensor network.get-identity
: Shows the identity details of a user's coldkey or hotkey.sign
: Allows users to sign a message with the provided wallet or wallet hotkey.verify
: Verify a message signature using the signer's public key or SS58 address.
btcli wallet list
Displays all the wallets and their corresponding hotkeys that are located in the wallet path specified in the config.
The output display shows each wallet and its associated ss58
addresses for the coldkey public key and any hotkeys. The output is presented in a hierarchical tree format, with each wallet as a root node and any associated hotkeys as child nodes. The ss58
address is displayed for each coldkey and hotkey that is not encrypted and exists on the device.
Upon invocation, the command scans the wallet directory and prints a list of all the wallets, indicating whether the
public keys are available (?
denotes unavailable or encrypted keys).
btcli wallet list --path ~/.bittensor
Note: This command is read-only and does not modify the filesystem or the blockchain state. It is intended for use with the Bittensor CLI to provide a quick overview of the user's wallets.
Usage:
btcli wallet list [OPTIONS]
Options:
Option | Type | Description |
---|---|---|
-p , --wallet-path , --wallet_path , --wallet.path | TEXT | Path where the wallets are located. For example: /Users/btuser/.bittensor/wallets . |
--quiet | Display only critical information on the console. | |
--verbose | Enable verbose output. | |
--help | Show this message and exit. |
btcli wallet associate-hotkey
This command is used to associate a hotkey with a wallet(coldkey).
Example
btcli wallet associate-hotkey --hotkey-name hotkey_name
btcli wallet associate-hotkey --hotkey-ss58 5DkQ4...
Usage:
btcli w associate-hotkey [OPTIONS]
alias: associate_hotkey
Options
Option | Type | Description |
---|---|---|
--wallet-name , --name , --wallet_name , --wallet.name | TEXT | Name of the wallet. |
-p , --wallet-path , --wallet_path , --wallet.path | TEXT | Path where the wallets are located. For example: /Users/btuser/.bittensor/wallets . |
-H , --hotkey , --wallet_hotkey , --wallet-hotkey , --wallet.hotkey | TEXT | Hotkey name or SS58 address of the hotkey. |
--network , --subtensor.network , --chain , --subtensor.chain_endpoint | TEXT | The subtensor network to connect to. Default: finney. |
--quiet | Display only critical information on the console. | |
--verbose | Enable verbose output. | |
--prompt , --prompt , --no-prompt , --yes , --no_prompt , -y | Enable or disable interactive prompts. | |
--help | Show this message and exit. | |
btcli wallet swap-hotkey
Swap hotkeys of a given wallet on the blockchain. For a registered key pair, for example, a (coldkeyA, hotkeyA) pair, this command swaps the hotkeyA with a new, unregistered, hotkeyB to move the original registration to the (coldkeyA, hotkeyB) pair.
- Make sure that your original key pair (coldkeyA, hotkeyA) is already registered.
- Make sure that you use a newly created hotkeyB in this command. A hotkeyB that is already registered cannot be used in this command.
- Finally, note that this command requires a fee of 1 TAO for recycling and this fee is taken from your wallet (coldkeyA).
Example:
btcli wallet swap_hotkey destination_hotkey_name --wallet-name your_wallet_name --wallet-hotkey original_hotkey
Usage:
btcli wallet swap-hotkey [OPTIONS] [DESTINATION_HOTKEY_NAME]
alias: swap_hotkey
Arguments:
[DESTINATION_HOTKEY_NAME]
: Destination hotkey name.
Options:
Option | Type | Description |
---|---|---|
--wallet-name , --name , --wallet_name , --wallet.name | TEXT | Name of the wallet. |
-p , --wallet-path , --wallet_path , --wallet.path | TEXT | Path where the wallets are located. For example: /Users/btuser/.bittensor/wallets . |
-H , --hotkey , --wallet_hotkey , --wallet-hotkey , --wallet.hotkey | TEXT | Hotkey of the wallet |
--netuid | INTEGER | The netuid of the subnet in the network, (e.g. 1). |
--all-netuids /--no-all-netuids , | Use all netuids | |
--network , --subtensor.network , --chain , --subtensor.chain_endpoint | TEXT | The subtensor network to connect to. Default: finney. |
--quiet | Display only critical information on the console. | |
--verbose | Enable verbose output. | |
--prompt , --prompt , --no-prompt , --yes , --no_prompt , -y | Enable or disable interactive prompts. | |
--json-output , --json-out | Outputs the result of the command as JSON. | |
--help | Show this message and exit. | |
btcli wallet swap-coldkey
This command allows you to schedule a coldkey swap for a wallet. You can either provide a new wallet name, or SS58 address.
Example
btcli wallet swap-coldkey --new-wallet my_new_wallet
btcli wallet swap-coldkey --new-coldkey-ss58 5Dk...X3q
Usage:
btcli wallet swap-coldkey [OPTIONS]
alias: swap_coldkey
Options
Option | Type | Description |
---|---|---|
--wallet-name , --name , --wallet_name , --wallet.name | TEXT | Name of the wallet. |
-p , --wallet-path , --wallet_path , --wallet.path | TEXT | Path where the wallets are located. For example: /Users/btuser/.bittensor/wallets . |
-H , --hotkey , --wallet_hotkey , --wallet-hotkey , --wallet.hotkey | TEXT | Hotkey of the wallet |
--new-coldkey , --new-coldkey-ss58 , --new-wallet , --new | TEXT | SS58 address of the new coldkey that will replace the current one. |
--network , --subtensor.network , --chain , --subtensor.chain_endpoint | TEXT | The subtensor network to connect to. Default: finney. |
--quiet | Display only critical information on the console. | |
--verbose | Enable verbose output. | |
--force , --force-swap , -f | Force the swap even if the new coldkey is already scheduled for a swap. | |
--help | Show this message and exit. | |
btcli wallet swap-check
This command checks the status of scheduled coldkey swaps. It can be used in one of three ways:
- Show all pending swaps using the
--all
flag. - Check status of a specific wallet's swap or SS58 address.
- Check detailed swap status with block number using the
--block
flag.
Example
Show all pending swaps:
btcli wallet swap-check --all
Check specific wallet's swap:
btcli wallet swap-check --wallet-name my_wallet
Check swap using SS58 address:
btcli wallet swap-check --ss58 5DkQ4...
Check swap details with block number:
btcli wallet swap-check --wallet-name my_wallet --block 12345
Usage:
btcli wallet swap-check [OPTIONS]
alias: swap_check
Options
Option | Type | Description |
---|---|---|
--wallet-name , --name , --wallet_name , --wallet.name | TEXT | Name of the wallet. |
-p , --wallet-path , --wallet_path , --wallet.path | TEXT | Path where the wallets are located. For example: /Users/btuser/.bittensor/wallets . |
-H , --hotkey , --wallet_hotkey , --wallet-hotkey , --wallet.hotkey | TEXT | Hotkey of the wallet |
--block | INTEGER | Block number where the swap was scheduled. |
--all | Show all pending coldkey swaps | |
--network , --subtensor.network , --chain , --subtensor.chain_endpoint | TEXT | The subtensor network to connect to. Default: finney. |
--quiet | Display only critical information on the console. | |
--verbose | Enable verbose output. | |
--help | Show this message and exit. | |
btcli wallet regen-coldkey
Regenerate a coldkey for a wallet on the Bittensor blockchain network.
This command is used to create a new coldkey from an existing mnemonic, seed, or JSON file.
Usage:
Users can specify a mnemonic, a seed string, or a JSON file path to regenerate a coldkey. The command supports optional password protection for the generated key.
Example:
btcli wallet regen-coldkey --mnemonic "word1 word2 ... word12"
This command is critical for users who need to regenerate their coldkey either for recovery or for security reasons.
Usage:
btcli wallet regen-coldkey [OPTIONS]
alias: regen_coldkey
Options:
Option | Type | Description |
---|---|---|
--wallet-name , --name , --wallet_name , --wallet.name | TEXT | Name of the wallet. |
-p , --wallet-path , --wallet_path , --wallet.path | TEXT | Path where the wallets are located. For example: /Users/btuser/.bittensor/wallets . |
-H , --hotkey , --wallet_hotkey , --wallet-hotkey , --wallet.hotkey | TEXT | Hotkey of the wallet |
--mnemonic | TEXT | Mnemonic used to regenerate your key. |
--seed , | TEXT | Seed hex string used to regenerate your key. |
--json , -j | TEXT | Path to a JSON file containing the encrypted key backup. |
--json-password , | TEXT | Password to decrypt the JSON file.key. |
--use-password /--no-use-password , | Set this to True to protect the generated Bittensor key with a password. | |
--overwrite /--no-overwrite | Overwrite the existing wallet file with the new one. | |
--quiet | Display only critical information on the console. | |
--verbose | Enable verbose output. | |
--json-output , --json-out | Outputs the result of the command as JSON. | |
--help | Show this message and exit. |
btcli wallet regen-coldkeypub
Regenerates the public part of a coldkey (coldkeypub.txt
) for a wallet.
Use this command when you need to move machine for subnet mining. Use the public key or SS58 address from your coldkeypub.txt
that you have on another machine to regenerate the coldkeypub.txt
on this new machine.
Usage:
The command requires either a public key in hexadecimal format or an SS58
address from the existing coldkeypub.txt
from old machine to regenerate the coldkeypub on the new machine.
Example:
btcli wallet regen_coldkeypub --ss58_address 5DkQ4...
This command is particularly useful for users who need to regenerate their coldkeypub, perhaps due to file corruption or loss. You will need either ss58 address or public hex key from your old coldkeypub.txt
for the wallet. It is a recovery-focused utility that ensures continued access to your wallet functionalities.
Usage:
btcli wallet regen-coldkeypub [OPTIONS]
alias: regen_coldkeypub
Options:
Option | Type | Description |
---|---|---|
--wallet-name , --name , --wallet_name , --wallet.name | TEXT | Name of the wallet. |
-p , --wallet-path , --wallet_path , --wallet.path | TEXT | Path where the wallets are located. For example: /Users/btuser/.bittensor/wallets . |
-H , --hotkey , --wallet_hotkey , --wallet-hotkey , --wallet.hotkey | TEXT | Hotkey of the wallet |
--public-key-hex , | TEXT | The public key in hex format. |
--ss58 , --ss58-address , | TEXT | The SS58 address of the coldkey. |
--overwrite /--no-overwrite | Overwrite the existing wallet file with the new one. | |
--quiet | Display only critical information on the console. | |
--verbose | Enable verbose output. | |
--json-output , --json-out | Outputs the result of the command as JSON. | |
--help | Show this message and exit. |
btcli wallet regen-hotkey
Regenerates a hotkey for a wallet.
Similar to regenerating a coldkey, this command creates a new hotkey from a mnemonic, seed, or JSON file.
Usage:
Users can provide a mnemonic, seed string, or a JSON file to regenerate the hotkey. The command supports optional password protection and can overwrite an existing hotkey.
btcli wallet regen_hotkey --seed 0x1234...
This command is essential for users who need to regenerate their hotkey, possibly for security upgrades or key recovery. It should be used with caution to avoid accidental overwriting of existing keys.
Usage:
btcli wallet regen-hotkey [OPTIONS]
alias: regen_hotkey
Options:
Option | Type | Description |
---|---|---|
--wallet-name , --name , --wallet_name , --wallet.name | TEXT | Name of the wallet. |
-p , --wallet-path , --wallet_path , --wallet.path | TEXT | Path where the wallets are located. For example: /Users/btuser/.bittensor/wallets . |
-H , --hotkey , --wallet_hotkey , --wallet-hotkey , --wallet.hotkey | TEXT | Hotkey of the wallet |
--mnemonic | TEXT | Mnemonic used to regenerate your key. |
--seed , | TEXT | Seed hex string used to regenerate your key. |
--json , -j | TEXT | Path to a JSON file containing the encrypted key backup. |
--json-password , | TEXT | Password to decrypt the JSON file.key. |
--use-password /--no-use-password , | Set this to True to protect the generated Bittensor key with a password. | |
--overwrite /--no-overwrite | Overwrite the existing wallet file with the new one. | |
--quiet | Display only critical information on the console. | |
--verbose | Enable verbose output. | |
--json-output , --json-out | Outputs the result of the command as JSON. | |
--help | Show this message and exit. |
btcli wallet regen-hotkeypub
This command regenerates the public part of a hotkey (hotkeypub.txt) for a wallet. Use this command when you need to move machine for subnet mining. Use the public key or SS58 address from your hotkeypub.txt that you have on another machine to regenerate the hotkeypub.txt on this new machine.
Usage
The command requires either a public key in hexadecimal format or an SS58
address from the existing hotkeypub.txt
from old machine to regenerate the coldkeypub on the new machine.
Example:
btcli wallet regen-hotkeypub --ss58_address 5DkQ4...
Usage
btcli wallet regen-hotkeypub [OPTIONS]
alias: regen_hotkeypub
This command is particularly useful for users who need to regenerate their hotkeypub, perhaps due to file corruption or loss. You will need either ss58 address or public hex key from your old hotkeypub.txt
for the wallet. It is a recovery-focused utility that ensures continued access to your wallet functionalities.
Options
Option | Type | Description |
---|---|---|
--wallet-name , --name , --wallet_name , --wallet.name | TEXT | Name of the wallet. |
-p , --wallet-path , --wallet_path , --wallet.path | TEXT | Path where the wallets are located. For example: /Users/btuser/.bittensor/wallets . |
-H , --hotkey , --wallet_hotkey , --wallet-hotkey , --wallet.hotkey | TEXT | Hotkey of the wallet |
--public-key-hex , | TEXT | The public key in hex format. |
--ss58 , --ss58-address , | TEXT | The SS58 address of the coldkey. |
--overwrite /--no-overwrite | Overwrite the existing wallet file with the new one. | |
--quiet | Display only critical information on the console. | |
--verbose | Enable verbose output. | |
--json-output , --json-out | Outputs the result of the command as JSON. | |
--help | Show this message and exit. |