Bittensor CLI: Permissions Guide
The Bittensor CLI permissions guide explains why different BTCLI actions require different forms of authority. The official Bittensor CLI: Permissions Guide says some actions require a coldkey private key, some require a hotkey private key, and some require no private key at all. It also notes that some actions depend on balances, validator permits, subnet roles, or Senate participation.
This article summarizes that permission model without reproducing the command matrix. The important point for readers is that “can run BTCLI” is not the same as “can perform every BTCLI action.” The authority depends on which key is present, what role the account has, and whether the action is a read, a signature, or an on-chain state change.
Permission Model
BTCLI permissions are easiest to read as layers. A permissionless layer uses public information and does not need private wallet material. A hotkey layer covers operational activity for mining, validation, and subnet participation. A coldkey layer covers ownership-sensitive actions such as balances, stake, hotkey management, subnet ownership, and some governance actions.
Those layers are about authority, not just software installation. The same command-line interface can be used on different workstations, but a workstation with only public keys cannot sign the same actions as a workstation that holds hotkey or coldkey material.
Permissionless Reads
Permissionless BTCLI work uses public chain data. Public keys can identify wallets, subnets, validators, miners, balances, and stake records without exposing a private key. That is why read-only inspection belongs in the lowest-risk category of the permission model.
This category matters because it separates observation from action. A user can inspect public network state without making a transaction, changing a balance, registering a UID, setting weights, or casting a vote. If a task only answers “what is currently visible on chain,” it should not require private signing authority.
Coldkey Authority
Coldkey authority is the highest-risk part of the BTCLI permission model. The official guide describes the coldkey as the primary, fully privileged key, and the wallet docs frame it as the key used for sensitive operations such as transfers, staking, subnet management, governance functions, and hotkey management.
The practical implication is that coldkey-required actions should be treated differently from ordinary queries. A coldkey can authorize changes that affect TAO, alpha stake, subnet ownership, or the relationship between coldkeys and hotkeys. Losing or leaking that authority is therefore a wallet-security issue, not merely a local CLI inconvenience.
Hotkey Authority
Hotkeys are operational keys. The permissions guide associates hotkeys with miner and validator activity, including serving requests, making signed requests, setting weights, and being visible to stakers and network participants. A hotkey does not have the same ownership authority as a coldkey, but it can still affect a participant’s operational reputation and subnet behavior.
This distinction prevents two common mistakes. First, a hotkey leak should not be treated as harmless just because it cannot directly transfer the primary coldkey’s balance. Second, a coldkey should not be placed in a hotkey workstation simply because both keys are used somewhere in BTCLI.
Balance and Resource Requirements
Not every requirement is a key requirement. Some BTCLI actions depend on available TAO, alpha stake, registration burns, fees, or other chain resources. The permissions guide separates these resource requirements from key authority: an action may have the right signer and still fail if the required balance or resource condition is not met.
For readers, this means “permission” has more than one meaning. There is cryptographic permission to sign, role permission to act in a particular network position, and economic capacity to pay or lock the required amount. A clear article should identify which kind of requirement it is describing.
Role-Based Requirements
Some actions depend on network role rather than only key possession. Examples in the official guide include validator permits and Senate requirements. A key may be able to sign a transaction while the account still lacks the network status needed for a specific action.
This is especially important for governance and validation topics. A senator-related action requires Senate eligibility, and a validator-weight action depends on validation requirements. BTCLI can expose the workflow, but the chain still enforces the relevant role boundary.
Workstation Context
The permissions model connects directly to workstation security. A permissionless workstation can inspect public data. A hotkey workstation supports miner or validator operation. A coldkey workstation carries much higher authority. The official permissions guide separates those authority levels, and the workstation-security guidance treats them as different risk environments rather than interchangeable devices (Bittensor CLI: Permissions Guide, Coldkey and hotkey workstation security).
A good reader-facing summary should therefore ask two questions: what authority does this BTCLI action require, and where should that authority live? The safest answer is often to keep public inspection, hotkey operation, and coldkey custody in separate environments.
Reader Boundary
This article explains the permission model. It does not list every BTCLI subcommand, duplicate the reference table, or provide wallet procedures. For the exact current command requirements, readers should use the official BTCLI permissions guide and reference documentation.
Config Setup Sits Outside Signing Authority
The official Bittensor CLI: Permissions Guide treats configuration setup as separate from signing authority. Choosing a target network and setting where wallet material is stored does not require a coldkey private key, a hotkey private key, or any other signing credential.
Those setup actions are meant to run on every BTCLI workstation type, including permissionless, hotkey, and coldkey environments, because they initialize the tool rather than authorize on-chain changes. Network selection and wallet storage location therefore belong to CLI preparation, not to the same permission layer as transfers, staking, registration, or weight setting (Coldkey and Hotkey Workstation Security).
That split helps explain why a machine can be correctly configured for BTCLI and still unable to perform signed actions. Configuration answers where the CLI looks and which chain it targets; Coldkey and Hotkey authority still determine whether private signing material is present when a state-changing action is attempted.
References: Bittensor CLI: Permissions Guide, Coldkey and Hotkey Workstation Security
Hotkey Workstations Keep Public Coldkey Context
Official permissions guidance describes a hotkey workstation as carrying two different key materials at once. It holds the hotkey private key needed for miner or validator signing, and it also holds the corresponding coldkey public key for the wallet that owns that hotkey (Bittensor CLI: Permissions Guide).
That pairing is not the same as loading a coldkey private key onto an operational server. The public-side coldkey material lets the workstation stay linked to the correct wallet identity while operational signing still flows through the hotkey layer described in Glossary: Hotkey-Coldkey Pair vocabulary.
The same guide also notes that TAO and alpha stake can move only with coldkey authority, while a leaked hotkey can be replaced through coldkey-controlled recovery. A hotkey workstation therefore supports subnet operation without granting custody authority, which is why the permissions model treats hotkey exposure as serious but not equivalent to coldkey compromise.
References: Bittensor CLI: Permissions Guide, Glossary: Hotkey-Coldkey Pair
Subnet Creation Burns Follow a Dynamic Auction
Some BTCLI actions fail for economic reasons even when the correct signer is present. Subnet creation is one example where the required TAO amount is not fixed. The official Create a Subnet documentation describes subnet creation burn cost as dynamic: the price doubles whenever a new subnet is created and then lowers gradually over time.
The permissions guide presents that mechanism as a distributed auction in which the current creation price reflects what participants are willing to pay under uncertainty about future demand (Bittensor CLI: Permissions Guide). That is a different resource question from ordinary transfer balance checks or the neuron registration burn paid when a hotkey registers on an existing subnet.
A coldkey with signing authority can still fail subnet creation if the wallet does not hold enough TAO for the current burn cost at submission time. The Glossary: Burn cost label therefore marks a moving economic gate tied to recent subnet creation activity, not a static fee table entry.
References: Create a Subnet, Glossary: Burn cost
Relationship to Coldkeys
BTCLI permissions and a coldkey are related but different scopes in Bittensor wallet authority vocabulary. A coldkey is the security-sensitive key that controls TAO and stake, while BTCLI permissions name which command-line actions require coldkey authority versus hotkey authority or permissionless reads. The Glossary: Coldkey describes the coldkey as the key that controls TAO and stake, and the Bittensor CLI: Permissions Guide describes coldkey-required actions as the highest-risk part of the permission model.
For readers, coldkey names the protected ownership key, while BTCLI permissions name when that key must be present to authorize a CLI action.
References: Glossary: Coldkey, Bittensor CLI: Permissions Guide
Relationship to Hotkeys
BTCLI permissions and a hotkey are related but different scopes in Bittensor wallet authority vocabulary. A hotkey is the operational key used for routine on-chain actions, while BTCLI permissions name which command-line actions require hotkey authority for miner and validator activity. The Glossary: Hotkey describes the hotkey as the operational key used by miners, validators, and subnet actors, and the Bittensor CLI: Permissions Guide associates hotkeys with operational activity such as setting weights.
For readers, hotkey names the operational key role, while BTCLI permissions name when that key must be present for CLI operational actions.
References: Glossary: Hotkey, Bittensor CLI: Permissions Guide
Relationship to Chain Reads
BTCLI permissions and chain reads are related but different parts of Bittensor information-access vocabulary. Chain reads name observation of public chain state without submitting a new action, while BTCLI permissions place permissionless reads in the lowest-risk category of the CLI permission model. The Transaction Fees in Bittensor documentation states that reading chain state is free, and the Bittensor CLI: Permissions Guide says some actions require no private key at all.
For readers, chain reads name the observation concept, while BTCLI permissions name which CLI tasks can stay in that permissionless read category.
References: Transaction Fees in Bittensor, Bittensor CLI: Permissions Guide
Relationship to Subtensor
BTCLI permissions and Subtensor are related but different parts of Bittensor chain vocabulary. Subtensor names Bittensor’s layer 1 blockchain and system of record, while BTCLI permissions name which forms of wallet authority are required before CLI actions can interact with that chain layer. The Glossary: Subtensor describes the blockchain layer, and the Bittensor CLI: Permissions Guide explains why different BTCLI actions require different forms of authority on chain.
For readers, Subtensor names the chain layer, while BTCLI permissions name the authority layers needed before CLI actions reach that layer.
References: Glossary: Subtensor, Bittensor CLI: Permissions Guide
Development Stage Context
The Introduction to Bittensor describes subnet development as moving from localnet to testnet and then mainnet. For btcli permissions, that sequence changes how readers should interpret evidence about CLI signing authority and wallet permission requirements.
In localnet, btcli commands can be tested in an isolated environment. Results reflect local wallet and key configuration and do not represent the permission requirements that apply on a production network.
On testnet, btcli permission behavior can be observed in a shared, non-production network. This separates the result from a private local environment while keeping CLI actions outside mainnet wallet and staking state.
On mainnet, btcli permissions govern actual signing authority for TAO transfers, staking, subnet registration, and other wallet operations. The Bittensor CLI: Permissions Guide describes which key type is required for each command category on the production network.
The Bittensor Networks reference separates mainnet, testnet, and localnet. A btcli permission example from one environment should not be read as identical evidence about CLI signing requirements in another environment.
For readers, this keeps btcli permission examples from being treated as carrying more weight than their environment supports. Localnet, testnet, and mainnet contexts can all involve CLI commands, but permission requirements and consequences differ across environments.
Read Versus Sign Boundary
BTCLI permission claims should separate read-only inspection from signed state changes. The permissions guide distinguishes actions that require no private key from actions requiring hotkey or coldkey authority, while transaction-fee documentation places state-changing submissions in the transaction context (Bittensor CLI: Permissions Guide, Transaction Fees in Bittensor).
This boundary helps readers avoid over-granting keys to a workstation. If an action only observes public chain state, it should not be described with the same authority expectations as staking, transfers, hotkey management, or validator operations.
Public Identifier Scope
A permissionless BTCLI lookup can still name a wallet, hotkey, subnet, or other public identifier. That identifier helps select public chain data; it is not the same thing as loading private wallet material for a signed action (Bittensor CLI: Permissions Guide, Wallets, Coldkeys and Hotkeys in Bittensor).
For readers, this keeps “uses an address” separate from “can sign with that address’s key.” The permission boundary is crossed when BTCLI needs hotkey or coldkey authority, not when a public identifier is used for inspection.