Hypertensor CLI (htcli)

A command-line interface for interacting with the Hypertensor blockchain network. htcli helps users configure endpoints, manage wallets, inspect chain state, register subnets and nodes, operate validators, and submit staking transactions from a terminal.

Built and maintained by ShiftLayer LLC, the package provides a Typer-based CLI with Rich terminal output, table/JSON/CSV formats, wallet-aware commands, and live Hypertensor RPC integration.

Install

htcli is distributed as a Python package and requires Python 3.10 or newer.

# Install from PyPI (after production release)
pip install htcli

# Install a dev release from TestPyPI.
# Replace 1.1.1.dev3 with the latest htcli dev version shown on TestPyPI.
pip install --only-binary=:all: --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple "htcli==1.1.1.dev3"

TestPyPI does not mirror PyPI dependencies, so --extra-index-url https://pypi.org/simple is required when testing dev releases. Installing the exact dev version avoids enabling prerelease dependencies globally, and --only-binary=:all: prevents native dependencies from falling back to local Rust builds.

Install from Source

# Clone the repository
git clone https://github.com/shiftlayer-llc/htcli.git
cd htcli

# Install with uv (recommended)
uv pip install -e .

# Or install with pip
pip install -e .

For isolated CLI installation, use a tool installer:

uv tool install htcli
# or
pipx install htcli

Verify the install:

htcli --version
htcli --help
htcli chain info

Quick Start

1. Initialize Configuration

htcli config init
htcli config show

By default, htcli connects to wss://rpc.htcli.io/. You can override the endpoint per command:

htcli --endpoint wss://custom.endpoint.example chain info

2. Create or Import Wallets

htcli wallet generate-coldkey --name my-coldkey
htcli wallet generate-hotkey --coldkey my-coldkey --hotkey my-hotkey
htcli wallet list

3. Inspect the Network

htcli chain info
htcli chain stats
htcli chain account 0x0000000000000000000000000000000000000000

4. Register and Manage Subnets

htcli subnet register \
  --coldkey my-coldkey \
  --name my-subnet \
  --repo https://github.com/example/subnet \
  --initial-coldkeys <coldkey-1>,<coldkey-2>,<coldkey-3> \
  --key-types Ecdsa,Ecdsa,Ecdsa

htcli subnet activate --subnet-id 1 --coldkey my-coldkey
htcli subnet info --subnet-id 1

5. Register and Inspect Nodes

htcli node register \
  --subnet-id 1 \
  --validator-id 1 \
  --hotkey <address> \
  --peer-id <peer-id> \
  --stake 100 \
  --coldkey my-coldkey

htcli node list --subnet-id 1
htcli node info --subnet-id 1 --node-id 1

6. Operate Validators

htcli validator register --hotkey <address> --delegate-rate 10 --coldkey my-coldkey
htcli validator update-delegate-rate --validator-id 1 --delegate-rate 12 --coldkey my-coldkey
htcli validator update-identity --validator-id 1 --name "My Validator" --url https://example.com --coldkey my-coldkey

7. Stake and Delegate

htcli stake add --subnet-id 1 --node-id 1 --amount 100
htcli stake delegate-add --subnet-id 1 --amount 100 --coldkey my-coldkey
htcli stake list --coldkey <wallet-or-address>
htcli stake claim --coldkey my-coldkey

8. Use Script-Friendly Output

htcli --format json chain stats
htcli --format csv subnet list

Command Groups

htcli
├── config      # Configuration management
├── wallet      # Coldkey and hotkey wallet management
├── chain       # Chain info, stats, blocks, transactions, and accounts
├── subnet      # Subnet registration and owner operations
├── node        # Node registration, listing, info, and updates
├── validator   # Validator registration, delegation, and identity
├── stake       # Direct and delegated staking operations
├── consensus   # Consensus proposals and attestations
├── governance  # Network parameter governance
└── overwatch   # Overwatch node operations

Use htcli --help, htcli <category> --help, or htcli <category> <command> --help for the authoritative command list.

Key Features

• Wallet management: Generate, restore, list, describe, rotate, and update coldkeys and hotkeys.
• Hypertensor RPC access: Query live network state through WebSocket RPC endpoints.
• Subnet and node operations: Register, activate, update, pause, unpause, inspect, and remove resources.
• Validator operations: Register validators, update delegate settings, rotate keys, and manage identity.
• Staking operations: Add/remove direct stake, delegate stake, transfer stake, swap stake, and claim unbonded tokens.
• Structured output: Use table output by default or JSON/CSV for scripts.
• Safety prompts: Confirmation and validation for transaction-producing commands.

Contributing From Source

Clone the repository and install the project in editable mode:

git clone https://github.com/shiftlayer-llc/htcli.git
cd htcli
uv sync
uv run htcli --help

Run the local checks before opening a pull request:

uv run pytest
uv run python -m build
uv run --with twine twine check dist/*

Development workflow:

1. Create a feature branch from dev.
2. Make focused changes and add tests for changed behavior.
3. Run the relevant test suite and package checks.
4. Open a pull request against dev.

Wallet-Based Filtering

Some asset commands support explicit wallet or coldkey filters:

htcli subnet list --coldkey <wallet-or-address>
htcli stake list --coldkey <wallet-or-address>

📋 Command Structure

Consistent Format

Commands follow Typer's standard command-group format:

htcli [global-options] <category> <command> [command-options] [arguments]

Most transaction-producing commands use named options such as --coldkey, --subnet-id, and --amount. Use command help for the authoritative signature.

🎨 User Experience Features

Interactive Guidance

Every complex operation includes comprehensive guidance:

╭────────────────────── 💰 Adding Stake to Node ──────────────────────────╮
│ This operation will stake TENSOR tokens to support a node in a subnet.   │
│                                                                          │
│ 📋 Requirements:                                                         │
│ • Valid subnet ID and node ID                                            │
│ • Sufficient TENSOR balance in your account                              │
│ • Node must be active and accepting stake                                │
│                                                                          │
│ 💡 Tips & Warnings:                                                      │
│ 💡 Staked tokens are locked and earn rewards                             │
│ ⚠️ Unstaking has an unbonding period before tokens are available        │
│                                                                          │
│ 📊 Current Operation:                                                    │
│ • Subnet ID: 1                                                           │
│ • Stake Amount: 1.000000000000000000 TENSOR                              │
╰──────────────────────────────────────────────────────────────────────────╯

Safety Features

• Confirmation prompts for destructive operations
• Warning messages for unbonding periods and risks
• Input validation with helpful error messages
• Recovery guidance for failed operations

Flexible Output

# Table format (default)
htcli chain stats

# JSON format for scripting
htcli --format json chain stats

# CSV format for data analysis
htcli --format csv chain stats

⚙️ Configuration

Configuration File

Default location: ~/.htcli/config.yaml

# Network Configuration
network:
  endpoint: "wss://rpc.htcli.io/"
  ws_endpoint: "wss://rpc.htcli.io/"
  timeout: 30
  retry_attempts: 3

# Output Configuration
output:
  format: "table"
  verbose: false
  color: true

# Wallet Configuration
wallet:
  path: "~/.htcli/wallets"
  default_name: "default"
  encryption_enabled: true

Environment Variables

Override configuration with environment variables:

export HTCLI_NETWORK_ENDPOINT="wss://custom-endpoint.com"
export HTCLI_OUTPUT_FORMAT="json"
export HTCLI_WALLET_PATH="/custom/wallet/path"

🔧 Advanced Usage

Custom Configuration

# Use custom config file
htcli --config /path/to/config.yaml chain info

# Override endpoint temporarily
htcli --endpoint wss://custom.endpoint.com chain info

# Enable verbose output
htcli --verbose chain info

Scripting Examples

# Get network stats in JSON for processing
STATS=$(htcli --format json chain stats)
echo $STATS | jq '.total_subnets'

# Check multiple accounts
for addr in addr1 addr2 addr3; do
    htcli --format json chain account $addr
done

# Automated staking workflow
htcli stake add --subnet-id 1 --node-id 1 --amount $AMOUNT

Batch Operations

# Register multiple subnets
for subnet in subnet1 subnet2 subnet3; do
    htcli subnet register \
        --coldkey my-coldkey \
        --name $subnet \
        --repo https://github.com/example/$subnet \
        --initial-coldkeys <coldkey-1>,<coldkey-2>,<coldkey-3> \
        --key-types Ecdsa,Ecdsa,Ecdsa
done

# Check status of multiple nodes
for node_id in {1..10}; do
    htcli node info --subnet-id 1 --node-id $node_id
done

🛠️ Source Reference

Project Structure

htcli/
├── src/htcli/           # Main CLI source code
│   ├── commands/        # Command implementations
│   │   ├── config/      # Configuration commands
│   │   ├── subnet/      # Subnet commands
│   │   ├── node/        # Node commands
│   │   ├── stake/       # Staking commands
│   │   ├── wallet/      # Wallet commands
│   │   └── chain/       # Chain commands
│   ├── client/          # Blockchain client modules
│   ├── models/          # Request/response models
│   ├── utils/           # Utility functions
│   └── main.py          # CLI entry point
├── tests/               # Test suite
└── pyproject.toml       # Project configuration

Testing

# Run all tests
uv run pytest

# Run specific test categories
uv run pytest tests/unit/
uv run pytest tests/integration/

# Run opt-in live runtime validation
HTCLI_RUN_LIVE=1 uv run pytest tests/live -m live

# Run with coverage
uv run pytest --cov=src/htcli

See LIVE_VALIDATION.md for the current live-chain validation endpoint, account setup, and known runtime migration gaps.

📚 Documentation

Use the built-in command help for the current command reference:

htcli --help
htcli wallet --help
htcli stake add --help

🔍 Troubleshooting

Common Issues

Connection Problems

# Test network connectivity
htcli chain info

# Use custom endpoint
htcli --endpoint wss://backup.endpoint.com chain info

Configuration Issues

# Validate configuration
htcli config validate

# Reset configuration
htcli config init --force

Key Management Issues

# List available keys
htcli wallet list

# Generate new key if needed
htcli wallet generate-coldkey --name backup-key

Getting Help

# General help
htcli --help

# Category help
htcli stake --help

# Command help
htcli stake add --help

🚀 Performance & Reliability

Performance Metrics

• Command Response Times: < 0.1s for help, 1-3s for network operations
• Success Rates: 100% command execution success
• Error Handling: Comprehensive error recovery and user guidance
• Network Resilience: Automatic retry with exponential backoff

Production Ready Features

• 18-digit TENSOR precision for accurate token calculations
• Real blockchain integration with transaction submission
• Comprehensive input validation and error handling
• Professional user interface with rich console output
• Extensive logging and debugging capabilities

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🤝 Support

• GitHub Issues: Report bugs or request features
• Documentation: Use htcli --help and category-specific help for current command details
• Discord: Join the community
• X: Follow ShiftLayer

Built and maintained by ShiftLayer LLC for the Hypertensor network.