switchback — part of the aimock family private · pre-launch

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.

after a build shell
$ node dist/switchback-cli.js [subcommand] [flags]
no build step shell
$ 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.

node dist/switchback-cli.js --help output
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.

-c, --config <path> string optional default: switchback.config.json

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.

-h, --host <string> string optional default: from config, else 127.0.0.1

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.

-p, --port <number> integer optional default: from config

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.

--record boolean optional default: false

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.

--redact-env boolean optional default: false

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.

--help boolean optional default: false

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.

validate and exit shell
$ node dist/switchback-cli.js config check --config switchback.config.json

On success it prints one line and exits 0:

success output
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:

unset variable output
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.

replay a failover offline bash
$ 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.

--request path optional default: read stdin

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.

--surface string optional default: /v1/chat/completions

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.

--report-id string optional default: a random sim- id

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.

summarize a window shell
$ 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.

<path>… file, glob, or dump required

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.

--json boolean optional default: text

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.

--help, -h boolean optional default: false

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:

node dist/switchback-cli.js report reports.json output
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:

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.

  1. Read and parse the config file. A read or parse failure prints Failed to load config from <path>: <message> and exits 1.
  2. Load and validate the route config, including every referenced environment variable. A schema violation prints Invalid route config in <path>: <message> and exits 1.
  3. Apply the --host, --port and --record overrides.
  4. 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.
  5. Print the experimental notice and the one-line auth-mode summary.
  6. Assemble the runtime and start the frontend. A bind failure prints Failed to start switchback frontend: <message> and exits 1.
  7. Print the listening line, plus one more line with --record saying so.
a clean start output
[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.