CLI reference
Eight commands. The set is small and verb-shaped on purpose — a control plane’s CLI gets used during an incident, so the commands you need then are top-level rather than three subcommands deep.
npx @cirvix/agent-control scannpm install -g @cirvix/agent-controlthen: cirvix scancirvix scanInventory what is ungoverned on this machinecirvix checkEvaluate one hypothetical callcirvix gatewayRun the MCP gateway — intercept and enforcecirvix daemonRun the endpoint service — policy sync and telemetrycirvix whyExplain a single decision in fullcirvix replayRe-evaluate a recorded runcirvix auditVerify the decision recordcirvix policyPrint the active rule set
cirvix scan
cirvix scanRead-only. Requires no account and sends nothing anywhere. Finds agent runtimes, agent frameworks, MCP server configurations, and credential files reachable from agent context, then reports what is currently unprotected. This is the first command anyone runs, and it is deliberately useful on its own.
--json- Machine-readable output for CI
--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 Cirvix scan · read-only · nothing was changed or sent runtimes 2 found Claude Code ~/.claude/settings.json ungoverned · 3 MCP servers Cursor ~/.cursor/mcp.json ungoverned · 2 MCP servers mcp servers 5 configured github stdio inline secrets filesystem stdio broad scope credentials 2 paths reachable from agent context AWS credentials On disk and readable by any agent with filesystem access findings 3 high · 2 medium ▲ Claude Code (runtime-ungoverned) Tool calls from Claude Code are not routed through a control plane. Anything it can reach, it can reach unchecked. fix: cirvix gateway --servers ~/.claude/settings.json Nothing was changed. To see how a call would be decided: cirvix check --action fs.read --resource .envcirvix check
cirvix check --action <action> --resource <resource>Asks the engine what it would decide, and executes nothing. The fastest way to answer whether something would be allowed, and the fastest way to reproduce a decision that surprised you — the evaluator is deterministic, so the same inputs give the same answer every time.
--action <action>- Required. e.g. fs.read, shell.exec, k8s.apply
--resource <resource>- Required. Path or URL, canonicalized before matching
--policy <file>- Rule set to evaluate against (default: the starter rules)
--env <name>- Environment context (default: local)
--json- Full decision record as JSON
$ cirvix check --action fs.read --resource .env.production DENY fs.read /repo/.env.production rule deny-dotenv-read reason Reading .env files is denied outside an approved secrets flow. This is the single most common path from a prompt injection to a live credential. fix Request the value as a handle: secrets.get("STRIPE_KEY") considered → forbid deny-dotenv-readcirvix gateway
cirvix gateway --servers <file>The enforcement path. The agent connects to Cirvix believing it is talking to an MCP server; Cirvix connects to the real ones. Every tool call is decoded, evaluated, recorded, and then forwarded, refused, or held. Unlike wrapping a tool list, the gateway governs tools added after it was deployed, because it sits on the wire.
--servers <file>- Required. MCP server map — an editor's config works verbatim
--policy <file>- Rule set (default: the starter rules)
--state <dir>- Audit log and telemetry spool (default: ./.cirvix)
--agent <name>- Recorded against every decision (default: local)
--api <url> --key <cvx_…>- Attach a control plane for policy sync and telemetry
$ cirvix gateway --servers ~/.cursor/mcp.json --env staging [cirvix] gateway up · 2 upstream · 9 rules · local policy permit fs.read ./data/input.csv 0.4ms permit http.request api.internal.example.com 0.3ms deny fs.read .env.production 0.2ms └─ deny-dotenv-read hold k8s.apply production/checkout 0.3ms └─ require-approval-destructive → platform-oncall [cirvix] stopping · 4 calls · 2 permitted · 1 denied · 1 heldcirvix daemon
cirvix daemon --api <url> --key <cvx_…>Pulls policy on an interval, ships spooled decisions, and heartbeats so the control plane can tell this host apart from one that stopped reporting. It holds no inbound port — it polls outward, which is why it works behind NAT and inside a locked-down VPC without a firewall exception. The gateway starts one automatically when given an API key.
--api <url>- Control-plane URL, or CIRVIX_API_URL
--key <cvx_…>- API key, or CIRVIX_API_KEY
--state <dir>- Policy cache and telemetry spool (default: ./.cirvix)
--interval <ms>- Sync interval (default: 30000)
$ cirvix daemon --api https://api.example.com --key $CIRVIX_API_KEY [cirvix] registered endpoint ep_7Q2X9F · host build-runner-03 [cirvix] policy synced · version 14 · 11 rules [cirvix] flushed 128 decisions [cirvix] policy synced · version 14 · 11 rules (unchanged) [cirvix] flushed 96 decisions A control-plane outage is not an enforcement outage: the last known rule set stays cached and telemetry spools to disk until it returns.cirvix why
cirvix why <decision-id>The command you reach for when someone asks why an agent was refused. Prints the resolved call, every rule that was considered, which one matched, and — the part that matters in an incident — the run the decision belongs to. That is the thread to pull, rather than the one bead you arrived holding.
--json- Full decision record as JSON
--api <url> --key <cvx_…>- Control plane to read from, or the CIRVIX_API_* variables
$ cirvix why dec_01JQ8F2K7M DENY fs.read /repo/.env.production rule deny-dotenv-read reason Reading .env files is denied outside an approved secrets flow. agent pr-triage when 2026-08-06T09:14:02.418Z run run_01JQ8F2K7M considered → forbid deny-dotenv-read permit allow-workspace-read cirvix replay run_01JQ8F2K7M --diffcirvix replay
cirvix replay <run-id>Reconstructs a run from its recorded decisions and re-decides each one against the current or a candidate rule set. No side effects are executed — replay re-decides, it never re-runs. With no --policy it answers 'would today's rules have stopped this', the question asked after an incident; with one, 'what would this change break', the question asked before a merge.
--policy <file>- Replay against a candidate rule set
--diff- Show only the decisions that would change
--json- Full result as JSON
$ cirvix replay run_01JQ8F2K7M --policy candidate.json --diff run_01JQ8F2K7M agent pr-triage 38 calls changed decisions 2 of 36 00.412 fs.read /workspace/.env.production was PERMIT allow-workspace-read now DENY deny-dotenv-read → Reading .env files is denied outside an approved secrets flow. 01.240 k8s.apply production/checkout was PERMIT allow-deploy now HOLD require-approval-destructive No side effects were executed. Exit code 1 — decisions changed. Usable as a CI gate.cirvix audit
cirvix audit verifyRecomputes the hash chain and reports exactly where it breaks, if it does. Verification is independent — it recomputes the chain rather than asking a service whether it is intact. What it proves is stated on every run, because the distinction is the whole value and is routinely overstated.
--file <path>- Chain to verify (default: .cirvix/audit.jsonl)
--json- { ok, records, brokenAt?, reason? }
$ cirvix audit verify chain intact 43675 records verified Verification proves records were not altered after they were written. It does not attest to their content.cirvix policy
cirvix policyShows every rule the engine would evaluate against, in order, with its effect and reason. Rules are JSON — an ordered array in which forbid always wins, a hold outranks a permit, and anything unmatched is denied. With no --policy you get the nine starter rules, chosen so a developer working normally is not interrupted while the handful of actions that actually cause incidents are stopped or held.
--policy <file>- Rule set to print (default: the starter rules)
--json- The rules verbatim, suitable for piping
$ cirvix policy 9 rules forbid deny-dotenv-read Reading .env files is denied outside an approved secrets flow. forbid deny-credential-files Cloud, SSH, and registry credentials are never readable by an agent. forbid deny-workspace-escape The resolved path is outside the workspace root. hold require-approval-destructive Destructive or state-changing action in production. forbid deny-external-egress-after-secret This session read secret material, so outbound requests are blocked. permit allow-workspace-read Read inside the workspace root. permit allow-workspace-write Write inside the workspace root. permit allow-allowlisted-egress Destination is on the egress allowlist. permit allow-read-only-tools Read-only tool call.CLI
Start with scan.
Read-only, no account, and it tells you something true about your machine in about four seconds.
Cirvix AgentControl is in private beta. Pricing is published and plans are not yet chargeable — early access confirms your place and we will tell you before anything bills.