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 (pip install tokenroute); a Node thin wrapper (npx tokenroute@latest) ships in Phase B.

Install

pipx install tokenroute     # global, pinned
uvx tokenroute              # one-shot, no install
npx tokenroute@latest       # via the npm thin wrapper (Phase B)

Global flags & env

Flag / env	Default	Purpose
`--json` / `TOKENROUTE_JSON=1`	off	Machine-parseable JSON output.
`TOKENROUTE_API_URL`	`https://api.tokenroute.io`	Override gateway base URL.
`TOKENROUTE_API_KEY`	(unset)	sk-tr-* key for LLM calls — skips `login`.

Credentials live at ~/.tokenroute/credentials.json (owner-readable only on POSIX). The most recently created raw API key is cached at ~/.tokenroute/last_key.txt so env, test, and models can find it with no arguments.

Commands

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 whoami --json
{
  "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 ~/.tokenroute/last_key.txt (pass --no-cache to skip).

$ tokenroute keys create --name fieryeye --json
{"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 balance --json
{"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 topup --amount 5 --json
{"checkout_url": "https://checkout.stripe.com/c/pay/...", "session_id": "cs_...", "amount_usd": "5", "expires_at": 1700000000}

`tokenroute usage --days N`

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

$ tokenroute usage --days 7 --json
{"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 models --json | jq '.[] | .id' | head
"openai/gpt-4o-mini"
"openai/gpt-4o"
"anthropic/claude-haiku-4-5"

Exit codes

Code	Meaning
0	Success
1	User error (4xx from API: insufficient balance, invalid input, no key)
2	Network error
3	Server error (5xx, device-flow failure)

CLI reference

On this page