Introduction
htcli is the official command-line interface for the Hypertensor ecosystem — manage wallets, operate subnets and nodes, stake, vote, and query the chain without leaving your terminal.
Hypertensor is a Substrate-based network for coordinating decentralized AI: subnets of compute and services, the operators and validators that run them, and the staking, consensus, and governance that secure it. htcli wraps every core transaction and query layer of that chain in a single, scriptable namespace.
What you can do
- Wallets — create and manage encrypted coldkey/hotkey pairs locally.
- Subnets — register networks, publish models, and set on-chain weights.
- Nodes — launch, daemonize, and monitor miner and validator nodes.
- Stake — add, remove, and delegate stake; inspect yields.
- Governance — review proposals and cast consensus votes.
- Chain — read blocks, balances, and runtime state directly from a peer.
New here? Head to Installation, then run through the Quickstart to go from a fresh machine to a registered validator in a few commands.
Design principles
Every command works the same way: predictable subcommands, consistent flags, and machine-readable output. Pass --format json to any command for scripting, or --format table (the default) for humans. No middleware, no hosted API — htcli talks to the chain directly.
Installation
Install the stable client from PyPI. htcli runs on macOS, Linux, and Windows.
Requirements
- Python 3.10+ and
pip - A network connection to a Hypertensor RPC endpoint
Install with pip
$ pip install htcli Collecting htcli Installing collected packages: requests, htcli Successfully installed htcli-1.0.0
Verify the install
$ htcli --version htcli v1.0.0
Upgrade
$ pip install --upgrade htcli
Prefer isolation? Install into a virtual environment (python -m venv .venv && source .venv/bin/activate) before running pip install htcli.
Quickstart
From a fresh install to an active validator in five commands.
1. Initialize configuration
Run the wizard once to write ~/.htcli/config.yaml with your endpoint and defaults.
$ htcli config init ? Blockchain endpoint wss://hypertensor.duckdns.org ? Default output format table Configuration initialized.
2. Create a wallet
$ htcli wallet create --name master-key Generating sr25519 keypair… Wallet "master-key" created.
3. Register a validator
$ htcli validator register --subnet 8 [SUCCESS] Registered in UID slot #11 on subnet 8.
That's it — you're on the network. Read the command reference for everything else, or browse Concepts to understand how the pieces fit together.
Configuration
htcli reads a YAML config and accepts global flags that override it per-command.
The config file
By default htcli stores configuration at ~/.htcli/config.yaml. Generate it with the wizard:
endpoint: wss://hypertensor.duckdns.org format: table wallet_dir: ~/.htcli/wallets
Global options
These flags work on every command and take precedence over the config file:
| Flag | Description |
|---|---|
-c, --config PATH | Path to an alternate configuration file. |
-e, --endpoint TEXT | Blockchain RPC endpoint (overrides config). |
-f, --format TEXT | Output format: table, json, or csv. |
-v, --verbose | Verbose logging. |
--help | Show help for any command or subcommand. |
Every flag also has an environment-variable form, e.g. HTCLI_ENDPOINT and HTCLI_FORMAT — handy for CI and daemon setups.
htcli wallet
Create, restore, inspect, and manage cryptographic coldkey and hotkey pairs locally, with AES-256 encryption at rest.
Subcommands
| Command | Description |
|---|---|
wallet create | Generate a new sr25519 coldkey/hotkey pair. |
wallet list | List wallets stored locally. |
wallet inspect | Show addresses and metadata for a wallet. |
wallet balance | Query the on-chain balance of a wallet. |
wallet import | Restore a wallet from a mnemonic. |
Create a wallet
$ htcli wallet create --name master-key Coldkey 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY Hotkey 5FHneW46xGXgs5mUiveU4sbTyGBzmstUspZC92UhjJM694ty Wallet "master-key" created.
Options
| Flag | Description |
|---|---|
--name TEXT | Wallet name (required). |
--hotkey TEXT | Hotkey label; defaults to default. |
--no-password | Skip the encryption passphrase prompt (not recommended). |
htcli subnet
Register custom validation parameters, list and inspect subnets, register models, and configure on-chain weights.
Subcommands
| Command | Description |
|---|---|
subnet list | List active subnets and their emissions. |
subnet info | Show details for one subnet by netuid. |
subnet register | Register a new subnet or model. |
subnet weights | Set or read on-chain validation weights. |
List your subnets
$ htcli subnet list --mine NETUID NAME STAKE EMISSION 8 coordination 1.284 kTAO 12.4% 19 inference 0.642 kTAO 6.1% 2 subnets active for hotkey master-key.
htcli node
Spawn, daemonize, monitor, and configure miner nodes or high-performance validation routers.
Subcommands
| Command | Description |
|---|---|
node start | Launch a node process for a subnet. |
node stop | Gracefully stop a running node. |
node status | Show heartbeat, sync state, and compute scores. |
node logs | Tail the node log stream. |
Start a node
$ htcli node start --subnet 8 Launching node process (pid 48213)… [SYNC] Compute scores updated :: epoch 9241 Node online. Operating on subnet 8.
Add --daemon to run the node detached, then watch it with htcli node status or htcli overwatch.
htcli stake
Add, remove, and delegate stake; inspect compound APY yields and delegator parameters.
Subcommands
| Command | Description |
|---|---|
stake add | Stake to a hotkey on a subnet. |
stake remove | Unstake from a hotkey. |
stake list | Show your stake positions and yields. |
stake delegate | Delegate stake to another validator. |
Add stake
$ htcli stake add --subnet 8 --amount 100 Submitting stake extrinsic… Staked 100 TAO to master-key on subnet 8.
htcli validator
Register validators and manage delegate reward settings.
$ htcli validator register --subnet 8
Full reference for validator subcommands and options is on the way. For now, see the Quickstart.
htcli governance
Review network upgrade proposals, formulate improvement budgets, and cast consensus votes.
$ htcli governance list
Full reference for governance subcommands and options is on the way.
htcli chain
Interact directly with the peer ledger — look up blocks, balances, transactions, and runtime data.
Subcommands
| Command | Description |
|---|---|
chain block | Read a block by number or --latest. |
chain balance | Query the free balance of an address. |
chain tx | Look up a transaction by hash. |
Read the latest block
$ htcli chain block --latest Block 1284812 Hash 0x9f2c…a17e Chain head synced.
htcli overwatch
Monitor node health, sync state, and consensus performance in real time.
$ htcli overwatch monitor --wallet master-key Uptime: 24h 12m :: Sync-State: Live [HEAL] Heartbeat broadcast to all subnets.
Full reference for overwatch subcommands and options is on the way.
Hypertensor Overview
Hypertensor is a Substrate-based blockchain that coordinates decentralized AI through subnets, operators, staking, consensus, and governance.
Rather than a single monolithic model or a centralized API, Hypertensor organizes compute into subnets — independent networks each focused on a task such as coordination or inference. Operators run nodes that join subnets; stake secures participation and aligns incentives; an on-chain consensus mechanism scores work each epoch; and governance lets the network evolve.
htcli is the operator's interface to all of it. The pages in this section explain each concept; the Command Reference shows the commands that act on them.
Subnets
A subnet is an independent network of compute and services registered on Hypertensor, identified by a numeric netuid.
Each subnet defines its own validation parameters and emission share. Operators register models and set on-chain weights to express which work is valuable. Manage subnets with htcli subnet.
Nodes
A node is the process an operator runs to participate in a subnet — mining work or validating it.
Nodes broadcast a heartbeat, sync chain state, and accrue compute scores each epoch. Launch and monitor them with htcli node and htcli overwatch.
Staking & Delegation
Stake is the economic security behind participation; delegation lets holders back validators they trust.
Operators stake to their own hotkeys to register and validate; holders can delegate stake to validators and share in rewards. Compound yields accrue per epoch. Manage positions with htcli stake.
Consensus & Epochs
Work on Hypertensor is scored over fixed intervals called epochs, and rewards are distributed according to consensus.
At each epoch boundary the network reconciles validator weights and compute scores, then emits rewards proportional to measured contribution. Read live chain and epoch state with htcli chain.