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.

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 default 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 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 RouteKit OAuth and enroll the resulting subscription credential. Official Codex/Claude CLIs are not required.
`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.
`routekit cloud login [--url <cloud-origin>]`	Approve a device authorization for the selected Cloud organization. Defaults to `https://cloud.velum-labs.com`; use `--url` to select staging or another Cloud origin.
`routekit cloud install --agent <codex\|claude> [--default-model <id>] [--repository-connection-id <uuid>]`	Create a user API key and configure a native client for Cloud. The repository binding is opt-in and requires authenticated discovery of bare `auto`; `--default-model` is Codex-only and required if no compatible unbound default can be confirmed. Use `--codex-home` or `--claude-config-dir` to isolate native settings. To change a binding use `--replace --repository-connection-id <new-uuid>`; to remove it use `--replace --clear-repository-binding`. Plain `--replace` preserves it.
`routekit cloud status [--url <cloud-origin>]`	Inspect stored Cloud login, native configuration/key presence and drift, saved repository binding, live authenticated catalog and policy `auto` availability, pending key revocations, and retired local credential cleanups; no inference call.
`routekit cloud sync --agent <codex\|claude> [--default-model <id>]`	Refresh an installed Cloud model picker and helper without key rotation or changing the saved repository binding. Unbound Codex requires `--default-model`; bound Codex preserves `auto` without it. A different `--repository-connection-id` is rejected.
`routekit cloud logout [--url <cloud-origin>]`	Remove the login and registered agent integrations, attempting API-key revocation. Check any reported pending revocations.
`routekit cloud account login <claude-code\|codex> --name <label> [--reauthorize]`	Privately enroll a subscription Source, or resume an existing one. `--reauthorize` explicitly validates and replaces its provider credential.
`routekit cloud account list`	List safe Cloud subscription Source metadata without credential values.
`routekit cloud account show <claude-code\|codex> --name <label> [--refresh]`	Show one account. `--refresh` validates an owned credential and updates its health and model inventory.
`routekit cloud account pool <claude-code\|codex> --name <label>`	Add a validated private account to the organization subscription pool.
`routekit cloud account unpool <claude-code\|codex> --name <label>`	Remove an account from routing while retaining its private enrollment.
`routekit cloud account rename <claude-code\|codex> --name <label> --to <new-label>`	Rename management metadata without changing the stable `codex/` or `claude-code/` model namespace.
`routekit cloud account remove <claude-code\|codex> --name <label>`	Permanently remove an account after confirmation; JSON or non-input use requires global `--yes`.
`routekit cloud source connect --url <cloud-origin> --enrollment <id> [--budget <USD>]`	Complete a source connection started in Cloud using the official provider CLI. Supports Vercel AI Gateway, with team selection and confirmation before creating a dedicated key.

The Cloud coding-agent guide distinguishes the hosted gateway install, provider Source enrollment, and gated Cloud sidekick. cloud logout does not remove a separately installed sidekick MCP entry.

For Vercel, open Sources → Connect source → Vercel AI Gateway → Set up with Vercel CLI, name the source, and run the command shown in the app. Install the latest official Vercel CLI first. RouteKit reuses its login or opens the official login flow, asks which team should pay, and transfers only the dedicated Gateway key to Cloud. Use the same RouteKit user and organization in the app and CLI. The command rejects --json and --no-input; --yes does not bypass provider-key confirmation. --budget sets an optional non-renewing Vercel key budget in USD (minimum 1). Key budgets are upstream soft limits.

If the Cloud upload fails, rerun the same command: the key is saved in RouteKit's protected local secret store and reused. If key creation was interrupted before capture, check the named key in Vercel, revoke it if present, cancel the connection, and start another. Cancelled or expired attempts may also require revoking their key in Vercel. No inference request or credit purchase is made by setup. You can also select API key in the dialog to connect an existing Gateway key.

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.

Cloud sidekick (restricted)

Command	Purpose
`routekit sidekick install --tool <codex\|claude> --mode cloud --lead-model <id> [--cloud-url <origin>]`	Add a project-bound Cloud MCP sidekick to an existing native lead in an approved Fusion environment; does not configure its provider or open admission.
`routekit sidekick status`	Inspect only the native MCP installation marker, not Cloud authentication or delegation readiness.
`routekit sidekick session --tool <codex\|claude> --json`	Inspect the authenticated, project-bound session and saved operations without submitting work.
`routekit sidekick preview --tool <codex\|claude> --delegation-id <id> --json`	Inspect a returned patch without applying it.
`routekit sidekick evidence --tool <codex\|claude> --delegation-id <id> --generation <id> --attempt-id <id> --result-digest <digest\|none> --json`	Read exact attempt, settlement, and cleanup evidence without selecting a newer result.
`routekit sidekick review --tool <codex\|claude> --delegation-id <id> --generation <id> --result-digest <digest> --decision <apply\|discard\|take_over> --approve`	Human-approved, fenced review; apply/take_over can modify the checkout. Global `--yes` is not approval.
`routekit sidekick recover --tool <codex\|claude> --operation-id <id> --approve`	Explicitly retry the original saved admission or follow-up with its original budget; not a read-only probe.
`routekit sidekick uninstall --tool <codex\|claude>`	Remove only the managed native MCP entry, separately from `cloud logout`.

Cloud Fusion sidekick is not a generally available production path. It requires an approved staging custom environment, healthy feature-flag decision, deployment opt-in, and separate admission before work can be delegated.

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.

Each native-client install also installs the product-owned routekit skill for onboarding, configuration, recovery, and compositional eval routing. An unchanged RouteKit-managed copy is updated in place; a user-owned or edited skill is never overwritten. 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 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

Use top-level routekit status to inspect daemon and gateway state. 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. Listener-setting and host-protocol changes that cannot roll require a hard service reinstall or restart.

Update and configure the CLI

Command	Purpose
`routekit eval setup [--repository <path>]`	Initialize or resume one durable compositional-routing project.
`routekit eval status [--repository <path>]`	Show project state, approvals, plans, and runs.
`routekit eval answer --answer <text>`	Answer exactly one unresolved setup question.
`routekit eval propose dimensions`	Generate a reviewable workload-dimension basis on the configured RouteKit target.
`routekit eval propose evaluations`	Generate dimension, decomposition, and composition evaluations for review.
`routekit eval approve dimensions --digest <digest>`	Approve the exact reviewed routing-basis digest.
`routekit eval approve evaluations --digest <digest>`	Approve the exact reviewed evaluation digest.
`routekit eval validate`	Validate configuration, approvals, and artifacts without model calls.
`routekit eval estimate [--scope pilot	full]`
`routekit eval run --plan <id>`	Execute through the configured RouteKit target. Optional external `--gateway-url` and `--token-file` are qualification-only.
`routekit eval results [--run <id>]`	Show sanitized qualification evidence, accounting, and cleanup outcomes.
`routekit eval publish --run <id>`	Atomically activate an already-qualified configured-target run.
`routekit policy show`	Print the eval isolation policy (dedicated token, no auto-router).
`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