tokenhubctl CLI

tokenhubctl is the command-line interface for managing TokenHub. It wraps every admin API endpoint into a convenient, scriptable tool.

Installation

make install    # Builds natively and installs to ~/.local/bin

Or build inside the Docker builder container:

make build      # Produces bin/tokenhub and bin/tokenhubctl

Configuration

export TOKENHUB_URL="http://tokenhub.internal:8080"
export TOKENHUB_ADMIN_TOKEN="$(tokenhubctl admin-token)"

Command Reference

General

tokenhubctl admin-token         # Print the admin token (env, file, or Docker)
tokenhubctl status              # Server info, health, vault state
tokenhubctl health              # Provider health table
tokenhubctl version             # CLI version
tokenhubctl help                # Full usage

Admin Token

The admin-token command retrieves the admin token by checking, in order:

1. TOKENHUB_ADMIN_TOKEN environment variable
2. ~/.tokenhub/.admin-token file (native deployments)
3. docker exec into the running container to read /data/.admin-token

This avoids the need to parse server logs. The token file is written automatically by the server at startup (whether auto-generated or set via env).

Rotating the Admin Token

tokenhubctl rotate-admin-token           # Generate a new random token
tokenhubctl rotate-admin-token <token>   # Replace with a specific token

After rotation, update your local environment:

make _write-env   # Sync token from container to ~/.tokenhub/env

The new token takes effect immediately (no restart required) and is persisted to the data directory so it survives restarts. The old token is invalidated instantly.

Vault

tokenhubctl vault unlock <password>
tokenhubctl vault lock
tokenhubctl vault rotate <old-password> <new-password>

Providers

tokenhubctl provider list
tokenhubctl provider add '<json>'
tokenhubctl provider edit <id> '<json>'
tokenhubctl provider delete <id>
tokenhubctl provider discover <id>

The list command merges providers from both the persistent store and the runtime engine, showing the source of each.

The discover command queries a provider's /v1/models endpoint to list available models and whether each is already registered in TokenHub.

Example:

# Add a new provider
tokenhubctl provider add '{
  "id": "openai",
  "type": "openai",
  "base_url": "https://api.openai.com",
  "api_key": "sk-..."
}'

# Update its base URL
tokenhubctl provider edit openai '{"base_url":"https://api.openai.com"}'

# Discover available models
tokenhubctl provider discover openai

Models

tokenhubctl model list
tokenhubctl model add '<json>'
tokenhubctl model edit <id> '<json>'
tokenhubctl model delete <id>
tokenhubctl model enable <id>
tokenhubctl model disable <id>

Model IDs can contain slashes (e.g., Qwen/Qwen2.5-Coder-32B-Instruct). The CLI handles them correctly.

Example:

# Add a model
tokenhubctl model add '{
  "id": "gpt-4o",
  "provider_id": "openai",
  "weight": 8,
  "max_context_tokens": 128000,
  "input_per_1k": 0.0025,
  "output_per_1k": 0.01,
  "enabled": true
}'

# Adjust its weight
tokenhubctl model edit gpt-4o '{"weight": 9}'

# Temporarily disable it
tokenhubctl model disable gpt-4o

Routing

tokenhubctl routing get
tokenhubctl routing set '<json>'

Example:

tokenhubctl routing set '{"default_mode":"cheap","default_max_budget_usd":0.02,"default_max_latency_ms":10000}'

API Keys

tokenhubctl apikey list
tokenhubctl apikey create '<json>'
tokenhubctl apikey rotate <id>
tokenhubctl apikey edit <id> '<json>'
tokenhubctl apikey delete <id>

The create command prints the API key exactly once. Save it immediately.

Example:

tokenhubctl apikey create '{"name":"prod-app","scopes":"[\"chat\",\"plan\"]","monthly_budget_usd":50.0}'

Observability

tokenhubctl logs [--limit N]       # Request logs
tokenhubctl audit [--limit N]      # Audit trail
tokenhubctl rewards [--limit N]    # Thompson Sampling reward data
tokenhubctl stats                  # Aggregated statistics
tokenhubctl engine models          # Runtime model registry and adapter info
tokenhubctl events                 # Live SSE event stream (Ctrl-C to stop)

Routing Simulation

Run a what-if simulation without sending a real request:

tokenhubctl simulate '{"mode":"cheap","token_count":500}'
tokenhubctl simulate '{"mode":"high_confidence","token_count":2000,"max_budget_usd":0.10}'

TSDB

tokenhubctl tsdb metrics
tokenhubctl tsdb query metric=latency&model_id=gpt-4o&step_ms=60000
tokenhubctl tsdb prune

Output Format

Most commands produce human-readable tabular output. For programmatic use, pipe JSON responses directly from curl or parse tokenhubctl output with standard text tools.