Metadata-Version: 2.4
Name: htcli
Version: 1.1.0
Summary: CLI to interact with Hypertensor
Project-URL: Repository, https://github.com/shiftlayer-llc/htcli
Project-URL: Issues, https://github.com/shiftlayer-llc/htcli/issues
Project-URL: Discord, https://discord.gg/CjVTDKaKzU
Project-URL: X, https://x.com/ShiftLayer_Ai
Author-email: ultrashiny <vasyl.123.000@gmail.com>
License-File: LICENSE
Requires-Python: <4,>=3.10
Requires-Dist: base58>=2.1.1
Requires-Dist: click<8.2.0,>=8.1.0
Requires-Dist: cryptography>=41.0.0
Requires-Dist: eth-utils<6,>=5.0.0
Requires-Dist: mnemonic<0.22,>=0.21
Requires-Dist: protobuf>=5.29.1
Requires-Dist: psutil>=7.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pyperclip>=1.10.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: requests>=2.32.4
Requires-Dist: rich>=13.0.0
Requires-Dist: scalecodec>=1.2.11
Requires-Dist: six>=1.16.0
Requires-Dist: substrate-interface<2.0.0,>=1.7.11
Requires-Dist: tenacity>=9.1.2
Requires-Dist: typer<0.16.0,>=0.15.3
Requires-Dist: web3>=6.0.0
Requires-Dist: websockets>=15.0.1
Description-Content-Type: text/markdown

# Hypertensor CLI (htcli)

[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![CLI Commands](https://img.shields.io/badge/commands-current-brightgreen.svg)](https://github.com/shiftlayer-llc/htcli)
[![Categories](https://img.shields.io/badge/categories-9%20organized-blue.svg)](https://github.com/shiftlayer-llc/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.

```bash
# 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**

```bash
# 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:

```bash
uv tool install htcli
# or
pipx install htcli
```

Verify the install:

```bash
htcli --version
htcli --help
htcli chain info
```

## Quick Start

### 1. Initialize Configuration

```bash
htcli config init
htcli config show
```

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

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

### 2. Create or Import Wallets

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

### 3. Inspect the Network

```bash
htcli chain info
htcli chain stats
htcli chain account 0x0000000000000000000000000000000000000000
```

### 4. Register and Manage Subnets

```bash
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

```bash
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

```bash
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

```bash
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

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

## Command Groups

```text
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:

```bash
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:

```bash
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:

```bash
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**

```bash
# 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`

```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:

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

## 🔧 **Advanced Usage**

### **Custom Configuration**

```bash
# 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**

```bash
# 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**

```bash
# 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**

```bash
# 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](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:

```bash
htcli --help
htcli wallet --help
htcli stake add --help
```

## 🔍 **Troubleshooting**

### **Common Issues**

#### **Connection Problems**

```bash
# Test network connectivity
htcli chain info

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

#### **Configuration Issues**

```bash
# Validate configuration
htcli config validate

# Reset configuration
htcli config init --force
```

#### **Key Management Issues**

```bash
# List available keys
htcli wallet list

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

### **Getting Help**

```bash
# 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](LICENSE) file for details.

## 🤝 **Support**

- **GitHub Issues**: [Report bugs or request features](https://github.com/shiftlayer-llc/htcli/issues)
- **Documentation**: Use `htcli --help` and category-specific help for current command details
- **Discord**: [Join the community](https://discord.gg/CjVTDKaKzU)
- **X**: [Follow ShiftLayer](https://x.com/ShiftLayer_Ai)

---

Built and maintained by [ShiftLayer LLC](https://shiftlayer.ai) for the Hypertensor network.
