Skip to main content

Bittensor CLI: Permissions Guide

SUBMIT A PRSUBMIT AN ISSUElast edit: Apr 10, 2025

The Bittensor CLI, btcli provides a wide range of functionality, and has a range of different requirements for various commands: some require a coldkey private key to authenticate, some require a hotkey private key, and some require neither. Additionally, different functions require different levels of permissions. Some require the user to have special status like being registered with a node, have a validator permit, or be an active member of the senate.

This page details the requirements for all of the btcli commands.

See also the btcli permissions guides for specific Bittensor personas:

Other resources:

Bittensor work environments and security requirements​

Interacting with Bittensor generally falls into one of three levels of security, depending on whether you need to use your coldkey private key, hotkey private key, or neither.

The workstations you use to do this work can be referred to as a permissionless workstation (requiring neither private key), a coldkey workstation or a hotkey workstation, depending on which private key is provisioned.

  1. A permissionless workstation has only coldkey public keys on it. Public keys are sufficient for viewing all information about a wallet, such as TAO and alpha stake balances. Information about wallets, subnets, miners, and validators can and should be viewed without initializing your private keys on a device, to avoid the security risk of compromising your keys.

    coldkey workstation security

    See Permissionless workstation

  2. A coldkey workstation contains one or more coldkey private key in the wallet_path. For any coldkey associated with mainnet TAO, the coldkey workstation should be held to the highest possible security standards.

    coldkey workstation security

    See [Coldkey workstation](./ getting-started/coldkey-hotkey-security#coldkey-workstation)

  3. A hotkey workstation—which is generally a server used for mining or validation—contains a hotkey private key in the wallet_path located in the btcli config, as well as a coldkey public key for the corresponding coldkey. Compromised hotkeys can damage your reputation if they are used to maliciously to submit inaccurate weights as a validator, or bad work as a miner. However, ownership of TAO or alpha stake can only be transferred with a coldkey, and a leaked hotkey can be swapped using the coldkey; therefore hotkey leaks are far less dangerous than coldkey leaks.

    hotkey workstation

    See Hotkey workstation security

Requirements for btcli functions​

Coldkey​

Your coldkey is your primary, fully privileged key; important for all users. This key should be handled on a maximum security coldkey workstation only, to avoid catastrophic loss or malicious actions if compromised.

See Coldkey and Hotkey Workstation Security.

Required for:

  • Moving and transferring TAO
  • Managing stake (add/remove/move)
  • Creating hotkeys
  • Registering hotkeys in subnets
  • Creating and modifying subnets
  • Participating in governance of Bittensor as a senator

Hotkey​

Hotkeys are used by miners and validators to sign transactions, and are required for governance.

Required for:

  • Running miners:
    • Serving requests from validators
    • Making on-chain data commitments (if applicable)
  • Running validators:
    • making signed requests to miners
    • setting weights
    • being discoverable by stakers and miners

Available liquidity​

Some operations require a TAO balance or alpha stake balance to execute.

  • Transfers of TAO fail if you lack the specified amount
  • Staking and unstaking operations fail if they specify more than the owner has
  • Registering a hotkey on a subnet to mine or validate has a fee that can be paid with TAO or proof-of-work.
  • Creating a subnet requires a fee, which is computed dynamically. The price to create a subnet doubles when someone creates a subnet, and then gradually decreases. This system is designed as a kind of distributed auction, where price is determined by what people are willing to pay given the uncertain estimation of what others are willing to pay.

Validator Permit​

To set weights, a validator must meet several requirements. See Requirements for validation.

Senate requirements​

See Senate: Requirements

btcli commands​

config​

The btcli config ... commands are used to configure btcli, including:

  • selecting the targeted network (finney a.k.a. mainnet or test for test network)
  • setting the directory where your Bittensor wallet coldkeys and/or hotkeys are stored

These commands don't require any permissions to run. Rather, you run these commands on all btcli workstations to initialize them.

See: Coldkey and Hotkey Workstation Security

btcli config

  • btcli config set

  • btcli config get

  • btcli config clear

  • btcli config metagraph

  • btcli conf set

  • btcli conf get

  • btcli conf clear

  • btcli conf metagraph

  • btcli c set

  • btcli c get

  • btcli c clear

  • btcli c metagraph

wallet​

wallet subcommands have a variety of uses and must be run on all different kinds of workstation.

The wallet command is required to provision keys to btcli, so it can access your wallet. This is essentially the equivalent of logging in/authentication. This is true for both coldkeys, which all users require, and hotkeys, which are required only by miners and validators as well as for advanced functions.

mind your keys

See: Coldkey and Hotkey Workstation Security

Provisioning keys​

  1. btcli wallet regen-coldkeypub: This initializes a wallet for a permissionless workstation with a public key only. It allows you to read all information about your wallet, which is public information. However, it doesn't allow you to sign any transactions and therefore doesn't allow you to make any changes to the state of the blockchain, including any of your balances or stakes.

  2. new coldkey is used to initialize a coldkey workstation using a newly created seed phrase. This is a high security risk operation due to the inherent risk of handling the seed phrase.

  3. regen coldkey is used to initialize a coldkey workstation using a pre-existing wallet's seed phrase. This is a high security risk operation due to the inherent risk of handling the seed phrase.

  4. new hotkey is used to initialize a hotkey workstation using a newly created seed phrase. This is a high security risk operation due to the inherent risk of handling the seed phrase. Hotkeys should be created on secure coldkey workstation and then carefully provisioned to working nodes for mining and validation.

  5. regen hotkey is used to initialize a hotkey workstation using a pre-existing wallet's seed phrase. This is a high security risk operation due to the inherent risk of handling the seed phrase.

Permissionless operations​

  • btcli wallet balance: Displays a wallet balance.
  • btcli wallet overview: Displays a wallet overview.

Operations requiring coldkey private key:​

  • swap-hotkey rotates a hotkey coldkey owned by the coldkey.
  • new-hotkey creates a new hotkey owned by the coldkey.
  • transfer transfers TAO to another coldkey.
  • set-identity sets the coldkey's public identity information.
  • sign(with coldkey) signs a message with the coldkey.

Operations requiring hotkey private key:​

  • sign (with hotkey): sign a message with the hotkey
btcli wallet

btcli wallet list​

btcli wallet swap-hotkey​

btcli wallet regen-coldkey​

btcli wallet regen-coldkeypub​

btcli wallet regen-hotkey​

btcli wallet new-hotkey​

btcli wallet new-coldkey​

btcli wallet create​

btcli wallet balance​

btcli wallet overview​

btcli wallet transfer​

btcli wallet inspect​

btcli wallet faucet​

btcli wallet set-identity​

btcli wallet get-identity​

btcli wallet sign​

btcli wallet swap_hotkey​

btcli wallet regen_coldkey​

btcli wallet regen_coldkeypub​

btcli wallet regen_hotkey​

btcli wallet new_hotkey​

btcli wallet new_coldkey​

btcli wallet set_identity​

btcli wallet get_identity​

btcli w list​

btcli w swap-hotkey​

btcli w regen-coldkey​

btcli w regen-coldkeypub​

btcli w regen-hotkey​

btcli w new-hotkey​

btcli w new-coldkey​

btcli w create​

btcli w balance​

btcli w overview​

btcli w transfer​

btcli w inspect​

btcli w faucet​

btcli w set-identity​

btcli w get-identity​

btcli w sign​

btcli w swap_hotkey​

btcli w regen_coldkey​

btcli w regen_coldkeypub​

btcli w regen_hotkey​

btcli w new_hotkey​

btcli w new_coldkey​

btcli w set_identity​

btcli w get_identity​

btcli wallets list​

btcli wallets swap-hotkey​

btcli wallets regen-coldkey​

btcli wallets regen-coldkeypub​

btcli wallets regen-hotkey​

btcli wallets new-hotkey​

btcli wallets new-coldkey​

btcli wallets create​

btcli wallets balance​

btcli wallets history​

btcli wallets overview​

btcli wallets transfer​

btcli wallets inspect​

btcli wallets faucet​

btcli wallets set-identity​

btcli wallets get-identity​

btcli wallets sign​

btcli wallets swap_hotkey​

btcli wallets regen_coldkey​

btcli wallets regen_coldkeypub​

btcli wallets regen_hotkey​

btcli wallets new_hotkey​

btcli wallets new_coldkey​

btcli wallets set_identity​

btcli wallets get_identity​

stake​

Read operations require public keys. Write operations (stake add, move, remove...) require a coldkey private key.

mind your keys

See: Coldkey and Hotkey Workstation Security

btcli stake

btcli stake add​

btcli stake remove​

btcli stake list​

btcli stake move​

btcli stake transfer​

btcli stake swap​

btcli stake child​

btcli stake child get​
btcli stake child set​
btcli stake child revoke​
btcli stake child take​

btcli stake children​

btcli stake children get​
btcli stake children set​
btcli stake children revoke​
btcli stake children take​

btcli st add​

btcli st remove​

btcli st list​

btcli st move​

btcli st transfer​

btcli st swap​

btcli st child​

btcli st child get​
btcli st child set​
btcli st child revoke​
btcli st child take​

btcli st children​

btcli st children get​
btcli st children set​
btcli st children revoke​
btcli st children take​

sudo​

Read commands (permissionless)​

  • get (same as btcli subnet hyperparameters), displays hyperparameters.
  • proposals displays proposals currently before the senate.
  • senate displays current senators.
  • get-take shows the validator take of a given validator.

Write commands (require coldkey)​

  • set sets the hyperparameters for a subnet (requires the coldkey of the subnet creator).
  • set-take sets the validator take for a validator (requires the validator's coldkey).
  • senate-vote votes on a proposal before the senate (requres a coldkey with senate permissions).
btcli sudo

btcli sudo set​

btcli sudo get​

btcli sudo senate​

btcli sudo proposals​

btcli sudo senate-vote​

btcli sudo set-take​

btcli sudo get-take​

btcli sudo senate_vote​

btcli sudo get_take​

btcli sudo set_take​

btcli su set​

btcli su get​

btcli su senate​

btcli su proposals​

btcli su senate-vote​

btcli su set-take​

btcli su get-take​

btcli su senate_vote​

btcli su get_take​

btcli su set_take​

subnets​

Read commands (permissionless)​

  • list lists subnets.
  • show alias metagraph displays info about miner and validator activity on the subnet.
  • hyperparameters shows configuration of a specific subnet.
  • price displays a graph of alpha token prices of subnets over time.
  • burn_cost shows current fee to create subnet.

Write commands (require coldkey)​

  • create: Create a subnet (requires burn fee)
  • register/pow-register: Register a UID for the hotkey on a given subnet
tip

hyperparams are set with btcli sudo.

Creating subnets requires a coldkey with sufficient balance.

Miner and validator registering a hotkey uses a coldkey, has a TAO cost unless proof-of-work

btcli subnets

btcli subnets hyperparameters​

btcli subnets list​

btcli subnets burn-cost​

btcli subnets create​

btcli subnets pow-register​

btcli subnets register​

btcli subnets metagraph​

btcli subnets show​

btcli subnets price​

btcli subnets burn_cost​

btcli subnets pow_register​

btcli s hyperparameters​

btcli s list​

btcli s burn-cost​

btcli s create​

btcli s pow-register​

btcli s register​

btcli s metagraph​

btcli s show​

btcli s price​

btcli s burn_cost​

btcli s pow_register​

btcli subnet hyperparameters​

btcli subnet list​

btcli subnet burn-cost​

btcli subnet create​

btcli subnet pow-register​

btcli subnet register​

btcli subnet metagraph​

btcli subnet show​

btcli subnet price​

btcli subnet burn_cost​

btcli subnet pow_register​

weights​

Reading weights with reveal is permissionless.

To set weights with commit, a validator must meet several requirements. See Requirements for validation.

btcli weight

btcli weights reveal​

btcli weights commit​

btcli wt reveal​

btcli wt commit​

btcli weight reveal​

btcli weight commit​

utils​

btcli utils convert​

btcli utils convert is a convenience command for performing conversions between minimal units (RAO) and TAO, or other chain-specific conversions. It is permissionless (no key required) because it performs no on-chain operation, just a local calculation.