TokenMix CLI

Zero-config CLI to use any open-source coding agent with TokenMix as the unified LLM backend.

One account, one balance, 160+ models routed automatically across Claude / GPT / Gemini / DeepSeek / Qwen / Moonshot / ...

Why TokenMix

Behind the zero-config CLI is a gateway built to be the honest, transparent LLM backend for BYOK coding agents:

• The model you pick is the model you get. Your request routes to the real upstream model you named, with no silent downgrade to a cheaper one (the grey market's classic "sold Opus, served Haiku"). Model aliases are name normalization only, never a swap.
• Transparent, real-time billing. tokenmix balance shows your actual balance, gift credit, and total spent to micro-USD precision, not opaque "credits". tokenmix models lists every model's real price (free models show $0, not a dash).
• Prompt caching that saves you money, automatically. Cache hits bill at the discounted rate with nothing to configure: OpenAI / DeepSeek / Gemini / Qwen via their cached_tokens, Anthropic via cache_control pass-through (cache reads about 10% of the input price). The savings are yours, and you can see them.
• One key, every protocol. OpenAI Chat Completions, Anthropic Messages, and the Responses API, all on one account, which is why every agent below (terminal and editor alike) runs on a single balance.
• Non-invasive by design. Configuring an agent never clobbers your setup: your Claude settings are backed up and restored, Codex's provider is injected at launch (your ~/.codex/config.toml stays untouched), and tokenmix logout reverts what it changed. Credentials are stored locally at 0600.

TokenMix vs. the grey market

The grey-market proxy scene is cheap but trust-broken: independent audits have documented model substitution, credential theft, and prompt-data resale. TokenMix is built to be the honest alternative, and every row below is enforced in code, not just promised:

Versus a mainstream gateway like OpenRouter, the difference is focus, not a knock on them: TokenMix is built for Asia/China BYOK users, with a six-language CLI and dashboard, networking tuned for slow or restricted connections, and one balance across the Anthropic, OpenAI, and Responses protocols.

Requirements

• Node.js 18 or newer. Check with node --version; if you don't have it, install it from nodejs.org.
• A TokenMix account. Sign up at tokenmix.ai. New accounts get $1 of free credit to start (see Free trial); after that you only pay for what you use.

Quick Start

New here? Two steps to your first agent:

# 1. Log in. This opens your browser - sign in to your TokenMix account,
#    then confirm the short code shown in the terminal.
npx tokenmix login

# 2. Launch your first agent. OpenCode is the easiest to start with: the CLI
#    installs it (first run only), points it at TokenMix, and launches it.
npx tokenmix opencode

After the first run, npx tokenmix opencode just starts it. The other agents work the same way:

npx tokenmix claude            # Claude Code (installs automatically)
npx tokenmix aider             # Aider (needs Python)
npx tokenmix codex             # Codex (installs automatically)
npx tokenmix qwen              # Qwen Code (installs automatically)
npx tokenmix goose             # Goose (install Goose itself first, see below)
npx tokenmix openhands         # OpenHands (install it first, see below)
npx tokenmix kilo              # prints config for the Kilo Code VSCode extension
npx tokenmix cline             # prints config for the Cline VSCode extension
npx tokenmix roo               # prints config for the Roo Code VSCode extension
npx tokenmix continue          # prints a Continue config snippet

Alternative login modes

npx tokenmix login --paste                     # interactive paste prompt (no browser)
npx tokenmix login --key sk-tm-...             # supply API key directly (for CI / scripts)

Free trial

New accounts get $1 of credit so you can try things before paying. It doesn't cover the premium models (Claude, GPT, Gemini, and the image/video/audio models), but it works on plenty of capable cheaper ones. To run an agent end to end at zero cost, point it at a trial-eligible model. qwen-flash is the cheapest and supports tool calling, so $1 goes a long way:

TOKENMIX_DEFAULT_MODEL=qwen-flash npx tokenmix opencode

If you want one tuned for coding, qwen3-coder-flash is also trial-eligible. Run tokenmix models for the full list, and switch to a premium model (and add credit) whenever you want more power.

Supported Agents

Commands

tokenmix login [--key sk-tm-xxx]   Log in
tokenmix logout                     Remove credentials (and revert injected agent config)
tokenmix balance                    Show your live balance (or open the dashboard)
tokenmix topup                      Open browser to top up
tokenmix models [--type chat]       List available models with prices
tokenmix list                       List supported agents
tokenmix doctor                     Diagnose configuration

tokenmix opencode [args...]         Launch OpenCode via TokenMix
tokenmix claude [args...]           Launch Claude Code via TokenMix
tokenmix aider [args...]            Launch Aider via TokenMix
tokenmix kilo                       Print Kilo Code configuration
tokenmix cline                      Print Cline configuration
tokenmix roo                        Print Roo Code configuration
tokenmix continue                   Print Continue config.yaml snippet
tokenmix codex [args...]            Launch Codex via TokenMix
tokenmix qwen [args...]             Launch Qwen Code via TokenMix
tokenmix goose [args...]            Launch Goose via TokenMix
tokenmix openhands [args...]        Launch OpenHands via TokenMix

Language

The CLI speaks English, 中文, 日本語, 한국어, Español, and Français (the same six languages as tokenmix.ai), auto-detected from your system locale (LANG / LC_ALL). Force it explicitly with TOKENMIX_LANG:

TOKENMIX_LANG=zh npx tokenmix doctor   # 中文
TOKENMIX_LANG=ja npx tokenmix doctor   # 日本語
TOKENMIX_LANG=fr npx tokenmix doctor   # Français

Default model

Agents default to claude-sonnet-4.6. Override it for any launch with the TOKENMIX_DEFAULT_MODEL environment variable, handy for a cheaper/faster default or for scripting:

TOKENMIX_DEFAULT_MODEL=claude-haiku-4.5 npx tokenmix opencode
TOKENMIX_DEFAULT_MODEL=qwen-flash       npx tokenmix aider

(tokenmix claude and tokenmix codex speak the Anthropic / Responses protocols, so they need a Claude-family model; the other agents accept any chat model.)

Slow or restricted networks

Requests auto-retry transient network failures (so a single hiccup won't fail a command) and time out after 20s. On a slow, proxied, or firewalled connection, raise the timeout with TOKENMIX_TIMEOUT_MS:

TOKENMIX_TIMEOUT_MS=60000 npx tokenmix login

If the default gateway host is unreachable from your network, point the CLI at a self-hosted or backup endpoint with TOKENMIX_API_BASE. It overrides the stored config at runtime only and is never written to disk, so it stays safe for one-off use, containers, and CI:

TOKENMIX_API_BASE=https://your-gateway.example.com npx tokenmix doctor

Behind a package-registry mirror (for example in mainland China), install through your mirror so the CLI and its agents download quickly:

npm config set registry https://registry.npmmirror.com
npm install -g tokenmix

Configuration Location

Your TokenMix credentials are stored locally at:

• macOS: ~/Library/Application Support/tokenmix/config.json
• Linux: ~/.config/tokenmix/config.json (respects XDG_CONFIG_HOME)
• Windows: %APPDATA%/tokenmix/config.json

File permissions are restricted to 0600 (owner read/write only).

FAQ

The browser didn't open when I ran tokenmix login. Expected on a server, in a container, or over SSH. The device flow prints the URL and a short code, so open the URL on any device and enter the code. To skip the browser entirely, use tokenmix login --paste to paste a key, or tokenmix login --key sk-tm-... in CI.

Something isn't working - where do I start? Run tokenmix doctor. It checks whether your key is valid and reports each agent's install and config status, which usually points straight at the problem.

How do I change the model an agent uses? Agents default to claude-sonnet-4.6. Set TOKENMIX_DEFAULT_MODEL to switch it (see Default model), and run tokenmix models to list everything available. claude and codex need a Claude-family model; the others take any chat model.

How do I log out or uninstall? tokenmix logout removes your stored key and reverts any agent config the CLI changed. Run via npx, the CLI leaves nothing behind; if you installed it globally, npm uninstall -g tokenmix.

Development

pnpm install
pnpm dev opencode

License

MIT. See LICENSE.