CLI reference
The bitrouter binary — one local endpoint your runtime points at, a daemon you control, and a scriptable surface for routing, policy, and your Cloud account.
BitRouter ships as one static binary, bitrouter, with no dependencies to install. It plays two roles: it runs the local router your agent talks to (by default on http://127.0.0.1:4356), and it's the command-line surface for routing introspection, policy lifecycle, and your hosted account.
Running it bare is always safe: bitrouter probes for configured credentials without touching the network, then launches the onboarding wizard when nothing is configured, or prints a one-line status when it is.
Conventions
- Output is JSON by default (agent-native).
-j/--jsonforces JSON where it's optional;--humanrenders the human-readable view instead. -c/--config <PATH>overrides config discovery for any command that loads a config. Discovery order:./bitrouter.yaml→$BITROUTER_HOME/bitrouter.yaml→~/.bitrouter/bitrouter.yaml→ zero-config (in-memory defaults, auto-enabling providers from env keys).- Credentials live under
$XDG_DATA_HOME/bitrouter/account-credentials.json(mode0600), written bycloud loginorproviders login. - Every command page below is generated from the binary's own
--help, so the flags you see here are the flags your installed version accepts.
Environment variables
| Variable | Effect |
|---|---|
OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY, OPENROUTER_API_KEY, OPENCODE_ZEN_API_KEY | Zero-config BYOK — auto-enables the provider. See BYOK |
BITROUTER_API_KEY | Cloud API key; enables the managed bitrouter provider |
BITROUTER_HOME | Config discovery override (see above) |
BITROUTER_OAUTH_AS | Override the OAuth authorization server for self-hosted Cloud |
OTEL_EXPORTER_OTLP_ENDPOINT | Opt in to OTLP export. See OpenTelemetry |
Command map
- Run it — daemon lifecycle:
serve,start,stop,restart,reload,status - Onboard — init & config: the wizard, config validation
- Inspect routing — route, models & observe: decision preview, model catalog, OTel state
- Providers — providers: catalog and subscription login
- The loop — policy: init, check, evolve, lock/unlock, reload
- Cloud — cloud: login, keys, usage, billing, policies, BYOK
- Gateways — tools, agents & acp: MCP introspection, agent catalog, ACP sessions
- Skills & MCP — skills & mcp: install skills, run the origin MCP server
- Harnesses — launch, spawn & tui: run agents pointed at the daemon
- Misc — key, workflow-state & update: virtual keys, benchmark tooling, self-update
Not the only surfaces: an agent can also drive BitRouter over MCP — the origin server exposing complete, list_models, and status as tools — or via the shipped /bitrouter Agent Skill, which teaches a coding agent to install and operate BitRouter on its own.
How is this guide?
BitRouter vs LiteLLM
LiteLLM is a Python-native library that lives inside your app; BitRouter is a single Rust binary with zero dependencies and ~7× better tail latency under load. An honest side-by-side.
Daemon lifecycle
serve, start, stop, restart, reload, status — run and control the local BitRouter daemon your agent talks to.