CLI — the operator control for the firewall

fw is the command-line tool for migrations, tenant setup, policy bundles, tool registries, MCP servers, sessions, approvals, exports, audit verification and replay. Commands that change a tenant write an audit record before they run, so the operator action itself is part of the chain.

Quick start

cargo build --release -p fw-cli

# Run migrations as the database owner.
target/release/fw --database-url "$OWNER_URL" migrate

# Seed a demo tenant, provider and gateway API key.
target/release/fw --database-url "$OWNER_URL" seed \
  --tenant demo \
  --upstream http://127.0.0.1:9000

# Create the audit checkpoint signing seed and print its public key.
target/release/fw --database-url "$OWNER_URL" audit keygen

# Verify a tenant's audit chain against the pinned public key.
target/release/fw --database-url "$OWNER_URL" audit verify \
  --tenant demo \
  --public-key <pinned-public-key>

Command groups

GroupWhat it does
DatabaseApply migrations, undo a migration, create the restricted application role, check partition ranges.
Tenant setupCreate tenants, principals, API keys, provider routes, model catalog entries, budgets, session limits and link allow-lists.
PolicyInitialize, validate, diff, build and activate Cedar bundles. Activating a bundle is denied on an unaccepted loosening.
ToolsImport or sync the tool registry, list tools, approve a tool pin, and inspect whether a tool description has changed.
MCP serversAdd servers, set credentials from stdin or an env var, sync tool lists, remove servers, generate master keys.
SessionsShow session state, declassify taint for a named human, set budgets, session limits, approval TTL and link allow-lists.
Approvals and notifiersList, show, approve, deny or expire approvals. Add, list, enable, disable and test webhook, Slack or email notifiers.
AuditGenerate signing keys, verify hash chains and checkpoints, replay recorded decisions, and compare what a candidate bundle would have decided.
ExportsAdd export sinks, filters, cursors, and tenant-level destinations for SIEM, warehouse, Kafka, S3, OTLP, webhook, syslog or files.
DetectionManage pattern rules, score inputs, benchmark classifier backends, and run calibration with a recorded report hash.

Examples

# Policy bundles
fw bundle init --team staff --out grants.cedar
fw bundle build --tenant demo --policies grants.cedar
fw bundle activate --tenant demo --bundle <hash>

# Tool registry
fw tools import --tenant demo --yaml tools.yaml
fw tools list --tenant demo
fw tools status --tenant demo --tool files/read_file --status approved

# MCP servers
fw mcp add --tenant demo --name ws --url https://mcp.example.test
fw mcp set-credential --tenant demo --name ws
fw mcp sync --tenant demo --name ws

# Sessions, budgets and declassification
fw session show --tenant demo --session <session-id>
fw session limits-set --tenant demo --session-calls 200 --session-spend 50
fw session declassify --tenant demo --session <session-id> --by operator --reason "reviewed page"

# Replay and what-if
fw replay --tenant demo --from 2026-11-01 --to 2026-11-13 --limit 1000
fw replay --tenant demo --bundle <candidate-bundle-hash>

The exact flags depend on the build, but this is the shape the CLI uses for routine operator work: tenant-scoped commands, explicit bundle hashes, audit-first writes, and no secrets in command lines.

CLI guarantees

Changes are audited first

Commands that mutate a tenant — keys, tools, bundles, MCP servers, sessions, notifiers, export sinks — write an admin_action record before the change is applied.

No secrets in command lines

Provider credentials and MCP credentials come from stdin or a named environment variable. The audit trail records the command shape without secret flags.

Verify is CI-friendly

fw audit verify exits 1 when it sees edited records, gaps, forged records, bad signatures, wrong checkpoints, or a tail that disagrees with the chain head.

Replay distinguishes what can be proven

Replay compares stored Cedar inputs with the recorded verdict. Records that lack replay data, bundles, or policy-decided evidence are counted separately rather than reported as reproductions.