CLI reference

The cerbix binary runs the platform, maintains its database and talks to a remote instance from CI/CD. This page lists every command, its flags, the environment it reads and the exit codes it returns.

Command overview

Command	Group	Purpose
serve	Runtime	Run cerbix in one process role.
migrate	Runtime	Apply database migrations and exit.
reencrypt	Runtime	Re-encrypt stored secrets with the current primary key.
adopt-fact-month	Reliability maintenance	Adopt one retained month of service-reliability facts.
enqueue-service-repair	Reliability maintenance	Queue an audited repair range for one service.
gate check	CI/CD	Ask the reliability gate whether a release may proceed.
change record	CI/CD	Record a deploy, rollback or flag change phase.
version	Other	Print build information as JSON.

Flags use the long form: --config <path> or --config=<path>. Durations use Go syntax (10s, 10m).

Exit codes

All commands share three codes. gate check and change record add result codes, listed in their sections.

Code	Meaning
0	Success.
1	Configuration, database, network or runtime failure.
2	CLI usage error: unknown command, missing required flag, invalid value.

Running cerbix with no command prints the command catalogue to stderr and exits 2.

Help and parsing

cerbix --help
cerbix gate check --help

Help does not load configuration or contact any dependency.

• cerbix <command> --help and cerbix help <command> print required flags, options with defaults, environment variables, exit codes and examples, and exit 0.
• -h is the only shorthand. Single-dash flags such as -config and clusters such as -hh fail with exit 2 before any side effect. Use --config.
• An explicit --help=false is refused with exit 2 on every command except version.
• Leaf commands reject positional arguments with exit 2.
• version exits 1 with a version: diagnostic if it cannot write its JSON.

Configuration file

The runtime and maintenance commands read a YAML file given with --config. Before parsing, cerbix expands ${VAR} and $VAR from the process environment. An undefined variable fails the load. A defined but empty variable is accepted. Write a literal $ as $$. A file that fails to load or validate exits 1 before any work starts. See Configuration.

serve

cerbix serve --config <path> [--role all|api|scheduler|worker|agent] [--region <name>]

Flag	Required	Default	Description
--config	yes	—	Path to the config YAML.
--role	no	all	Process role: all, api, scheduler, worker or agent.
--region	no	empty	Worker or agent region. Empty means the core region.

Role	Runs
all	The whole stack in one process, with an in-process dispatcher.
api	REST API, SSE, embedded UI, check-result consumer and outbox delivery.
scheduler	Leader-elected job scheduling, rollups, retention, alerts and escalations.
worker	Stateless prober pool for one region’s queue.
agent	HTTP-pull prober for a region without broker access. It uses no database or broker and reaches the central API over outbound HTTPS.

With database.dsn set, every role except agent applies pending migrations at startup. The distributed roles api, scheduler and worker require rabbitmq.url. Every role serves /healthz, /readyz and /metrics on server.listen. SIGINT and SIGTERM trigger a graceful shutdown.

Exit codes: 0 services stopped cleanly; 1 configuration, startup, dependency, runtime or shutdown failure; 2 usage error.

See Architecture and Geo probers.

migrate

cerbix migrate --config <path>

Flag	Required	Default	Description
--config	yes	—	Path to the config YAML.

Applies the embedded migrations and exits without starting services. Requires database.dsn. The run has a 60 s budget.

Exit codes: 0 migrations applied; 1 configuration, database or migration failure; 2 usage error.

reencrypt

cerbix reencrypt --config <path>

Flag	Required	Default	Description
--config	yes	—	Path to the config YAML.

Rewrites stored webhook and notification-channel secrets with the current primary key, security.encryption_key. Data encrypted with an older key stays readable while that key is listed in security.previous_keys. Requires database.dsn and security.encryption_key. The run has a 5 min budget and logs the number of rewritten webhooks and channels.

Exit codes: 0 stored secrets re-encrypted; 1 configuration, database, key or rewrite failure; 2 usage error.

Caution

Keep the previous key in security.previous_keys until reencrypt exits 0. Secrets not yet rewritten still need it to decrypt.

adopt-fact-month

Caution

adopt-fact-month and enqueue-service-repair are operator recovery tools. Neither has a dry-run or a confirmation prompt. Take a database backup first and run them in a maintenance window.

cerbix adopt-fact-month --config <path> --month YYYY-MM [--timeout 10m]

Flag	Required	Default	Description
--config	yes	—	Path to the config YAML.
--month	yes	—	Month to adopt, YYYY-MM (UTC).
--timeout	no	10m	Total budget for the fenced cutover, from the parent lock through commit. Must be positive.

Moves one month of service-reliability facts from the DEFAULT partition into its monthly partition through the copy-authoritative recovery path. It changes physical placement only, not fact values. A month that is already attached is a no-op success. The cutover holds the parent-table lock through commit. Use it when automatic adoption reports an oversize month or keeps timing out. See the Runbook.

Exit codes: 0 month adopted or already attached; 1 configuration, database or adoption failure; 2 usage error, including a malformed --month or a non-positive --timeout.

enqueue-service-repair

cerbix enqueue-service-repair --config <path> --project <id> --service <id> --from <RFC3339> --to <RFC3339>

Flag	Required	Default	Description
--config	yes	—	Path to the config YAML.
--project	yes	—	Project ID.
--service	yes	—	Service ID.
--from	yes	—	Range start, RFC3339. Floored to the bucket.
--to	yes	—	Range end, RFC3339. Ceiled to the bucket. Must be after --from.

Queues a durable repair with reason admin. The command does not recompute anything itself. The scheduler leader recomputes the range later through the normal audited repair path and coalesces overlapping pending work. A recompute can restate sealed service facts. Choose a range that raw-evidence retention still covers.

Exit codes: 0 repair range durably queued; 1 configuration, database or enqueue failure; 2 usage error, including an invalid or empty range.

gate check

cerbix gate check --project <id> --service <id> [--json] [--timeout 10s]

Flag	Required	Default	Description
--project	yes	—	Project ID.
--service	yes	—	Service ID.
--json	no	false	Print the API response body byte for byte, without a trailing newline, instead of the summary line.
--timeout	no	10s	Overall request deadline. Must be positive.

Variable	Required	Description
CERBIX_URL	yes	Server base URL, http:// or https://. A path prefix is allowed; credentials, a query or a fragment are refused.
CERBIX_TOKEN	yes	API bearer token. Environment only; there is no flag.
CERBIX_CA_FILE	no	PEM CA file added to the system roots.

The command reads no config file and opens no database. It sends one POST to /api/v1/projects/<id>/services/<id>/gate and never retries, including on 429. It does not follow redirects; set CERBIX_URL to the final address. TLS verification has no bypass, and the minimum version is TLS 1.2. Standard proxy variables such as HTTPS_PROXY apply.

The decision goes to stdout as one line. Each reason goes to stderr.

state=<STATE> [action=<ACTION>] policy_source=<SOURCE> policy_owner_id=<ID> policy_revision=<REVISION> window_mode=<MODE> evaluated_windows=<WINDOWS> [override=<actor_label>] decision=<decision_id>

Absent values print as none. UNKNOWN stays visible in state whatever the action.

Code	Meaning
0	Action ALLOW or WARN.
1	Transport, timeout, TLS, authentication, 429, server or malformed-response error. A missing CERBIX_URL or CERBIX_TOKEN is also 1.
2	Action BLOCK, or a usage error.
4	State NOT_CONFIGURED: the service has no gate policy.

See Release gate.

change record

cerbix change record --project <id> --service <id> --kind <kind> --phase <phase> --source <slug> --external-id <id> [--ref <label>] [--url <https-url>] [--decision <id>] [--at <RFC3339>] [--json] [--timeout 10s]

Flag	Required	Default	Description
--project	yes	—	Project ID.
--service	yes	—	Service ID.
--kind	yes	—	deploy, rollback or flag.
--phase	yes	—	started, succeeded, failed or cancelled.
--source	yes	—	Slug of the reporting system, for example github-actions.
--external-id	yes	—	The change’s ID at the source, for example the run ID.
--ref	no	—	Label for the change, for example a version or commit. Omitted from the request when not given.
--url	no	—	https:// link to the change. Omitted from the request when not given.
--decision	no	—	The gate decision_id the release rested on.
--at	no	invocation time	When the phase occurred, RFC3339.
--json	no	false	Print the API response body byte for byte instead of the summary line.
--timeout	no	10s	Overall request deadline. Must be positive.

Environment variables and network behaviour are the same as for gate check. The command sends one POST to /api/v1/projects/<id>/services/<id>/changes. The server validates enum values; the CLI passes them through unchanged.

Stdout carries one line: recorded change=<id> kind=<kind> phase=<phase>, or replayed … when the server matched an identical earlier record.

Code	Meaning
0	Recorded (201) or replayed (200).
1	Transport, timeout, TLS, authentication (401, 403), 429, server or malformed-response error.
2	Refused by the contract (400, 404, 409), or a usage error. The server’s error text is printed to stderr.

See Change intelligence.

version

cerbix version

Prints build information as indented JSON and exits 0. The values below are placeholders:

{
  "version": "<version>",
  "commit": "<commit>",
  "go_version": "<go version>"
}