CLI reference

The tokenroute CLI is the primary surface for managing your tokenroute account from a terminal or an AI agent. It's a Python package on PyPI — run it with uvx tokenroute (or pipx install tokenroute). A Node thin wrapper (npx tokenroute) is planned for Phase B and not published yet.

Install

pipx install tokenroute     # global, pinned
uvx tokenroute              # one-shot, no install (recommended for agents)

Global flags & env

Credentials live at ~/.paradigx/auth.json (shared with other Paradigx CLIs, owner-readable only on POSIX). The most recently created raw API key is cached at ~/.paradigx/tokenroute_last_key.txt so env, test, and models can find it with no arguments.

Commands

tokenroute login

OAuth device-flow against Logto. Opens your browser; CLI polls until you authorize.

$ tokenroute login
Visit: https://auth.paradigx.com/device
And enter code: NHWB-FGSR
Waiting for authorization...
OK logged in

tokenroute logout

Forget locally stored credentials.

tokenroute whoami

Show current user + balance.

$ TOKENROUTE_JSON=1 tokenroute whoami
{
  "id": "f4a8...",
  "display_name": "Agent",
  "email": "agent@example.com",
  "logto_sub": "logto_xyz",
  "balance_usd": "0.00",
  "status": "active"
}

tokenroute keys create --name <name>

Create a new sk-tr-* API key. Raw value is shown once; cached to ~/.paradigx/tokenroute_last_key.txt (pass --no-cache to skip).

$ TOKENROUTE_JSON=1 tokenroute keys create --name fieryeye
{"id":"...","name":"fieryeye","key_prefix":"sk-tr-abcd","raw":"sk-tr-...","balance_usd":"0",...}

tokenroute keys list

Table or JSON list of your keys. Raw values are never returned.

tokenroute keys revoke <id>

Mark a key revoked. Future calls with it return 401.

tokenroute balance

Sum of credit across all active keys.

$ TOKENROUTE_JSON=1 tokenroute balance
{"balance_usd": "5.00", "currency": "USD"}

tokenroute topup --amount <usd>

Get a Stripe Checkout URL to add credit. Default behavior opens it in the browser. Agents must not auto-pay — hand the URL to the user.

$ TOKENROUTE_JSON=1 tokenroute topup --amount 5
{"checkout_url": "https://checkout.stripe.com/c/pay/...", "session_id": "cs_...", "amount_usd": "5", "expires_at": 1700000000}

tokenroute usage --days N

Summary of spend over the last N days (1-365). Only successful requests count.

$ TOKENROUTE_JSON=1 tokenroute usage --days 7
{"range_days": 7, "total_requests": 142, "total_tokens_in": 12450, "total_tokens_out": 3200, "total_cost_usd": "0.18"}

tokenroute env [--key sk-tr-...]

Output OPENAI_API_KEY=... + OPENAI_BASE_URL=... for shell redirection.

$ tokenroute env >> .env
$ tail -2 .env
OPENAI_API_KEY=sk-tr-cached123
OPENAI_BASE_URL=https://api.tokenroute.io/v1

tokenroute test [--model X]

Send a tiny chat completion to verify the gateway + your key work end-to-end. Default model is openai/gpt-4o-mini.

$ tokenroute test
OK connected (openai/gpt-4o-mini)
  reply: OK

tokenroute models

List available models with pricing.

$ TOKENROUTE_JSON=1 tokenroute models | jq '.[] | .id' | head
"openai/gpt-4o-mini"
"openai/gpt-4o"
"anthropic/claude-haiku-4-5"

Exit codes