| title | Bittensor CLI: Permissions Guide |
|---|
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:
- Managing Your Stakes
- Miner's Guide to
BTCLI - Validator's Guide to
BTCLI - Subnet Creator's Guide to
BTCLI - Senator's Guide to
BTCLI
Other resources:
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.
-
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.
:::tip coldkey workstation security See Permissionless workstation :::
-
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.:::tip coldkey workstation security See Coldkey workstation :::
-
A hotkey workstation—which is generally a server used for mining or validation—contains a hotkey private key in the
wallet_pathlocated in thebtcli 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.:::tip hotkey workstation See Hotkey workstation security :::
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
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
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 requires paying the current neuron registration burn in TAO.
- 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.
To set weights, a validator must meet several requirements. See Requirements for validation.
The btcli config ... commands are used to configure btcli, including:
- selecting the targeted network (
finneya.k.a. mainnet ortestfor 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 setbtcli config getbtcli config clearbtcli config metagraphbtcli config add-proxybtcli config proxiesbtcli config remove-proxybtcli config update-proxybtcli config clear-proxy
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.
:::tip mind your keys See: Coldkey and Hotkey Workstation Security :::
-
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. -
new coldkeyis 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. -
regen coldkeyis 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. -
new hotkeyis 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. -
regen hotkeyis 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. -
btcli wallet createis used to initialize a new coldkey and hotkey workstation with new seed phrases for both. This is a high security risk operation due to the inherent risk of handling the seed phrase. -
btcli wallet associate-hotkeyis used to associate a hotkey with a coldkey on chain.
btcli wallet balance: Displays a wallet balance.btcli wallet overview: Displays a wallet overview.btcli wallet list: Displays all the wallets and their corresponding hotkeys that are located in the wallet path.
swap-hotkeyrotates a hotkey coldkey owned by the coldkey.swap-coldkeyannounces and executes a coldkey swap to transfer assets on the coldkey to the destination coldkey.swap-checkchecks to see if a coldkey has an existing swap announcement.new-hotkeycreates a new hotkey owned by the coldkey.transfertransfers TAO to another coldkey.set-identitysets the coldkey's public identity information.sign(with coldkey) signs a message with the coldkey.
sign(with hotkey): sign a message with the hotkeyverify: Verify a message signature using the signer's public key or SS58 address
`btcli wallet`
#### `btcli wallet list` #### `btcli wallet swap-hotkey` #### `btcli wallet swap-coldkey announce` #### `btcli wallet swap-coldkey execute` #### `btcli wallet swap-coldkey dispute` #### `btcli wallet swap-coldkey clear` #### `btcli wallet swap-check` #### `btcli wallet regen-coldkey` #### `btcli wallet regen-coldkeypub` #### `btcli wallet regen-hotkey` #### `btcli wallet regen-hotkeypub` #### `btcli wallet new-hotkey` #### `btcli wallet new-coldkey` #### `btcli wallet associate-hotkey` #### `btcli wallet create` #### `btcli wallet balance` #### `btcli wallet overview` #### `btcli wallet transfer` #### `btcli wallet inspect` #### `btcli wallet set-identity` #### `btcli wallet get-identity` #### `btcli wallet sign` #### `btcli wallet verify`Read operations require public keys. Write operations (stake add, move, remove...) require a coldkey private key.
:::tip mind your keys See: Coldkey and Hotkey Workstation Security :::
btcli stake
#### `btcli stake add` #### `btcli stake remove` #### `btcli stake auto` #### `btcli stake set-auto` #### `btcli stake list` #### `btcli stake move` #### `btcli stake transfer` #### `btcli stake swap` #### `btcli stake wizard` #### `btcli stake child` ##### `btcli stake child get` ##### `btcli stake child set` ##### `btcli stake child revoke` ##### `btcli stake child take` #### `btcli stake set-claim` #### `btcli stake process-claim`get(same asbtcli subnet hyperparameters), displays hyperparameters.proposalsdisplays proposals currently before the senate.senatedisplays current senators.get-takeshows the validator take of a given validator.
setsets the hyperparameters for a subnet (requires the coldkey of the subnet creator).trimsets the maximum number of UIDs on a subnet (requires the coldkey of the subnet creator).stake-burnallows subnet owners to buyback their Alpha (requires the coldkey of the subnet creator).set-takesets the validator take for a validator (requires the validator's coldkey).senate-votevotes on a proposal before the senate (requres a coldkey with senate permissions).
`btcli sudo`
#### `btcli sudo set` #### `btcli sudo get` #### `btcli sudo trim` #### `btcli sudo stake-burn` #### `btcli sudo senate` #### `btcli sudo proposals` #### `btcli sudo senate-vote` #### `btcli sudo set-take` #### `btcli sudo get-take`listlists subnets.showaliasmetagraphdisplays info about miner and validator activity on the subnet.hyperparametersshows configuration of a specific subnet.pricedisplays a graph of alpha token prices of subnets over time.burn-costshows current fee to create subnet.check-startchecks if a subnet's emission schedule can be started.get-identityretrieves on-chain identity for a given subnet.mechanisms countshows how many mechanisms are registered under a subnet.mechanisms emissionsdisplay the current emission split across mechanisms for a subnet.
create: Create a subnet (requires burn fee).register: Register a UID for the hotkey on a given subnet (requires burn fee).start: Starts a subnet's emission schedule.set-identity: Sets on-chain identity for a given subnet.set-symbol: Sets on-chain symbol for a given subnet.mechanisms set: Configures how many mechanisms are registered for a subnet.mechanisms split-emissions: Updates the emission split across mechanisms for a subnet.
:::tip
Subnet hyperparameters are set with btcli sudo set.
:::
Creating subnets requires a coldkey with sufficient balance to cover burn costs.
`btcli subnets`
#### `btcli subnets hyperparameters` #### `btcli subnets list` #### `btcli subnets burn-cost` #### `btcli subnets create` #### [`btcli subnets register`](../btcli/btcli.md#btcli-subnets-register) #### `btcli subnets metagraph` #### `btcli subnets show` #### `btcli subnets price` #### `btcli subnets check-start` #### `btcli subnets start` #### `btcli subnets get-identity` #### `btcli subnets set-identity` #### `btcli subnets set-symbol`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`The proxy command group allows you to create and manage proxy accounts for secure delegation of account permissions.
There are no read-only proxy commands in btcli. To view proxies associated with an account, use the SDK's get_proxies_for_real_account() method or query chain state directly via Polkadot.js.
proxy create: Creates a new pure proxy account. This generates a keyless account that can only be controlled through the proxy relationship. Requires the spawner's coldkey.proxy add: Adds a standard proxy relationship, authorizing a delegate account to perform specific operations on behalf of the real account. Requires the real account's coldkey.proxy remove: Removes a proxy relationship, revoking the delegate's permissions. Requires the real account's coldkey.proxy kill: Permanently destroys a pure proxy account. Warning: All funds in the pure proxy will be permanently lost. Requires the spawner's coldkey.
proxy execute: Executes a previously announced proxy call after the delay period has passed. This is used with delayed proxies (non-zero delay).
:::tip Address book management
The btcli config commands provide convenient local address book management for proxies:
btcli config add-proxy- Save a proxy to your local address bookbtcli config proxies- List all proxies in your address bookbtcli config remove-proxy- Remove a proxy from your address book (local only, does not affect on-chain state)btcli config update-proxy- Update a proxy entry in your address book :::
:::info Using proxies with other commands
Many btcli commands support the --proxy flag, allowing you to execute operations through a proxy account. You can specify either:
- The proxy's SS58 address directly:
--proxy 5ABC... - The proxy's name from your address book:
--proxy my-staking-proxy
For delayed proxies, use the --announce-only flag to announce a call without executing it immediately.
:::
See also: Proxies Documentation
`btcli proxy`
The btcli crowd commands are used to create and manage crowdloans on the network.
crowd contribute: Pledges TAO contribution from your wallet to a specific crowdloan campaign.crowd withdraw: Recalls your contributed TAO from a non-finalized crowdloan.crowd finalize: Finalizes a crowdloan that has reached its cap if the finalization conditions are met. Finalizing a crowdloan either transfers the funds to the target account or executes the underlying crowdloan call.crowd create: Initializes a new crowdloan campaign with a defined funding cap, duration, and purpose.crowd update: Modifies the details of an existing crowdloan campaign. This command can only be called by the crowdloan creator.crowd refund: Triggers the return of TAO to all contributors of an non-finalized crowdloan. This command can only be called by the crowdloan creator.crowd dissolve: Dissolves a crowdloan entirely and removes its record from the blockchain. This command can only be called by the crowdloan creator after all contributors have been refunded.crowd list: Displays a summarized list of all active and past crowdloans, including their current status on the selected network.crowd info: Provides detailed information about a specific crowdloan.
`btcli crowd`
The btcli liquidity commands are used to provide and manage trading liquidity for specific subnets. For more information, see Liquidity positions.
liquidity add: Add liquidity to the swap (as a combination of TAO + Alpha).liquidity list: Shows a wallet's liquidity positions in given subnet.liquidity modify: Modifies the liquidity position for the given subnet.liquidity remove: Remove liquidity from the swap (as a combination of TAO + Alpha).
The btcli axon commands are used to configure or remove a neuron's serving endpoint on the network.
axon resetis used to reset the axon information for a neuron on the network by setting the IP address and port to0.0.0.0and1respectively.axon setsets the axon information for a neuron on the network.
The btcli utils ... commands are utility commands used for specialized operations like checking network latency and performing token conversions.
utils convertis 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.utils latencyreturns the latency of all finney-like nodes. You can also view latency on additional networks by using the--networkflag.
view dashboardgenerates an HTML dashboard that provides a comprehensive overview of the entire network, listing all subnets and detailing the wallet's stake information across each of them.