Skip to main content

Bittensor CLI: Permissions Guide

SUBMIT A PRSUBMIT AN ISSUElast edit: Apr 01, 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
  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

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.

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.

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.