SUBMIT A PRSUBMIT AN ISSUElast edit: Aug 28, 2024

Bittensor CLI

After you install Bittensor you can use btcli command line interface (CLI) to stake or unstake funds, run miners, check network state, and even deploy, analyze, and interface with the Bittensor network. This section presents the command and subcommand options available in btcli CLI.

Usage

btcli [COMMAND]
usage: btcli <command> <command args>
positional arguments:
  {subnets,s,subnet,root,r,roots,wallet,w,wallets,stake,st,stakes,sudo,su,sudos,legacy,l}
    subnets (s, subnet)
                        Commands for managing and viewing subnetworks.
    root (r, roots)     Commands for managing and viewing the root network.
    wallet (w, wallets)
                        Commands for managing and viewing wallets.
    stake (st, stakes)  Commands for staking and removing stake from hotkey accounts.
    sudo (su, sudos)    Commands for subnet management
    legacy (l)          Miscellaneous commands.

---

Wallets

Show overview

btcli wallet overview [OPTIONS]

Displays comprehensive information about each neuron associated with the user's wallets, including both hotkeys and coldkeys. It is especially useful for users managing multiple accounts or looking for a summary of their network activities and stake distributions.

Example

btcli wallet overview

With example options:

btcli wallet overview --all --sort_by stake --sort_order descending

Run,

btcli wallet overview --help

for full options.

Show history

btcli wallet history --wallet.name <YOUR WALLET NAME>

Displays the last 1000 transactions performed with <YOUR WALLET NAME> by querying the Taostats GraphQL indexer. It shows the From, To, Amount, Extrinsic Id and Block Number.

Run,

btcli wallet history --help

for help.

List wallets

btcli wallet list [OPTIONS]

• Lists all wallets locally stored on your machine under path --wallet.path.
• Output addresses are SS58 encoded.
• Required as destinations for btcli transfer

btcli wallet list
Wallets
└─
    my_wallet (<ss58_address>)
       └── my_first_hotkey (<ss58_address>)

Check balance in all wallets

btcli wallet balance --all

Lists the balances in all the wallets in the user's configuration directory, showing the wallet name, coldkey address, and the free and staked balances.

Check balance in a single wallet

btcli w balance --wallet.name WALLET

or you can specify the wallet's name in the terminal prompt:

btcli w balance

New coldkey

btcli wallet new_coldkey [OPTIONS]

Create a new wallet with encrypted coldkey EdDSA cryptographic keypair:

btcli wallet new_coldkey

New hotkey

btcli wallet new_hotkey [OPTIONS]

Create a EdDSA cryptographic keypair hotkey associated with a wallet:

btcli wallet new_hotkey

Regenerate hotkey

btcli wallet regen_hotkey [OPTIONS]

Regenerate a hotkey from mnemonic:

btcli wallet regen_hotkey

Regenerate coldkey

btcli wallet regen_coldkey [OPTIONS]

Regenerate a wallet encrypted coldkey file from mnemonic or seed:

btcli wallet regen_coldkey

Regenerate coldkeypub

btcli wallet regen_coldkeypub [OPTIONS]

Regenerate a wallet with just the public seed of your coldkey:

btcli wallet regen_coldkeypub

Swap hotkey

btcli wallet swap_hotkey

For a registered key pair, for example, a (coldkeyA, hotkeyA) pair, this command swaps the hotkeyA with another already-registered hotkeyB to move the original registration to the (coldkeyA, hotkeyB) pair.

this operation costs 1 TAO recycled

This command registers, behind the scenes, the new key pair (coldkeyA, hotkeyB) into the network you specify (defaults to mainnet, finney), hence it costs you 1 TAO recycled.

IMPORTANT

• Make sure that your original key pair (coldkeyA, hotkeyA) is already registered.
• Make sure that you first create the new hotkeyB before using it in this command.
• Finally, note that this command will not warn you but it does take out 1 TAO for recycling from your coldkeyA wallet.

Get identity

btcli wallet get_identity --key <s58_address> [OPTIONS]

• --key [Optional] is the SS58 address of the coldkey or hotkey.

Displays the identity details of a user's coldkey or hotkey associated with the Bittensor network.

Set identity

btcli wallet set_identity [OPTIONS]

Creates or updates a delegate's on-chain identity. This identity includes various attributes such as display name, legal name, web URL, PGP fingerprint, and contact information, among others.

caution

This command should only be used if the user is willing to incur the 1 TAO transaction fee associated with setting an identity on the blockchain. It is a high-level command that makes changes to the blockchain state and should not be used programmatically as part of other scripts or applications.

---

Subnets

List subnets

Lists the existing subnets and shows their detailed information. In addition to the subnet details, the command fetches delegate information and provides the name of the subnet owner where available. If the owner's name is not available, the owner's SS58 address is displayed.

Defaults to subnets on the mainchain.

btcli subnets list [OPTIONS]

Use,

btcli subnets list --help

to see the available OPTIONS.

Show lock cost

Shows the locking cost required for creating a new subnet on the Bittensor network. This command is designed to provide users with the current cost of registering a new subnet. If the cost is unappealing currently, check back in a day or two to see if it has improved.

btcli subnets lock_cost [OPTIONS]

Use,

btcli subnets lock_cost --help

to see the available OPTIONS.

Create subnet

For advanced users only

This command is intended for advanced users of the Bittensor network who wish to contribute by adding new subnets. It requires a clear understanding of the Bittensor network's functioning and the roles of subnets. Users should ensure that they have secured their wallet and are aware of the implications of adding a new subnetwork to the Bittensor ecosystem.

Creates and registers a new subnet. This involves interaction with the user's wallet and the Bittensor subtensor. It ensures that the user has the necessary credentials and configurations to successfully register a new subnet.

btcli subnets create [OPTIONS]

Use,

btcli subnets create --help

to see the available OPTIONS.

Register

btcli subnets register [OPTIONS]

Registers a new neuron using the recycle_register option. Adds a new neuron to the specified subnet --netuid.

alert

The command option recycle_register is removed. Instead, use the above register option.

To register in a subnet of netuid of 1:

btcli subnets register --netuid 1

Use,

btcli subnets register --help

to see the available OPTIONS.

PoW registration

btcli subnets pow_register [OPTIONS]

Registers a neuron on the Bittensor network using Proof of Work (PoW). This method is an alternative registration process that leverages computational work for securing a neuron's place on the network.

Example:

btcli subnets pow_register --netuid 1 --pow_register.num_processes 4 --cuda.use_cuda

Use,

btcli subnets pow_register --help

to see the available OPTIONS.

caution

This command is for users with adequate computational resources to participate in PoW registration. It requires a sound understanding of the network's operations and PoW mechanics. Users should ensure their systems meet the necessary hardware and software requirements, particularly when opting for CUDA-based GPU acceleration.

Show metagraph

Shows the metagraph of the desired subnet. Defaults to subnets on the mainchain.

btcli subnets metagraph [OPTIONS]

Use,

btcli subnets metagraph --help

to see the available OPTIONS.

Show hyperparameters

Shows the current hyperparameters for the desired subnet. This command is useful for users who wish to understand the configuration and operational parameters of a particular subnet.

btcli subnets hyperparameters [OPTIONS]

Use,

btcli subnets hyperparameters --help

to see the available OPTIONS.

---

Transfers and staking

Transfer Tao

btcli wallet transfer [OPTIONS]

• Transfers TAO from a wallet coldkey to another wallet public key address.
• Destination addresses must be SS58 encoded.

btcli wallet transfer

Stake

btcli stake add [OPTIONS]

Stake TAO from the coldkey balance to the hotkey staking account.

btcli stake add

Unstake Tao

btcli stake remove [OPTIONS]

Remove stake TAO from the hotkey staking account and add it to the coldkey.

btcli stake remove

---

Delegation

See available delegates

btcli root list_delegates

List all active delegates available for delegated TAO. Displays the below output:

Delegate Tao

btcli root delegate [OPTIONS]

Delegate TAO from the coldkey balance to the hotkey staking account of a delegate.

btcli root delegate

Set delegate take

btcli root set_take [OPTIONS]

Sets the take percentage of the delegate.

To set the delegate take at 10%:

btcli root set_take --take 0.1

The --take value must be a floating point number between 0.09 and 0.18.

Default --take value is 0.18 (18%).

To use a specific wallet:

btcli root set_take --wallet.name my_wallet --wallet.hotkey my_hotkey --take 0.1

• Allowed take values: Ensure the --take value is within the range of 0.09 to 0.18.
• wallet.name and wallet.hotkey: If not specified, the command will prompt for the wallet name and hotkey.

Examples:

1. Set delegate take to 10%:

   btcli root set_take --take 0.1

2. Set delegate take to 10% using a specific wallet:

   btcli root set_take --wallet.name my_wallet --wallet.hotkey my_hotkey --take 0.1

Undelegate Tao

btcli root undelegate [OPTIONS]

Remove TAO from the hotkey balance of delegate you have previously delegated to.

btcli root undelegate

My delegates

btcli root my_delegates

Show all your previously made delegations.

tip

Use --all option to show delegations across all your wallets.

---

Root network

Root network list

btcli root list

Lists all the root network members. Shows the top 64 validators in the root network.

Boost weights

btcli root boost [OPTIONS]

This command allows boosting (increasing) of weights for different subnets within the root network.

Optional arguments:

• --netuid (int): A single netuid for which weights are to be boosted (increased).
• --increase (float): The corresponding increase in the weight for this subnet.

Example:

btcli root boost --netuid 1 --increase 0.01

Slash weights

btcli root slash [OPTIONS]

This command allows slashing (decreasing) the weights for different subnets within the root network.

Optional arguments:

• --netuid (int): A single netuid for which weights are to be slashed (decreased).
• --decrease (float): The corresponding decrease in the weight for this subnet.

Example:

btcli root slash --netuid 1 --decrease 0.01

---

Governance

View proposals

btcli root proposals

List all active proposals for the Senate to vote on. Displays an output similar to below:

Proposal votes

btcli root proposals [OPTIONS]

Inspect the votes for a single proposal.

btcli root proposals --proposal=[PROPOSAL_HASH]

Senate register

btcli root register [OPTIONS]

Elect to join the Senate with your nominated hotkey.

btcli root register

Senate vote

btcli root senate_vote [OPTIONS]

Participate in a triumvirate proposal by voting with your senate hotkey.

btcli root senate_vote --proposal=[PROPOSAL_HASH]

---

Misc

Update Bittensor

btcli legacy update [OPTIONS]

Update your Bittensor installation.

btcli legacy update