CLI reference
The command line does four things: it serves the router, it validates a config without serving, it replays a request against fixtures without touching the network, and it summarizes a window of routing reports. Six flags, three subcommands, two exit codes. Everything below was read off the shipped entry point and confirmed by running it.
How to invoke it
There are exactly two working invocations. The built entry point is the one to use for anything long-running; running from source skips the build and is for a contributor loop. Both are covered end to end in Install.
$ node dist/switchback-cli.js [subcommand] [flags]
$ pnpm tsx src/switchback-cli.ts [subcommand] [flags]
The module only runs itself when the basename of the invoked script is
switchback, switchback-cli.js, or
switchback-cli.ts. That guard is the reason the two forms above work and the
reason a third form that looks identical does not.
Warning
The build also emits a CommonJS twin, dist/switchback-cli.cjs. Its basename
is not in the self-run guard, so running it prints nothing and exits 0:
no error, no listener, no config validation. Verified. Always run
dist/switchback-cli.js. A supervisor pointed at the .cjs file
will look like a clean start and route no traffic.
Note
The package's bin map registers the name switchback, which is
why the guard accepts that basename. No global-install or link path has been tested, so
this page does not present one: every example invokes the built entry point directly.
The help output
--help prints the block below verbatim and exits 0. It used
to open with two usage lines that fetched this project from a package registry under a
scoped name that does not exist. The repository is private and the package has never been
published, so those lines could only fail to resolve. They now name the built entry point,
and the help itself says why there is no registry form. Nothing is elided here.
switchback — self-hosted LLM router (experimental)
Usage:
node dist/switchback-cli.js --config switchback.config.json
node dist/switchback-cli.js config check --config switchback.config.json
Not on a registry: switchback is private and unpublished, so there is no
npx or npm-install form. Run `pnpm build` first, or drive the source
directly with `pnpm tsx src/switchback-cli.ts`.
Options:
-c, --config <path> Route config JSON (default: switchback.config.json)
-h, --host <string> Bind host override (default: config, else 127.0.0.1)
-p, --port <number> Bind port override (default: from config)
--record Shadow-record live legs into replayable fixtures
--redact-env Scrub provider key vars from env after load (§17.3)
--help Show this help message
Subcommands:
config check Validate the config (incl. referenced env vars) and
exit; prints missing variable NAMES only, never
their values.
sim Replay ONE request through the config's route section
against its fixture pack and print the routing report.
No network, no upstream contacted. Flags: --request
<path> (else stdin), --surface, --report-id. Exits 1
if nothing was simulated, and prints why.
report <path>... Summarize a window of routing reports (files, globs,
or a GET /route/reports dump): what routed where,
failover rates by reason, spend by upstream, and
honest savings vs an all-OpenRouter baseline.
--json for machine output.
Flags
These six are the complete set. They apply to serve mode; config check reads
--config, and report has its own small flag set documented with
the subcommand.
Path to the route config JSON. It is resolved to an absolute path before anything else happens, so every message that names your config names the absolute path, not what you typed. The field-by-field schema is in Configuration.
Overwrites listen.host for this process. Setting a non-loopback host
here is equivalent to setting it in the config file. The router's exposure warning
fires on any non-loopback bind regardless of which of the two set it. See
Deploy for the bind posture.
-h is the short form of --host, not of
--help
in serve mode. Inside the report subcommand, -h does mean
help. That inconsistency is real; budget one surprise for it.
Overwrites listen.port. The value must parse as an integer in
0–65535; anything else exits 1 with
invalid port "<value>".
--port 0 is legal and binds an operating-system-assigned port. The port
actually bound is printed in the listening line, so read it there rather than
guessing.
Force-enables route.record.enabled, shadow-recording routed legs into
replayable fixtures under the configured record directory. Recording is
fire-and-forget: a persistence failure never affects a response that has already
been sent. More in Observability.
After the keys are materialized into the isolated auth store, the environment variables they came from are deleted from the process environment, so child processes and diagnostics cannot read them. Dispatch is unaffected, because the router reads from the bound store, never from the environment. Only variable names are logged.
The trade is stated in full on Security: with nothing left to re-read, SIGHUP key rotation becomes impossible and rotation requires a restart.
Prints the help block and exits 0 without loading the config.
Parsing is strict
Positionals are rejected in serve mode, and so is any flag not in the table above. An
unknown flag prints Error: <message> followed by the full help block
and exits 1. There is no pass-through and no tolerated typo.
--host, --port and --record are re-applied after
every SIGHUP reload, so the served config never drifts away from the flags in force. That
re-application cannot rebind a live socket (see Deploy and the
signal table below).
Subcommands
There are exactly three: config check, sim and
report. Anything else is serve mode.
Note
There is no --version flag, and no version string in the
startup log.
config check
Validates the config and that every environment variable it references is set, then exits without serving anything and without opening a socket. This is the command to put in a pre-deploy gate.
$ node dist/switchback-cli.js config check --config switchback.config.json
On success it prints one line and exits 0:
Config check passed: /srv/switchback/switchback.config.json is valid and all referenced env vars are set.
On a missing credential variable the config loader hard-fails first, and the message names the upstream and the variable, never the value:
Invalid route config in /srv/switchback/switchback.config.json: upstream "stub": auth.env references
environment variable "STUB_API_KEY" which is unset or empty — …
A config with no route section is refused with
Config in <path> has no "route" section — nothing to serve. Every
failure here exits 1. Variable names are the only credential-
adjacent thing this command ever prints; values never appear.
Warning
config check reports the first unset variable, not all of
them. The loader fails hard as soon as it hits one, so the aggregate "N referenced env
var(s) are unset" summary in the code is unreachable today, confirmed by running it.
Expect to iterate one variable at a time, and do not read a single- variable error as
"only one is missing".
sim
Replays one request through the route section against the fixture pack the
config's top-level fixtures globs name, and prints the routing report as
JSON. No upstream is contacted and no key is sent anywhere, but the config loader still
requires every auth.env variable it names to be set, so export a placeholder
(any non-empty value) if you have no real key. This is the same route section
production runs, evaluated by the same engine, so the report is directly comparable to one
from a live request.
$ node dist/switchback-cli.js sim --config switchback.config.json --request ./req.json
$ echo '{"model":"gpt-4o","messages":[{"role":"user","content":"hi"}]}' | \
node dist/switchback-cli.js sim --config switchback.config.json
What it is for: asserting failover behaviour in CI. Give the fixture pack a 429 for your primary and a success for your fallback, then assert on the report—same legs, same verdict reasons, same winner. A policy regression fails the build instead of being discovered during an incident.
A JSON file holding one canonical chat request. Omit it and the request is read from standard input, which is what makes the command pipeable.
The client path used for route matching. Set it to
/api/v1/chat/completions to simulate a request arriving on the
OpenRouter surface. No route matching the surface is an exit-1 refusal, never a
guessed upstream.
Pins the report's id. Reports otherwise carry a random id, which makes
a byte-for-byte diff between two runs impossible; pin it and the whole document is
comparable.
Warning
Budget caps are not enforced in sim. The live path reserves budget
inside the resolver before dispatching a leg; the sim resolver has no reserve step, only
settlement. Per-leg cost still appears in the report, but a crossed cap does not become
a 402 the way it would in production. Do not use sim to prove a spend guard
trips — that needs a reserve step in the simulation, which is not built.
Note
Relative fixtures globs resolve against the
config file's directory, not your shell's working directory, so a committed
config simulates the same way from anywhere in a repo. A glob that matches no files is a
hard failure rather than an empty run: simulating against no fixtures would route
nothing and look like a pass. For the same reason, a run that would print an empty
legs array prints the reason and exits 1. The reason is
one of these: the config has no fixtures key; no candidate reaches an
upstream (no models mapping, or provider preferences exclude
every upstream); or no fixture matches any candidate.
report
Summarizes a window of routing reports: what routed where, failover rates by reason, spend
by upstream, and an estimated saving against an all-OpenRouter baseline. It takes the
reports from files, from shell-style globs, or from a saved
GET /route/reports dump.
$ curl -s http://127.0.0.1:4011/route/reports > reports.json
$ node dist/switchback-cli.js report reports.json
$ node dist/switchback-cli.js report './reports/*.json' --json
The subcommand is intercepted before the strict flag parser runs, which is how it accepts positional paths at all.
One or more patterns. A pattern containing any of *, ?,
[, ], { or } is expanded as a
glob; anything else is treated as a literal path. Quote your globs so the shell
hands them over unexpanded. Duplicate paths after expansion are de-duplicated, so
overlapping patterns do not double-count a report.
Accepted payload shapes, in the order they are tried: a
/route/reports dump object, a bare JSON array of reports, a single
report object, or newline-delimited JSON.
Emits the structured summary instead of the human text block. Top-level keys are
windowReportCount, routing, failover,
spend and savings; the full field list is in
Observability.
Prints the help block and exits 0. Inside this subcommand
-h means help; in serve mode it means --host.
The text output, from a real five-report window:
switchback report — window of 5 reports
Routed where (upstream: wins / legs):
stub: 3 win(s) / 4 leg(s)
Failover (4 legs total): 3 success, 1 retryable, 0 fatal
0 of 5 requests failed over (0.0%)
by reason:
silent_empty: 1
Spend by upstream (total 0.000069):
stub: 0.000069
Estimated savings vs all-OpenRouter baseline:
baseline (all-OpenRouter): 0.000069
actual spend: 0.000069
winner-actual: 0.000069
failover waste: 0.000000
price savings: 0.000000
net savings: 0.000000
(3 priced, 0 unpriceable)
A closing line states the method used for the baseline. Two honest notes on that number.
First, the baseline prices each served request's actual winning token usage at the
catalog's OpenRouter list price for the winning model, while actual spend sums every leg,
so
net savings goes negative when failover waste outweighs the price advantage. Second, the baseline deliberately does not apply your
budget.priceMap overlay, so negotiated or self-hosted rates show up as
savings rather than silently discounting the thing you are comparing against. Requests
with no winner, no usage, or no catalog price are excluded and counted
unpriceable; no dollar is invented.
report errors
Each of these exits 1:
- an unknown flag;
-
no patterns at all, which prints
Error: report needs at least one report file, glob, or dump path.; -
a glob that matches nothing:
No report files matched "<pattern>".; - a file that cannot be read;
- a payload that does not parse as one of the four accepted shapes;
- a failure loading the signed catalog needed for the savings baseline.
A successful summary exits 0.
Serve mode
With no subcommand, the process loads the config and serves. The startup order matters because it determines which failures happen before anything is listening. All of them do, by design.
-
Read and parse the config file. A read or parse failure prints
Failed to load config from <path>: <message>and exits 1. -
Load and validate the route config, including every referenced environment variable. A
schema violation prints
Invalid route config in <path>: <message>and exits 1. -
Apply the
--host,--portand--recordoverrides. -
If catalog refresh is configured with a URL, check the scheme and host
before any timer arms. A rejected URL prints
Invalid catalog.refresh URL in <path>: <message>and exits 1. - Print the experimental notice and the one-line auth-mode summary.
-
Assemble the runtime and start the frontend. A bind failure prints
Failed to start switchback frontend: <message>and exits 1. -
Print the listening line, plus one more line with
--recordsaying so.
[switchback] EXPERIMENTAL: the self-hosted router is under active development; config shape and behavior may change without notice.
[switchback] auth: default mode — keys held in memory; SIGHUP re-reads keys from env
[switchback] router listening on http://127.0.0.1:4011
Under --redact-env the second line changes and a scrub count is added; both
forms are quoted on Security. With --record the
router adds
[switchback] --record set: config.record.enabled — shadow recording wired by the
resolver.
Signals
Handlers for all three are installed by default.
| Signal | Behavior | Exit |
|---|---|---|
| SIGINT |
Graceful shutdown: deregister handlers, stop the catalog refresher, log
[switchback] shutting down…, close the server.
|
0 |
| SIGTERM | Identical to SIGINT. This is the one your supervisor will send. | 0 |
| SIGHUP |
Re-read the config file and hot-swap the reloadable derived state, then log
[switchback] SIGHUP: re-read config and reloaded derived runtime state.
|
— |
A close error during shutdown exits 1 instead of 0. A SIGHUP reload that
throws is swallowed: the router logs
[switchback] SIGHUP reload failed; retaining last-good config — <message>
and the process survives on the config it was already serving. A reloaded file missing the
route key is treated the same way.
What SIGHUP actually reloads
Half of the config is reloadable and half is not, and the half that is not says so loudly in the log rather than pretending. Plan a restart for anything in the "No" rows.
| Section | Reloaded | Detail |
|---|---|---|
| Budget caps (global, per-upstream, per-route) | Yes | Rebuilt in place; accrued spend is preserved. |
| Budget cap metric gauges | Yes | Re-set to the new caps. |
| budget.priceMap | Yes | The price source is re-pointed, and the shared holder is reassigned so the next catalog refresh overlays the reloaded map. |
| Auth registry (default mode) | Yes |
Keys are re-read from the environment. Not available under
--redact-env.
|
| Budget backend (kind, store path or URL, store-error posture) | No | Refused loudly: restart to change the backend or its store-error posture. |
| Catalog (refresh, URL, interval) | No | Refused loudly: the armed refresher keeps its startup URL. |
| Observer hooks and the shadow recorder | No | Refused loudly; requires a restart. |
| listen.host / listen.port | No | The socket cannot be rebound on a live reload; the original bind is retained and the served values are restored so the runtime cannot misreport them. |
Danger
Under --redact-env, SIGHUP re-reads only non-secret config and carries key
material forward only for auth references that did not change. A
re-pointed variable name, a changed key-file path, or a changed auth kind each warn
loudly and leave that upstream keyless until you restart. The old key
is deliberately not kept live under a config that names a different one. If you rotate
keys by editing config and sending SIGHUP, do not run with --redact-env.
Environment variables
The command line reads very little from the environment. Credentials are the exception, and they are named by your config rather than by a fixed variable.
| Variable | Type | Default | Effect |
|---|---|---|---|
Any name your config's auth.env references |
string (credential) | none, required once referenced |
Supplies that upstream's credential, read at load and again on SIGHUP in default
mode. Unset or empty is a hard startup failure, and the message names only the
variable. config check reads the same set.
|
| AIMOCK_ALLOW_PRIVATE_URLS | 1 to enable |
unset | Permits private and reserved hosts to pass the host check applied to the catalog refresh URL. Note that the network refresh path cannot arm in this build at all (see Security), so this only affects the startup URL check. |
| SWITCHBACK_TEST_REDIS_URL | string (URL) | unset | A test-only gate used by the unit-test workflow to activate real-Redis test legs. Not a runtime setting. The router does not read it to configure a budget backend. Use the config file for that. |
There is
no environment variable for the config path, the bind port, or a log level. The config path comes from --config and nothing else; the port from the
config or --port; log verbosity is not configurable. The AWS credential and
region environment chain used by the SigV4 signing option is deliberately not documented
here. It has not been verified end to end, so treat it as untested rather than as a
supported surface.
Exit codes
Two, which makes scripting simple: zero means it did the thing, one means it did not.
| Code | When |
|---|---|
| 0 |
--help; config check passed; report
succeeded; graceful shutdown on SIGINT or SIGTERM.
|
| 1 |
Unknown flag or invalid port; config read or parse failure; schema violation;
missing route section; config check failure; rejected
catalog refresh URL; frontend start failure; any report error; a
close error during shutdown.
|
Known rough edges
All of these are confirmed against the shipped entry point, and all of them are the kind of thing you would otherwise discover at an inconvenient hour.
| Edge | Status | What to do |
|---|---|---|
| The CommonJS entry silently no-ops | not supported |
Run dist/switchback-cli.js. Never
dist/switchback-cli.cjs.
|
| Help text names an unpublished registry package | stale output | Ignore those two lines; see Install. |
-h is host in serve mode, help inside report |
by construction | Use --help when you mean help. |
| Aggregate "N variables unset" summary is unreachable | known defect | Fix variables one at a time; do not infer a total from one error. |
No --version flag, no version in the startup log |
not supported | Pin and record the commit you built from. |
| Global-install path | untested | Invoke the built entry point directly. |
Where to go next
The config every one of these commands reads is documented key by key in
Configuration. The reports that report consumes,
and the endpoint that serves them, are in Observability.
Credential handling behind --redact-env and config check is in
Security, and the process posture these signals imply is in
Deploy.