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.

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

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://rpc.htcli.io/
  ? Default output format  table
  Configuration initialized.

2. Create keys

$ htcli wallet generate-coldkey --name master-key
$ htcli wallet generate-hotkey --coldkey master-key --hotkey master-hot
  Coldkey "master-key" and hotkey "master-hot" created.

3. Register a validator, then a node

Register a validator first; it returns a validator_id that your subnet nodes register under.

$ htcli validator register --hotkey master-hot --delegate-rate 10 --coldkey master-key
  Validator registered :: validator_id 11

$ htcli node register --validator-id 11 --subnet-id 8 --hotkey node-hot --stake 100 --coldkey master-key
  [SUCCESS] Node registered on subnet 8 under validator 11.

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://rpc.htcli.io/
format:   table
wallet_dir: ~/.htcli/wallets

Global options

These flags work on every command and take precedence over the config file:

htcli config

Initialize, view, and validate htcli configuration — the chain endpoint, output format, and wallet paths.

Subcommands

Initialize configuration

$ htcli config init
  Configuration written to ~/.htcli/config.yaml

See Configuration for the file format and global flags.

htcli wallet

Generate, import, rotate, and inspect cryptographic coldkey and hotkey pairs locally, with encrypted storage in ~/.htcli/wallets/.

Subcommands

Generate a coldkey

$ htcli wallet generate-coldkey --name master-key
  Generating ECDSA keypair…
  Address  0xBbCdFE56402109104dcA757B0B644035Ac3Fd321
  Coldkey "master-key" created in ~/.htcli/wallets.

Options

htcli subnet

Register and activate subnets, and inspect subnet information and network-wide statistics.

Subcommands

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

Register, list, inspect, and monitor nodes across the subnets you operate.

Subcommands

Register a node under a validator

Nodes register under a validator, so pass the validator_id returned by htcli validator register (see validator).

$ htcli node register --validator-id 11 --subnet-id 8 --hotkey node-hot --stake 100 --coldkey master-key
  [SUCCESS] Node registered on subnet 8 under validator 11.

htcli stake

Add, remove, and delegate stake; inspect compound APY yields and delegator parameters.

Subcommands

Add stake

$ htcli stake add --subnet-id 1 --node-id 1 --amount 100
  Submitting stake extrinsic…
  Staked 100 TENSOR on subnet 1, node 1.

htcli chain

Query the chain directly — network statistics, account info, balances, and blocks.

Subcommands

Network info

$ htcli chain info
  Block        1284812
  Validators   256   ::   spec_version 142
  Chain head synced.

htcli consensus

Participate in consensus — submit proposals and attestations for the subnets you validate.

Subcommands

Submit a proposal

$ htcli consensus propose --wallet master-key --subnet 1 --data 0x123
  Proposal submitted for subnet 1.

htcli governance

Set on-chain network parameters that govern how Hypertensor operates.

Subcommands

Set a parameter

$ htcli governance set-param --wallet master-key --param max_subnets --value 64
  Parameter update submitted.

htcli overwatch

Register and operate overwatch nodes that monitor network health and consensus.

Subcommands

Register an overwatch node

$ htcli overwatch register --coldkey master-key --hotkey master-hot --stake 1000
  Overwatch node registered.

htcli validator

Register validators and manage their delegation settings, keys, and on-chain identity.

Subcommands

Register a validator

$ htcli validator register --hotkey master-hot --delegate-rate 10 --coldkey master-key
  Validator registered :: validator_id 11

Key switches

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.