CLI commands
Every `cirvix` command, every flag, and what each exits with. Taken from the binary, not from a plan.
The CLI overview page introduces the commands you reach for first. This page is the exhaustive reference. Everything except why and replay works offline, because enforcement has to — those two ask about something already recorded on a control plane.
| Command | Needs a control plane | What it does |
|---|---|---|
scan | no | Inventory what is ungoverned on this machine |
check | no | Evaluate one hypothetical call |
policy | no | Print the active rule set |
gateway | optional | Run the MCP gateway — intercepts and enforces |
daemon | yes | Run the endpoint service — policy sync and telemetry |
audit verify | no | Recompute the local decision chain |
why | yes | Explain one decision, and name its run |
replay | yes | Re-evaluate a recorded run under a candidate rule set |
help / version | no | Usage, and the version |
cirvix scan
Read-only inventory of what an agent on this machine could reach with nothing in the way. Nothing is changed and nothing is sent.
| Flag | Meaning |
|---|---|
--json | Full result as JSON |
--deep | Include MCP command lines in the output |
--sarif <file> | Write SARIF 2.1.0 for code-scanning upload |
--fail-on <level> | Exit non-zero at high|medium|low findings |
$ cirvix scan --deep --fail-on highSARIF is written before the exit-code gate, so a failing scan still produces the artifact CI is about to upload. Fingerprints are stable across runs, so a dismissal in code scanning sticks.
cirvix check
Evaluates one hypothetical call and executes nothing. --action and --resource are both required.
| Flag | Meaning |
|---|---|
--action <action> | Required. e.g. fs.read, shell.exec, k8s.apply |
--resource <resource> | Required. Path or URL, canonicalized before matching |
--policy <file> | Rule set. Omitted → the starter rules |
--agent <name> | Default local |
--env <name> | Default local |
--json | Full decision record |
$ cirvix check --action fs.read --resource .env.productioncheck builds is deliberately minimal: path.insideWorkspace is computed from --cwd, and egress.external, egress.allowlisted, and session.touchedSecret are all false. To exercise those, use evaluate() from the SDK's testing entry point.cirvix policy
Prints the active rule set — every rule the engine would evaluate against, in order.
| Flag | Meaning |
|---|---|
--policy <file> | Rule set to print. Omitted → the nine starter rules |
--json | The rules verbatim, suitable for piping |
$ cirvix policy --jsoncirvix gateway
Runs the MCP gateway over stdio. The agent talks to Cirvix; Cirvix talks to the upstream servers. Every tools/call is evaluated before it is forwarded, and every result is scanned on the way back.
| Flag | Meaning |
|---|---|
--servers <file> | Required. MCP server map — an editor's config works verbatim |
--policy <file> | Rule set. Omitted → the starter rules |
--state <dir> | Audit log and telemetry spool (default ./.cirvix) |
--agent <name> | Recorded against every decision (default local) |
--env <name> | Environment context (default local) |
--api <url> / --key <cvx_…> | Attach a control plane |
$ cirvix gateway --servers ~/.cursor/mcp.json --policy cirvix.policy.json--servers accepts mcpServers (Claude Code, Cursor, Windsurf) or servers (VS Code), so you point at the file you already have. stdio transport only. An entry named cirvix is skipped, otherwise pointing the gateway at a governed config would make it proxy itself.
Without --api and --key the gateway still enforces, from the local rule set — the product is useful before you have an account. With them, a daemon starts alongside to supply policy, register the agent, open a run, and ship telemetry.
cirvix daemon
Runs the endpoint service on its own: policy sync, telemetry, and heartbeat. It holds no inbound port — it polls outward.
| Flag | Meaning |
|---|---|
--api <url> | Required. Or CIRVIX_API_URL |
--key <cvx_…> | Required. Or CIRVIX_API_KEY |
--state <dir> | Default ./.cirvix |
--interval <ms> | Sync interval, default 30000 |
$ cirvix daemon --api https://api.example.com --key $CIRVIX_API_KEYcirvix audit verify
Recomputes the local hash chain and reports the first break. verify is the only subcommand; anything else exits 2.
| Flag | Meaning |
|---|---|
--file <path> | Chain to verify (default .cirvix/audit.jsonl) |
--json | { ok, records, brokenAt?, reason? } |
$ cirvix audit verifycirvix why
Explains one recorded decision in full, and names the run it belongs to — the thread to pull in an incident.
| Flag | Meaning |
|---|---|
--json | Full decision record as JSON |
--api <url> / --key <cvx_…> | Control plane to read from |
$ cirvix why dec_01JQ8F2K7Mcirvix replay
Re-evaluates every step of a recorded run under a candidate rule set. No side effects are executed.
| Flag | Meaning |
|---|---|
--policy <file> | Candidate rule set. Omitted → replays against live policy |
--diff | Show only the steps whose verdict changed |
--json | Full result |
$ cirvix replay run_01JQ8F2K7M --policy candidate.json --diffSteps recorded without enough context to re-decide are reported as not replayable rather than counted as unchanged, and changed is always stated as a fraction of replayable.
Exit codes
| Code | Meaning |
|---|---|
0 | Success, or a permitted/held decision |
1 | A substantive negative: findings over the gate, a deny, a broken chain, a changed replay |
2 | Usage error, or an unhandled exception |
1 and 2 are kept distinct so CI can tell "the tool worked and the answer was no" from "the tool did not run".