init & config
The onboarding wizard and config tooling — write the starter bitrouter.yaml, validate it against the published schema.
BitRouter discovers its config in this order — first hit wins:
./bitrouter.yamlin the current directory$BITROUTER_HOME/bitrouter.yaml(must exist when the variable is set)~/.bitrouter/bitrouter.yaml- Zero-config — in-memory defaults, auto-enabling any provider whose API key is set in the environment
Any command taking -c/--config overrides discovery. The daemon chdirs into the config's directory on startup, so relative paths (database.url, policy.path) resolve there. A JSON Schema for the config lives at dist/schema/bitrouter.config.schema.json in the repo for IDE autocomplete.
The full onboarding walkthrough — wizard steps, headless flags, recipes — is Onboarding.
bitrouter init
Write a starter bitrouter.yaml (with skip_auth: true)
Usage: bitrouter init [OPTIONS]
Options
| Flag | Description |
|---|---|
-c, --config <CONFIG> | Path to write [default: bitrouter.yaml] |
-j, --json | Force JSON output (the default; agent-native). Conflicts with --human |
--human | Render the human-readable view to stdout instead of JSON |
Re-runs the wizard interactively; with --yes it never blocks and emits a JSON result envelope — the form an agent or CI should drive. Refuses to overwrite an existing bitrouter.yaml unless --force.
bitrouter init --yes --use-detected --harness claude --after servebitrouter config
Configuration tooling (validation against the published schema)
Usage: bitrouter config [OPTIONS] <COMMAND>
Options
| Flag | Description |
|---|---|
-j, --json | Force JSON output (the default; agent-native). Conflicts with --human |
--human | Render the human-readable view to stdout instead of JSON |
bitrouter config validate
Validate a config file: structure, provider derives resolution, and upstream-URL (SSRF) safety. Exits non-zero on an invalid config — safe to run in CI. Unset ${VAR} references are substituted with a placeholder and reported as warnings, so secrets need not be present
Usage: bitrouter config validate [OPTIONS]
Options
| Flag | Description |
|---|---|
-c, --config <CONFIG> | Path to bitrouter.yaml / bitrouter.json. When omitted, the standard resolution chain applies (./bitrouter.yaml → $BITROUTER_HOME → ~/.bitrouter) |
-j, --json | Force JSON output (the default; agent-native). Conflicts with --human |
--human | Render the human-readable view to stdout instead of JSON |
The CI-safe check: exits non-zero when the config doesn't match the schema.
bitrouter config validate -c ./bitrouter.yamlHow is this guide?