RouterPlex CLI

npx routerplex connects the coding agents on your machine to RouterPlex in one command. It logs you in through the browser, finds your agents, lets you pick models and keys, shows every change before writing it, and then checks that each agent really works.

npx routerplex

Requires Node.js 18.17 or newer. Works on macOS and Linux, and on Windows in PowerShell or Windows Terminal.

Install #

1. Check Node.js. Run node -v. If it prints v18.17.0 or higher, skip to step 2. Otherwise install the LTS version from nodejs.org, or with a package manager:

brew install node                  # macOS (Homebrew)
winget install OpenJS.NodeJS.LTS   # Windows

On Linux, use nvm or your distribution's Node.js 18+ package. Open a new terminal afterwards.

2. Run it. No install needed: npx downloads the CLI and runs it.

npx routerplex

Or install it once to run routerplex without npx:

npm install -g routerplex
routerplex setup

If npm install -g fails with EACCES (permission denied), don't use sudo: run it with npx instead, or install Node.js through nvm, which keeps global packages in your home folder.

Update. npx can reuse a cached copy, so ask for the newest one with npx routerplex@latest. For a global install, run npm install -g routerplex@latest. routerplex --version shows the version you have.

Supported agents #

CODEX_HOME, CLAUDE_CONFIG_DIR, XDG_CONFIG_HOME, HERMES_HOME and PI_CODING_AGENT_DIR are respected. Hermes runs on Windows only inside WSL; run the CLI there too.

What setup does #

1. Log in. The CLI shows a short code and opens routerplex.com/device. Approve it while signed in. The CLI receives a new API key named CLI - <your machine> and a CLI login that lasts 7 days. On a machine without a browser, open the link on any device. Already have a key? Run npx routerplex login --with-key and paste it.
2. Pick agents. Every supported agent is listed. The ones found on this machine are ticked; agents that aren't installed are shown but can't be selected. Use ↑/↓ to move, space to tick, enter to continue.
3. Pick models. For each agent, choose a model from the live RouterPlex list, with prices, context size and vision support. Type to filter. OpenCode isn't asked: it gets every model, and you switch inside it with /models.
4. Pick keys. One shared key for every agent, a key per agent, or a choice for each agent (see Keys).
5. Preview. A diff of every file the CLI will change, with keys masked. Nothing is written until you confirm.
6. Apply. Each file is backed up before its first change and written atomically. Only RouterPlex's own settings are touched: your other providers, comments and settings stay.
7. Check. One small request per agent's API format, a scan for settings that override RouterPlex, and optionally a real run of each agent (see Checks).

Run it again any time to change models or keys, or to add an agent. Your original backups are kept.

Commands #

For scripts and CI: npx routerplex setup --yes --agents codex --model gpt-5.6-terra.

Keys #

When you run setup, the CLI asks which key the agents should use:

• One shared key. Every agent uses CLI - <your machine>.
• A key per agent. The CLI creates a key for each agent, named like CLI - laptop - Codex CLI. The API Keys page then shows spend per agent, and you can revoke one agent's key without touching the others.
• Choose for each agent. For each agent: the shared key, its own existing key, a new key, or a key you paste.

The CLI can't list the keys already on your account: RouterPlex keeps only a fingerprint of each key after creating it, so their full text can't be fetched. To use one of them, choose Paste a key.

Per-agent keys follow the same rules as the API Keys page. Funded pay-as-you-go accounts can create as many as they need. An account still on its trial is limited to one key, and a plan has its own key limit. When a key can't be created, the CLI says why and that agent uses the shared key.

Where keys are stored

Codex, OpenCode and Pi read ROUTERPLEX_CLI_API_KEY, or ROUTERPLEX_CLI_API_KEY_<AGENT> (for example ROUTERPLEX_CLI_API_KEY_CODEX) when they have their own key. These names are only ever set by the CLI, so a ROUTERPLEX_API_KEY you exported yourself, as in the environment guide, never clashes with them.

After setup, open a new terminal, or run . ~/.config/routerplex/env.sh, so the current shell picks up the key.

Login #

The CLI login lasts 7 days. It is needed only to create keys. Your agents' keys don't expire with it, so Claude Code, Codex and the rest keep working.

• npx routerplex status shows when the login expires.
• When creating a key needs a fresh login, the CLI asks you to approve again in the browser.
• npx routerplex login renews the login without creating another key. It creates a new shared key only if the stored one was revoked, or when you pass --new-key. Agents on the shared key are then updated automatically.
• logout and uninstall also sign the CLI out on the server. The keys themselves keep working until you revoke them on the API Keys page.

Checks #

After applying, setup runs three checks.

Connection. One small request per agent's API format: Anthropic Messages for Claude Code, Responses for Codex, Chat Completions for the others. Each shows its x-routerplex-request-id.

Conflicting settings. A read-only scan for anything that silently overrides RouterPlex, reported with the file and line and how to fix it:

• an older key exported again in .bashrc, .zshrc or fish, or a different key loaded in the current terminal;
• OPENAI_API_KEY, OPENAI_API_BASE or AIDER_MODEL in your shell or in a project's .env, which Aider ranks above its config file;
• OPENCODE_CONFIG or OPENCODE_CONFIG_CONTENT;
• CODEX_HOME, CLAUDE_CONFIG_DIR or XDG_CONFIG_HOME pointing somewhere other than the files setup wrote;
• a project's .claude/settings.json, .codex/config.toml, opencode.json or .aider.conf.yml in the current folder or its repository root;
• organization-managed Claude Code settings that set the API URL or key.

Real agent test (optional; setup asks, or run npx routerplex test). Each agent starts in a new shell that loads your startup files, like a new terminal, and answers a one-line prompt containing a one-time code. It passes only if the reply contains that code and RouterPlex's usage for that agent's key shows the request, so an agent that answered through another login or provider is flagged. Failures say why: command not found from a new terminal, key rejected, out of credit, unknown model, or a timeout. Each run costs a few cents of credit.

Undo and uninstall #

npx routerplex undo <agent> (or --all) restores each file from its backup. If you edited the file after setup, it removes only RouterPlex's settings and keeps your edits.

npx routerplex uninstall puts the whole machine back:

• every file setup changed is restored, the same way as undo;
• RouterPlex settings the CLI never recorded, such as ones added by hand from these guides, are removed too;
• the RouterPlex lines are removed from your shell startup files (and the user variables on Windows);
• the CLI is signed out, and ~/.config/routerplex (keys, backups, undo history) is deleted.

It lists everything first and asks once (--dry-run only shows the list). Before changing anything it saves a private copy of each affected file in ~/.config/routerplex-uninstalled-<date>. A ROUTERPLEX_API_KEY you exported yourself is listed but never changed.

Troubleshooting #

No matching version found for routerplex@… right after a release: npm on your machine is using an outdated package list. Run npm cache clean --force and try again. If npm config get registry shows a mirror rather than https://registry.npmjs.org/, run npx --registry https://registry.npmjs.org routerplex@latest.

An agent ignores RouterPlex. Run npx routerplex doctor from the folder you work in: project-level configs and old exports are the usual cause. Then run npx routerplex test <agent>.

Codex, OpenCode or Pi says the key is missing. The terminal was opened before setup. Open a new one, or run . ~/.config/routerplex/env.sh.

"RouterPlex rejected the stored key". The shared key was revoked. Run npx routerplex login: it creates a new one and updates the agents that use it.

Out of credit (402). Top up on the billing page; requests resume at once.

Something looks wrong after setup. npx routerplex undo --all restores your files from the backups the CLI made before its first change.