tokenroute (Python CLI)

Agent-first CLI for tokenroute — the OpenAI-compatible LLM API gateway with smart routing and transparent token billing.

Install

pip install tokenroute
# or, run once without installing:
uvx tokenroute --help
pipx run tokenroute --help

Quickstart

tokenroute login                                 # OAuth device-flow, opens browser
tokenroute whoami                                # current user + balance
tokenroute keys create --name my-app             # create new sk-tr-* key
tokenroute balance                               # current credit

All commands accept --json (or env TOKENROUTE_JSON=1) for machine-parseable output that's friendly to agents and CI.

Agent / sub-agent usage (no interactive login)

For automation, skip tokenroute login and call the OpenAI-compatible API directly with a pre-issued key:

export TOKENROUTE_API_KEY=sk-tr-...
curl https://api.tokenroute.io/v1/chat/completions \
  -H "Authorization: Bearer $TOKENROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"openai/gpt-4o-mini","messages":[{"role":"user","content":"hi"}]}'

Configuration

Credentials from tokenroute login are stored at ~/.paradigx/auth.json (owner-readable only on POSIX) — shared with other Paradigx CLIs (e.g. botu) and auto-refreshed, so login is a one-time step per machine. Upgrading from 0.1.x migrates the old ~/.tokenroute/credentials.json automatically on first run.

License

MIT