CLI command reference

This page covers the current public RouteKit command surface. Run routekit <command> --help for the exact options installed on your machine. Commands that inspect or mutate product state target the selected local or remote daemon unless marked local-only.

Global options

Option	Behavior
`--json`	Emit machine-readable stdout where supported and imply non-interactive behavior.
`--no-input`	Never prompt; interactive-only commands reject it.
`--yes`	Accept confirmations.
`--quiet`	Suppress informational output, but keep warnings and errors.
`--remote <name>`	Target an enrolled remote gateway.
`--local`	Force the local daemon when a remote is active.
`--config <path>`	Recovery input for `doctor` and `config migrate`; it is not a daemon scope selector.

Global options may appear before or after a command, but arguments after -- belong to a launched native client.

Configure providers and accounts

Command	Purpose
`routekit setup [--no-browser]`	Interactively select, verify, and configure one or more first-launch routes; local-only.
`routekit config init [--force]`	Create the backward-compatible OpenAI starter at `~/.config/routekit/router.yaml`; local-only.
`routekit config init --provider <provider> [--default-model <provider/model>]`	Create one deterministic API-provider starter; local-only.
`routekit config init --empty`	Start with no provider before the first subscription enrollment; local-only.
`routekit config path`	Print the canonical router path.
`routekit config show`	Print the validated canonical router document.
`routekit config edit`	Open the document with `$EDITOR` or `$VISUAL`, validate it, and reload atomically.
`routekit config import --from <path>`	Replace the complete canonical document with validated YAML.
`routekit config migrate [--dry-run]`	Diagnose or convert legacy endpoint/account configuration; local-only.
`routekit providers add <provider>`	Enable a first-launch provider.
`routekit providers remove <provider>`	Disable a provider; the only configured provider cannot be removed.
`routekit providers status [provider]`	Run live credential and model discovery.
`routekit accounts login <claude-code\|codex> --name <label> [--no-browser]`	Run an isolated official-CLI login and enroll the resulting subscription credential.
`routekit accounts add <claude-code\|codex> --name <label>`	Import the current official CLI login.
`routekit accounts rename <kind> <source> <target>`	Rename an enrolled subscription account without repeating OAuth.
`routekit accounts remove <kind> <name>`	Remove one enrolled account.
`routekit accounts list`	List enrolled account identities without reading credential values.
`routekit accounts status`	Show credential, pool, relay, serving, selection, and upstream authentication state.

providers add accepts --strategy, --switch-threshold, --probe-interval, --fallback-cooldown, and --default-model. Supported first-launch provider IDs are openai, anthropic, openrouter, bedrock, codex, and claude-code.

setup can combine explicitly selected API and subscription routes, preflights API providers before writing a fresh configuration, enrolls subscriptions, and offers a live default-model picker. It is interactive and rejects --json and --no-input. API keys must already be in the environment; RouteKit never asks for or stores them.

For config init --provider, the deterministic provider choices are openai, anthropic, openrouter, and bedrock. --default-model requires --provider and must use the same provider namespace. Bedrock requires an explicit approved bedrock/<model-or-inference-profile> default.

Start and stop

routekit start
routekit status
routekit stop

routekit start accepts --host, --port, --auth-token, --no-portless, and --drain-grace. It is local-only. The default bind is 127.0.0.1:8080; a non-loopback bind requires authentication.

routekit stop [--force] drains and stops the local daemon. Use --force only when a detached daemon's control plane cannot drain normally.

Launch supported coding tools

routekit codex [provider/model] [--effort <id>] -- [native arguments]
routekit claude [provider/model] [--effort <id>] -- [native arguments]

[provider/model] is optional. Without it, RouteKit chooses a suitable configured or compatible startup model and makes the compatible RouteKit catalog available through the native client's model picker. You can switch models inside the client. Supplying an exact namespaced ID pins the startup model, which is useful for automation, reproducible runs, and one-off comparisons.

Both commands launch the installed native client in the current directory and accept --gateway-url, --auth-token or --auth-token-env, --effort, and --cwd. Use --cwd to launch in another directory. Authenticated non-loopback gateway URLs must use HTTPS. Codex uses Responses-compatible routes only. See Models and catalog behavior for implicit Codex selection and reasoning-effort behavior.

The exact qualified builds are Codex CLI 0.146.0 and Claude Code 2.1.216 or 2.1.220. Other versions are unqualified but are not rejected at runtime. Cursor Desktop, cursor-agent, and OpenCode are not offered public client surfaces. See supported coding tool versions.

Native clients own transcripts, history, resume, and deletion. Forward native arguments after --, for example:

routekit codex -- resume <native-id>
routekit claude -- --resume <native-id>

Install persistent native-client configuration

routekit codex install
routekit claude install
routekit codex uninstall
routekit claude uninstall

Installs are additive: Codex receives one routekit profile without changing its default model; start it with codex --profile routekit, then use the RouteKit- backed model picker. Claude receives native availableModels entries derived from the RouteKit catalog, so its normal /model picker lists RouteKit models without synthetic aliases. Each install issues a dedicated gateway token and stores it in macOS Keychain (or a private 0600 RouteKit secret file elsewhere). Codex and Claude retrieve the token on demand through their native credential helper settings, so terminal, IDE, and GUI launches need no shell changes. Reinstalling the same target preserves the token; use --rotate-token to replace it. Use --shell only as a compatibility fallback for an older client. Claude's --bare mode intentionally ignores normal user settings, including apiKeyHelper; use a normal launch or pass its settings file explicitly. uninstall removes the RouteKit-owned configuration and revokes its tracked dedicated token.

--no-token writes only the RouteKit-owned client configuration for an external environment that supplies ROUTEKIT_GATEWAY_TOKEN for Codex or ANTHROPIC_AUTH_TOKEN for Claude; it cannot be combined with --rotate-token. Use routekit token shell --tool <codex|claude> only when a shell needs explicit credential exports for a configured integration.

Optional location flags are --codex-home <dir> and --claude-config-dir <dir>.

Inspect models, usage, and health

Command	Purpose
`routekit status [--watch [seconds]]`	Show daemon, service, provider, account, and cached-model status.
`routekit usage [--watch [seconds]]`	Show subscription limits, credits, and reset windows.
`routekit usage redeem --provider codex [--label <name>] [--credit-id <id>]`	Redeem one banked Codex reset; non-input use requires global `--yes`.
`routekit models list [--provider <name>]`	Discover live namespaced model IDs.
`routekit models info <provider/model>`	Show provider, native ID, account class, billing mode, capabilities, and reasoning metadata.
`routekit calls inspect <call-id>`	Show routing, billing, retries, usage, cost, principal, and account attribution.
`routekit leaderboard [options]`	Rank retained calls by principal, model, or provider.
`routekit doctor`	Check configuration, credentials, providers, daemon health, and coding-tool binaries.

Common usage and reset commands:

routekit usage
routekit usage --watch 10
routekit usage redeem --provider codex
routekit usage redeem --provider codex --label work --credit-id RateLimitResetCredit_… --yes

usage redeem interactively selects an eligible account and reset credit when they are omitted. With --yes and no explicit ID, RouteKit chooses the soonest-expiring detailed credit, or lets the provider choose when only an aggregate count is available. RouteKit never auto-redeems a reset.

Remote and shared gateways

Command	Purpose
`routekit remote install <ssh-host> [options]`	Probe, install, configure, and start RouteKit on a macOS or Linux SSH host.
`routekit remote add <name> --url <https-url> --ssh <host>`	Enroll an existing remote and obtain a named data token over SSH.
`routekit remote list`	List enrolled remotes.
`routekit remote show [name]`	Show and probe one remote.
`routekit remote use [name]`	Select a remote; `--none` returns to local mode.
`routekit remote remove <name>`	Remove local remote metadata and its stored token.
`routekit token issue <label> [--plane data\|control]`	Issue plaintext once; a control token produces a peer join command.
`routekit token list [--plane data\|control]`	List token hashes and revocation state, never plaintext.
`routekit token revoke <id>`	Revoke a named token; the owner token cannot be revoked.
`routekit peer add <join-credential>`	Join this OS account to another user's local shared daemon; pass `-` to read from stdin.
`routekit peer show`	Show the peer pointer and current public daemon record.
`routekit peer remove`	Remove the peer pointer from this account.

remote install accepts --name, --url, --version, --force, --dry-run, and --no-use. Without --url, it leaves the daemon loopback-bound and prints the next enrollment command. See Set up a remote gateway for the trust and network model. When --version latest is used, RouteKit resolves the npm dist-tag to an exact version before contacting the host. An already-current host skips installation; --force reinstalls the resolved version. JSON output preserves the requested version and reports the exact release as targetVersion.

Advanced local daemon operations

These operations are available under the intentionally hidden daemon group:

routekit daemon status
routekit daemon reload
routekit daemon restart
routekit daemon upgrade
routekit daemon logs --lines 100 --follow
routekit daemon auth show
routekit daemon service install
routekit daemon service status
routekit daemon service uninstall

daemon auth show intentionally prints the private owner token. Do not paste it into logs, shell history, source control, or issue reports. daemon run and daemon exec are internal plumbing rather than operator commands.

daemon restart rolls the active worker using the current entrypoint. daemon upgrade rolls to the invoking CLI entrypoint after an exact version probe. On host protocol v1 the host PID, data URL, public port, and control port remain stable; JSON reports the previous/new worker PIDs and generation. Legacy combined daemons use one graceful hard restart to migrate to the host/worker layout. Listener-setting and host-protocol-incompatible changes require a hard service reinstall or restart.

Update and configure the CLI

Command	Purpose
`routekit self-update [--version <version>] [--dry-run]`	Update the CLI through its owning package manager.
`routekit telemetry status\|on\|off`	Inspect or change anonymous telemetry consent.
`routekit telemetry category <usage\|reliability\|adoption> <on\|off>`	Change one telemetry category.
`routekit telemetry schema`	Print the exact event and field inventory.
`routekit telemetry reset`	Rotate the anonymous install identity.
`routekit completion <bash\|zsh\|fish>`	Print a dynamic shell completion script.
`routekit version` or `routekit --version`	Print the installed package version.

After updating the CLI, roll an already-running local daemon to the installed version with routekit daemon upgrade.

self-update updates the RouteKit executable that is both currently running and first on the original PATH. Lower-priority npm or pnpm installations can coexist and are left unchanged. If a different or uninspectable RouteKit executable is first, the update fails instead of reporting false success. latest is resolved to an exact npm release before comparison, so an already-current CLI reports action: "skipped"; JSON preserves the requested version and includes the exact targetVersion.

CLI command reference

On this page