The Tokens CLI is a single JavaScript file that connects your coding agents to Tokens. One setup command signs you in through the browser, creates a key, lets you choose a default model and writes the config for OpenCode, Claude Code, Codex CLI and Crush. It needs Node.js 18 or newer and has no dependencies.
Install and run the Tokens CLI#
There's nothing to install globally. Download the file and run it with Node:
curl -fsSL https://tokens.bd/cli/tokens.mjs -o tokens.mjs && node tokens.mjs setup --base-url https://tokens.bdiwr https://tokens.bd/cli/tokens.mjs -OutFile tokens.mjs; node tokens.mjs setup --base-url https://tokens.bdIt's plain, readable JavaScript (about 650 lines). If you're cautious about running downloaded scripts, and you should be, open tokens.mjs and read it before the second half of that command runs.
Before you start, make sure your account has a plan or wallet balance. The CLI can't do anything useful on an empty account.
What setup does, step by step#
1. Signs you in through the browser#
Unless you pass --key, the CLI starts a device login. It prints a link and a code like ABCD-EFGH, and opens the link in your browser. On the page (/dashboard/connect/cli), check that the code matches the one in your terminal and approve it. The CLI waits and, once approved, receives a new API key named CLI (<your platform and Node version>). It's a normal key: you'll see it in /dashboard/keys and can revoke it there.
On a machine without a browser (SSH, a container), add --no-browser and open the printed link on any device where you're signed in.
2. Lists your models and asks for a default#
The CLI reads the gateway's base URLs from https://tokens.bd/api/gateway/config, then calls GET /v1/models with the key. It shows the first 10 models and asks you to pick one; Enter picks the first. To use a model that isn't in the first 10, pass it with --model.
3. Saves your credentials#
The base URL and key are saved to:
- macOS / Linux:
~/.config/tokens/credentials.json(or$XDG_CONFIG_HOME/tokens/credentials.json), readable only by you (mode 600) - Windows:
%APPDATA%\tokens\credentials.json
usage and models use this file later, so you don't need to pass the key again.
4. Finds your agents and shows what it will change#
It looks for OpenCode, Claude Code, Codex CLI and Crush, either by their config folder or by the program on your PATH. It prints the exact files it will update and asks Continue? [Y/n]. Nothing is written until you answer.
| Agent | File | What is written |
|---|---|---|
| OpenCode | ~/.config/opencode/opencode.json | A tokens provider (@ai-sdk/openai-compatible) with your key, and model set to tokens/<model> |
| Claude Code | ~/.claude/settings.json | env.ANTHROPIC_BASE_URL, env.ANTHROPIC_AUTH_TOKEN and env.ANTHROPIC_MODEL |
| Codex CLI | ~/.codex/config.toml (or $CODEX_HOME/config.toml) | A marked block with [model_providers.tokens] (env_key = "TOKENS_API_KEY", wire_api = "responses") and [profiles.tokens] |
| Crush | ~/.config/crush/crush.json | A tokens provider of type openai-compat with your key and model |
JSON files are merged: your other settings stay. The Codex block sits between # >>> tokens and # <<< tokens markers and is replaced in place if you run setup again.
5. Backs up every file first#
Before changing a file, the CLI copies it to <file>.tokens-backup-<timestamp>, for example settings.json.tokens-backup-2026-10-03T09-15-00-000Z. To undo, copy the backup over the file.
If a file can't be edited safely (JSON with comments, a syntax error, or a Codex config that already has its own [model_providers.tokens] table), the CLI leaves it alone, marks it skipped, and points you to the paste-in settings at /dashboard/connect?agent=<agent>.
6. Codex CLI: one manual step#
Codex reads the key from an environment variable, so its config file holds no secret. After setup, add the variable to your shell profile and start Codex with the profile:
export TOKENS_API_KEY="tok_live_your_key"
codex --profile tokenssetx TOKENS_API_KEY "tok_live_your_key"
# open a new terminal, then:
codex --profile tokensThe CLI prints this line with your real key filled in. See Codex CLI for more.
Note
OpenCode, Claude Code and Crush store the key in their config files in your home directory. Don't commit those files to a dotfiles repository.
Commands and flags#
node tokens.mjs setup [--base-url URL] [--key KEY] [--model ID] [--agents opencode,claude,codex,crush]
[--yes] [--dry-run] [--no-browser]
node tokens.mjs usage [--json]
node tokens.mjs models
node tokens.mjs logout
node tokens.mjs version
node tokens.mjs help| Flag | What it does |
|---|---|
--base-url URL | The Tokens site, https://tokens.bd. Needed the first time unless TOKENS_BASE_URL is set; saved afterwards. |
--key KEY | Use an existing key instead of the browser login. |
--model ID | Set the default model without the picker. Must be a model the key can use. |
--agents LIST | Configure only these agents (opencode, claude, codex, crush), even if they weren't detected. |
--yes | Skip the confirmation. Needed in scripts, where the prompt defaults to "no". |
--dry-run | Show which files would be written, without writing them or saving credentials. |
--no-browser | Print the sign-in link instead of opening it. |
usage prints your plan, each usage window with a progress bar and reset time, your wallet balance and the key's cap and allowed models. usage --json prints the raw response of GET /v1/tokens/usage (see usage, limits and alerts). models prints the model ids your key can use, one per line.
Dry runs still sign in
--dry-run doesn't write files, but without --key it still runs the browser login, which creates a key. To preview with no side effects at all, combine it with an existing key: node tokens.mjs setup --base-url https://tokens.bd --dry-run --key "$TOKENS_API_KEY".
Environment variables#
| Variable | Used for |
|---|---|
TOKENS_BASE_URL | Base URL when --base-url isn't given |
TOKENS_API_KEY | Key when --key isn't given; takes priority over the saved credentials |
The CLI picks the key in this order: --key, then TOKENS_API_KEY, then the saved credentials file.
Troubleshooting#
"Your account has no models available yet. Subscribe or add funds first." The key works but can't use any model. Subscribe to a plan or top up your wallet in /dashboard/billing, then run setup again.
"That API key was not accepted." The key was rotated, revoked or mistyped. Run setup without --key to get a fresh one, or check that an old TOKENS_API_KEY in your environment isn't overriding the saved key.
A file shows as skipped. It has comments or an unexpected format. Configure that agent by hand from /dashboard/connect or its guide: OpenCode, Claude Code, Codex CLI, Crush.
"No supported agents were found." Your key is saved anyway. Install the agent first, or force one with --agents claude. For Cursor, Cline, Zed, Aider and others, use /dashboard/connect.
"The code expired" or "Timed out waiting for approval." Approve the code within its time limit (up to 15 minutes). Run the command again for a new code.
"Could not reach https://tokens.bd." Check your network or proxy, and the status page.
Log out and uninstall#
node tokens.mjs logoutlogout deletes the saved credentials file on this computer and nothing else. The key stays valid. To disable it, revoke it in /dashboard/keys.
To remove Tokens from your agents, restore the .tokens-backup- copies or delete the settings the CLI added (the tokens provider in OpenCode and Crush, the three ANTHROPIC_* entries in Claude Code's env, the marked block in Codex's config.toml). Then delete tokens.mjs and, once you're happy, the backup files. The CLI leaves nothing else on disk.