🌊 poolcli

A command-line interface for managing Bittensor subnet pool operations. poolcli simplifies wallet authentication, developer key management, and pool administration through an intuitive CLI.

Features

• Wallet Authentication: Seamless Bittensor wallet integration with secure token management
• Developer Key Management: Create, list, and manage developer keys with invoice tracking
• Pool Management: Create, list, and inspect subnet pools
• Session Management: Automatic token caching and re-authentication support

Installation

pip install poolcli
or
uv add poolcli

Or install from source:

git clone <repository-url>
cd poolcli
pip install -e .

Requirements

• Python 3.10+

Quick Start

1. Authenticate

poolcli auth login --wallet-name my_wallet

You'll be prompted for your hotkey (defaults to "default" if not specified).

2. View Your Wallets

poolcli wallet list

This displays all available coldkeys and their associated hotkeys with addresses.

3. Create a Developer Key

poolcli key create --wallet-name my_wallet

This command will:

• Authenticate with your wallet
• Create an invoice for a developer key
• Prompt for payment in TAO
• Optionally create a pool after successful payment

4. Create a Pool

poolcli pool create --wallet-name my_wallet

5. View Your Pools

poolcli pool list --wallet-name my_wallet

6. Initiate Refund

poolcli refund create --wallet-name my_wallet

Command Reference

Authentication (auth)

Manage authentication and sessions.

poolcli auth login

Authenticate with your Bittensor wallet.

poolcli auth login \
  --wallet-name my_wallet \
  --hotkey default \
  --force  # Force re-authentication

Options:

• --wallet-name (required): Your Bittensor wallet name
• --hotkey: Hotkey name (defaults to "default")
• --backend-url: Backend API URL
• --force: Force re-authentication even if a valid session exists

poolcli auth status

Check your current authentication status.

poolcli auth status --wallet-name my_wallet

poolcli auth logout

Clear all stored authentication tokens.

poolcli auth logout

Key Management (key)

Manage developer keys and invoices.

poolcli key create

Create a new developer key invoice and optionally proceed with payment.

poolcli key create \
  --wallet-name my_wallet \
  --hotkey default \

Options:

• --wallet-name (required): Your Bittensor wallet name
• --hotkey: Hotkey to use for the key (defaults to "default")
• --backend-url: Backend API URL
• --force: Force re-authentication

poolcli key list

List all developer keys for your wallet.

poolcli key list \
  --wallet-name my_wallet \
  --page 1 \
  --limit 15 \
  --status active

Options:

• --wallet-name (required): Your Bittensor wallet name
• --page: Page number for pagination (default: 1)
• --limit: Number of keys per page (default: 15)
• --status: Filter by status: active, expired, or unused
• --backend-url: Backend API URL

poolcli key invoice get

Check the status of a specific invoice.

poolcli key invoice get <invoice-id> --wallet-name my_wallet

Arguments:

• invoice-id: The invoice ID to check

Options:

• --wallet-name (required): Your Bittensor wallet name
• --backend-url: Backend API URL

Pool Management (pool)

Manage your Bittensor subnet pools.

poolcli pool create

Create a new pool for your wallet.

poolcli pool create \
  --wallet-name my_wallet \
  --hotkey default \

Options:

• --wallet-name (required): Your Bittensor wallet name
• --hotkey: Hotkey to use for the pool (defaults to "default")
• --backend-url: Backend API URL
• --force: Force re-authentication

poolcli pool list

List all pools for your wallet.

poolcli pool list \
  --wallet-name my_wallet \
  --page 1 \
  --limit 15

Options:

• --wallet-name (required): Your Bittensor wallet name
• --page: Page number for pagination (default: 1)
• --limit: Number of pools per page (default: 15)
• --backend-url: Backend API URL
• --force: Force re-authentication

poolcli pool show

View detailed information about a specific pool.

poolcli pool show <pool-id> --wallet-name my_wallet

Arguments:

• pool-id: The pool ID to inspect

Options:

• --wallet-name (required): Your Bittensor wallet name
• --backend-url: Backend API URL

Refund Management (refund)

Initiate Refund Process

poolcli refund create

Start the refund process by selecting the expired developer key.

poolcli refund create

poolcli refund list

Display all available refund invoices for a specific wallet.

poolcli refund list

poolcli refund get

Display all invoice details for a specific Refund ID.

poolcli refund get

Wallet Management (wallet)

Inspect your Bittensor wallets.

poolcli wallet list

Display all available coldkeys and their associated hotkeys with addresses.

poolcli wallet list

This command scans your wallet directory and displays public key information (no password required).

Global Options

poolcli --version      # Show version and exit
poolcli --commands     # Show all available commands and exit
poolcli --help         # Show help message and exit

Wallet Storage

Bittensor wallets are typically stored in ~/.bittensor/wallets/. The wallet list command reads from this directory.

Common Workflows

Complete Setup Workflow

# 1. View available wallets
poolcli wallet list

# 2. Authenticate
poolcli auth login --wallet-name my_wallet

# 3. Create a developer key
poolcli key create --wallet-name my_wallet

# 4. Check key status
poolcli key list --wallet-name my_wallet --status active

# 5. Create a pool
poolcli pool create --wallet-name my_wallet

# 6. View your pools
poolcli pool list --wallet-name my_wallet

Check Invoice Status

# Create invoice
poolcli key create --wallet-name my_wallet

# Check status later
poolcli key invoice get <invoice-id> --wallet-name my_wallet

Development

Installation for Development

git clone <repository-url>
cd poolcli
pip install -e ".[dev]"

License

GNU GENERAL PUBLIC LICENSE Version 2

Support

For issues, questions, or contributions, please create issue in github.

See Also

• Bittensor Documentation
• Bittensor GitHub
• BetterTherapy Subnet