Reference
CLI reference
Every command and option, generated from the CLI by scripts/gen/docs_reference.py. If it is on this page, it runs.
The commands are grouped the way the work goes: see what you have, watch it run, contain what it can do, prove it. agentfox --help prints the same panels, and every command takes --help. For walkthroughs that put these commands together, start with the Quickstart.
agentfox --help
agentfox scan --help| Stage | Command | What it is for |
|---|---|---|
| Start | init | Set everything up. |
demo | Run the end-to-end walkthrough (offline). | |
| See | scan | Find what is worth governing: a repo, local sessions, an MCP server, the runtime. |
agents | Find every agent that is running, and who owns it. | |
| Watch | serve | Run the gateway and control-plane API, or the MCP server for AI clients. |
findings | What the platform found. | |
| Contain | permit | Grant, list and withdraw what an agent — or an end user — may do, and decide the calls held for a person (`permit approvals`). |
declare | Declare the facts containment reasons over: tools, data scope, sources, hand-offs. | |
policy | Write the rules, try them against recorded traffic, then turn them on. | |
| Prove | test | Prove the controls hold before you ship: score, gate, attack, and dry-run. |
report | What you can show an auditor: posture, evidence, risk, sign-off. | |
| Operate | doctor | Is the runtime configured the way you think it is? |
admin | Run the deployment: operators, tokens, schema, scheduled jobs, key rotation, catalog upkeep, hooks, seed data. |
agentfox init
Set everything up. Idempotent, offline, and safe to run twice. Creates the database, applies migrations, loads the control catalog and the shipped policy packs, each in the mode it declares (baseline and eu-ai-act-high-risk observe; tool-containment enforces; coding-agent only for agents this repo's coding-harness hooks govern), and writes a agentfox.toml carrying the real runtime defaults so they are visible rather than implicit. AGENTFOX_* environment variables override that file.
agentfox init [OPTIONS]| Argument / option | Meaning |
|---|---|
--path, -p path | Where to write agentfox.toml. Default: here. Default: .. |
--env, -e text | Name this deployment: development, staging or production. It decides how strictly `agentfox doctor` grades authentication. Default: development. |
--demo | Also load the demo fixtures: three agents and an eval suite. No traffic is recorded; run `agentfox demo` afterwards for sample traces and findings. |
agentfox demo
Run the end-to-end walkthrough (offline).
agentfox demoagentfox scan
Find what is worth governing: a repo, local sessions, an MCP server, the runtime. `agentfox scan [PATH] [--fail] [--json]` scans a repository (the default). `agentfox scan --sessions [PATH]` also reads local AI-tool sessions and runs the live detector check. `mcp`, `skills` and `runtime` scan the rest; `monitors` re-checks connected sources on a schedule.
agentfox scan [COMMAND]Run with no subcommand, it does scan repo.
agentfox scan skills
Scan agent skills for planted instructions and declared danger. A skill is the same object as an MCP tool one layer up: a description the model reads to decide whether to invoke it, and instructions it then obeys. OWASP published an Agentic Skills Top 10 in 2026 and we scanned servers but not skills.
agentfox scan skills [PATH] [OPTIONS]| Argument / option | Meaning |
|---|---|
PATH | Directory to search for SKILL.md files. Default: .. |
--persist, --no-persist | Raise findings, or just print. Default: true. |
agentfox scan mcp
Check an MCP server: what it can reach, how it is pinned, and its tools. Reads your MCP client config and registers every server it declares, so there is nothing to set up first. Nothing is started: without --file the check covers what the config shows (version pinning, remote auth, credentials in the file) and what the server can reach. With --file (the server's tools/list output) it also snapshots the tools and flags poisoned descriptions and changes since last time.
agentfox scan mcp [SERVER] [OPTIONS]| Argument / option | Meaning |
|---|---|
SERVER | Server name as your MCP config declares it. Omit to scan every one. |
--file path | Tool list JSON (what the server's tools/list returned). |
--config path | MCP client config to read servers from. Default: the first of .mcp.json, .cursor/mcp.json, .claude/settings.json, .claude.json and claude_desktop_config.json found in this directory. |
--seed-fixture | Scan the built-in demo tool list instead of --file. For demos only. |
--json | Machine-readable output for scripts. |
agentfox scan repo
Scan a repository and highlight everything worth governing. Static only: reads the source, never imports or runs it. Importing the target would execute arbitrary code from a repo the operator may not trust, and would fail on anything with an import-time side effect — which is most real applications. Stays entirely local unless `--submit` (or an interactive "yes") opts into sending a redacted summary — see `cli/submit.py`.
agentfox scan repo [PATH] [OPTIONS]| Argument / option | Meaning |
|---|---|
PATH | Directory to scan. Default: here. Default: .. |
--json | Full records for scripts: every site, whole paths, no table. |
--limit, -n integer | How many sites to show, worst first. Default: 15. |
--fail | Exit non-zero if any model call is ungoverned (for CI). |
--submit, --no-submit | Send a redacted summary (counts and structure only, never file contents) to a running control plane for a fuller dashboard report. Optional — omit both flags to be asked interactively. |
agentfox scan runtime
Sweep for shadow agents, unowned agents, registry drift, identity posture and delegation cycles/depth.
agentfox scan runtimeagentfox scan monitors
Watch connected sources on a schedule: list, add, pause, resume, remove, run.
agentfox scan monitors COMMANDagentfox scan monitors list
Every monitor, its last outcome, and when it runs next.
agentfox scan monitors list [OPTIONS]| Argument / option | Meaning |
|---|---|
--json | Print JSON. |
agentfox scan monitors add
Start watching a source. Its first run stores a baseline; later runs report changes.
agentfox scan monitors add KIND TARGET [OPTIONS]| Argument / option | Meaning |
|---|---|
KIND required | github_repo, hosted_api, mcp_server or deployed_agent. |
TARGET required | owner/repo, the spec URL, the MCP server name, or a probe target id. |
--every text | Interval, e.g. 30m, 6h, 1d. Default per kind. |
--name text | A label for lists and alerts. |
agentfox scan monitors pause
Stop scheduled runs. Open findings stay open.
agentfox scan monitors pause IDENT| Argument / option | Meaning |
|---|---|
IDENT required | Monitor id or target. |
agentfox scan monitors resume
Resume scheduled runs.
agentfox scan monitors resume IDENT| Argument / option | Meaning |
|---|---|
IDENT required | Monitor id or target. |
agentfox scan monitors remove
Stop watching a source. Its findings are kept.
agentfox scan monitors remove IDENT| Argument / option | Meaning |
|---|---|
IDENT required | Monitor id or target. |
agentfox scan monitors run
Run one monitor now, or every monitor that is due.
agentfox scan monitors run [IDENT] [OPTIONS]| Argument / option | Meaning |
|---|---|
IDENT | Monitor id or target. Omit to run every due monitor. |
--json | Print JSON. |
agentfox agents
Find every agent that is running, and who owns it.
agentfox agents COMMANDagentfox agents list
List every agent, registered or shadow.
agentfox agents list [OPTIONS]| Argument / option | Meaning |
|---|---|
--json | — |
--stopped | Only agents that are quarantined or killed, and why. |
agentfox agents register
Register an agent (or update one), so it is owned rather than shadow. Agents also appear on their first call; registering one up front gives it an owner and an environment before it has run, and turns a shadow agent into a registered one. Options left out keep the agent's current values.
agentfox agents register SLUG [OPTIONS]| Argument / option | Meaning |
|---|---|
SLUG required | Agent slug, e.g. support-triage. |
--name text | Display name. Default: the slug. |
--owner text | Owner's email. An agent with no owner is a finding. |
--team text | Owning team. |
--env text | Environment it runs in. Default: production, or its current one. |
--risk-tier text | minimal | limited | high | prohibited. Default: limited, or its current one. |
agentfox agents budget
Show or set an agent's budget: the caps `budget.exceeded` blocks on. With no option it prints the current caps and usage. Each option sets one cap and leaves the others as they are; 0 removes that cap. Over a cap, the agent's calls are blocked (`budget.exhausted`) until the window rolls over.
agentfox agents budget SLUG [OPTIONS]| Argument / option | Meaning |
|---|---|
SLUG required | Agent slug. |
--max-calls integer | Calls per window. |
--max-tokens integer | Tokens per window. |
--max-cost-usd float | Spend per window, in USD. |
--max-depth integer | Longest tool-call chain in one run. |
--window text | minute | hour | day. |
--clear | Remove the agent's budget. |
agentfox agents lineage
Show what an agent reaches — the blast radius.
agentfox agents lineage SLUG [OPTIONS]| Argument / option | Meaning |
|---|---|
SLUG required | — |
--depth integer | — Default: 2. |
agentfox agents quarantine
Stop an agent while you investigate. Reversible and audited.
agentfox agents quarantine SLUG [OPTIONS]| Argument / option | Meaning |
|---|---|
SLUG required | — |
--reason, -r text | — |
agentfox agents kill
Stop an agent now.
agentfox agents kill SLUG [OPTIONS]| Argument / option | Meaning |
|---|---|
SLUG required | — |
--reason, -r text | — |
agentfox agents resume
Restart a stopped agent.
agentfox agents resume SLUG [OPTIONS]| Argument / option | Meaning |
|---|---|
SLUG required | — |
--reason, -r text | — |
agentfox serve
Run the gateway and control-plane API, or the MCP server for AI clients. `agentfox serve [--host] [--port] [--reload]` starts the API (the default); `agentfox serve mcp` speaks MCP over stdio.
agentfox serve [COMMAND]Run with no subcommand, it does serve api.
agentfox serve api
Start the gateway and control-plane API.
agentfox serve api [OPTIONS]| Argument / option | Meaning |
|---|---|
--host text | — Default: 127.0.0.1. |
--port integer | — Default: 8080. |
--reload, --no-reload | — |
agentfox serve mcp
Serve MCP over stdio (for Claude Code, Claude Desktop and other MCP clients). Read-only by design: nothing that changes enforcement or stops an agent is exposed.
agentfox serve mcpagentfox findings
What the platform found. The list `agentfox.auto()` tells you to read. Ordered worst first, then most recently seen. A finding that keeps happening is one row with a count, not one row per occurrence, so the length of this list is the number of distinct problems. `--types` lists the kinds of finding there are.
agentfox findings [OPTIONS]| Argument / option | Meaning |
|---|---|
--severity, -s text | Show only this severity: critical, high, medium, low or info. |
--limit, -n integer | How many findings to show, worst first. Default: 20. |
--json | Full records for scripts: whole ids, fingerprints, subjects and timestamps. |
--types | List every finding type instead: what each means, its usual severity, who raises it. |
agentfox permit
Grant, list and withdraw what an agent — or an end user — may do, and decide the calls held for a person (`permit approvals`).
agentfox permit COMMANDagentfox permit grant
Allow an agent to call a tool, and say under what limits. Least privilege is default deny: an agent with no grant for a tool cannot call it, whether or not a detector fires. This command is the only thing that widens that, so it asks before it writes and records the result in the audit chain.
agentfox permit grant AGENT TOOL [OPTIONS]| Argument / option | Meaning |
|---|---|
AGENT required | Agent slug, e.g. payments-ops. |
TOOL required | Tool key this grant covers. A glob is allowed: tickets.* or *. |
--action, -a text | Action on the tool this grant covers, repeatable. Default: every action. Repeatable. |
--limit, -l text | Argument limit, repeatable. path=value, or path:op=value — for example --limit amount:lt=1000 --limit currency:in=USD,EUR. Repeatable. |
--max-taint text | Worst provenance an argument may carry and still go through without an approval. One of: none, user, retrieved, tool_result, subagent, memory. Default: user. |
--requires-approval, --no-requires-approval | Send every matching call to a human before it runs. |
--expires-in-days integer | Withdraw the grant automatically after this many days. Default: no expiry. |
--granted-by text | Who is accountable for this grant. Recorded in the audit. Default: cli. |
--yes, -y | Skip the confirmation prompt (for scripts and CI). |
agentfox permit list
What each agent is allowed to do. Anything not listed here is refused.
agentfox permit list [AGENT] [OPTIONS]| Argument / option | Meaning |
|---|---|
AGENT | Agent slug. Omit to list every agent's grants. |
--json | Machine-readable output for scripts. |
agentfox permit revoke
Withdraw a grant. The agent's calls to that tool are refused from now on.
agentfox permit revoke CAPABILITY_ID [OPTIONS]| Argument / option | Meaning |
|---|---|
CAPABILITY_ID required | Grant id from `agentfox permit list`, e.g. cap_01h.... |
--yes, -y | Skip the confirmation prompt (for scripts and CI). |
agentfox permit user
Grant access to a resource pattern.
agentfox permit user RESOURCE PRINCIPAL [OPTIONS]| Argument / option | Meaning |
|---|---|
RESOURCE required | Resource pattern, e.g. 'hr/*'. |
PRINCIPAL required | Group or subject the grant is for. |
--kind text | group | subject Default: group. |
--classes text | mnpi, legal_hold, pii_sensitive… |
--purposes text | GDPR Art. 5(1)(b) purposes. |
agentfox permit approvals
See the calls waiting for a person, and approve or deny them.
agentfox permit approvals COMMANDagentfox permit approvals list
The calls held for a person. Unanswered ones expire, and expiry denies.
agentfox permit approvals list [OPTIONS]| Argument / option | Meaning |
|---|---|
--status text | pending (the default), approved, denied, expired, used, or all. Default: pending. |
--agent text | Only this agent's approvals. |
--json | Machine-readable output for scripts. |
agentfox permit approvals show
One approval in full: the call, its arguments, why it was held, and the decision.
agentfox permit approvals show APPROVAL_ID [OPTIONS]| Argument / option | Meaning |
|---|---|
APPROVAL_ID required | Approval id, or the short id `list` prints. |
--json | Machine-readable output for scripts. |
agentfox permit approvals approve
Let the held call run once: the same agent, tool and arguments, when retried.
agentfox permit approvals approve APPROVAL_ID [OPTIONS]| Argument / option | Meaning |
|---|---|
APPROVAL_ID required | Approval id, or the short id `list` prints. |
--rationale, -r text | Why, for the audit record. |
--as text | Who is deciding (an email), for the audit record. |
agentfox permit approvals deny
Refuse the held call. A retry presenting this approval escalates again.
agentfox permit approvals deny APPROVAL_ID [OPTIONS]| Argument / option | Meaning |
|---|---|
APPROVAL_ID required | Approval id, or the short id `list` prints. |
--rationale, -r text | Why, for the audit record. |
--as text | Who is deciding (an email), for the audit record. |
agentfox declare
Declare the facts containment reasons over: tools, data scope, sources, hand-offs. What a tool can do, which column says whose row it is, what an agent has no data for, which sources are authoritative, and when to hand off to a person.
agentfox declare COMMANDagentfox declare tool
Declare a tool and what it can do. Containment is declared, not detected: an irreversible tool recorded as `read` is one a tainted argument can reach. This is the command that makes least privilege real, and it is deliberately the first thing `agentfox init` points at.
agentfox declare tool KEY [OPTIONS]| Argument / option | Meaning |
|---|---|
KEY required | — |
--impact text required | read | write | high_impact | irreversible — the axis every containment rule reasons over. |
--name text | — |
--description text | — |
--triggers text | Comma-separated downstream effects. |
--output-trust text | untrusted | trusted — whether values copied out of this tool's output taint the arguments they land in. Default for a new tool: untrusted. Declare trusted only for a system of record you control, such as a CRM read. |
--effect text | communication — this tool's irreversible effect is a message leaving (an email, a chat message, a notification), not data destroyed, money moved or state changed. A cascade whose only irreversible tail is such a tool is escalated for approval rather than blocked. Pass '' to clear. |
agentfox declare triggers
Declare what a tool call sets off downstream (a DB trigger, a webhook, a fan-out), so `cascade_risk()` can actually see it. An undeclared trigger stays invisible by design (see `effects.cascade_risk`'s own docstring) — this is how an operator closes that gap for one tool.
agentfox declare triggers KEY [OPTIONS]| Argument / option | Meaning |
|---|---|
KEY required | Tool key, e.g. demo.delete_user |
--triggers text | Comma-separated tool keys this call sets off downstream |
agentfox declare scope
Declare which column on a table decides whose row it is, so `analyse_access()` can prove a query is scoped instead of assuming it. An undeclared table is reported, never assumed safe (see `data_access`'s own docstring).
agentfox declare scope TABLE [OPTIONS]| Argument / option | Meaning |
|---|---|
TABLE required | Table name |
--column text required | Column that decides whose row it is |
--principal-key text | Attribute of the calling principal the column must equal Default: id. |
--restricted-columns text | Comma-separated columns nobody should receive even for their own row |
agentfox declare reference
Declare a table that belongs to nobody, so `analyse_access()` does not flag it as an undeclared/unscoped table.
agentfox declare reference TABLE| Argument / option | Meaning |
|---|---|
TABLE required | Table name — belongs to nobody (currencies, statuses, postcodes) |
agentfox declare boundary
Declare what an agent is allowed to answer from. Until this exists nothing stops the agent inventing an answer to a question it has no data for, which is the single failure most likely to reach a customer. Re-running it changes only the options you pass, so `--mode enforce` on its own switches enforcement on and keeps the systems, coverage and topics already declared.
agentfox declare boundary AGENT [OPTIONS]| Argument / option | Meaning |
|---|---|
AGENT required | Agent slug. |
--systems text | Comma-separated systems of record. |
--coverage-months integer | Rolling window. |
--answerable text | Question types this agent may answer (default fact,aggregate,procedure). |
--out-of-scope text | Comma-separated topics. |
--mode text | observe | enforce (a new boundary starts in observe) |
agentfox declare source
Register a source and its authority tier.
agentfox declare source KEY [OPTIONS]| Argument / option | Meaning |
|---|---|
KEY required | Identifier the retriever emits. |
--tier, -t text | — Default: unverified. |
--owner text | — |
--domain text | — |
--sla-hours integer | Freshness SLA. |
--updated text | When the source last changed (ISO, or 'now'). |
--title text | — |
agentfox declare import-sources
Bulk-register from a JSON file. Tiering a corpus is inherently a bulk act. Nobody classifies four hundred sources one command at a time, and making them try is how the tiering never happens.
agentfox declare import-sources FILE| Argument / option | Meaning |
|---|---|
FILE required | JSON list of sources. |
agentfox declare escalation
Declare when this agent must hand off to a human.
agentfox declare escalation [OPTIONS]| Argument / option | Meaning |
|---|---|
--agent text | Agent slug; omit for the default. |
--turn-depth integer | — |
--repeated-failure integer | — |
--sla-minutes integer | — Default: 60. |
--owner text | — Default: support. |
--mode text | observe: record missed escalations as findings. enforce: hand the conversation off on the turn it qualifies. Default: observe. |
agentfox declare principal
Register the human an agent acts for. Everything else in this pillar depends on this. The Copilot failure is its absence: the agent runs under its own identity, inherits everything that identity can reach, and every permission check passes.
agentfox declare principal SUBJECT [OPTIONS]| Argument / option | Meaning |
|---|---|
SUBJECT required | IdP subject — an OIDC `sub` or employee id. |
--groups, -g text | Comma-separated groups. |
--clearances text | Restricted classes they may see. |
--residency text | — |
--display text | — |
agentfox declare list
Everything declared so far: tools and their impact, sources and their tier.
agentfox declare list [KIND] [OPTIONS]| Argument / option | Meaning |
|---|---|
KIND | tools, sources, or all (the default; not with --json). Default: all. |
--json | — |
agentfox policy
Write the rules, try them against recorded traffic, then turn them on.
agentfox policy COMMANDagentfox policy list
List policies and their enforcement mode.
agentfox policy listagentfox policy lint
Lint the policy hierarchy, or policy files. Exits 1 on critical or high findings. This is the half of hierarchical policy that produces the 87% misconfiguration reduction — composition without a linter just moves the confusion somewhere harder to see. Pass files to check them before they are loaded, e.g. in CI.
agentfox policy lint [FILES]| Argument / option | Meaning |
|---|---|
FILES | Policy files to lint, as org-level layers in the order given. Without files, lints every bound policy layer. |
agentfox policy effective
Show the policy actually in force for a subject, and where each rule came from. Opacity is what makes layered policy dangerous, so the resolver explains itself.
agentfox policy effective [OPTIONS]| Argument / option | Meaning |
|---|---|
--agent text | — |
--team text | — |
--user text | — |
--environment text | Environment to resolve for. Defaults to the configured environment (AGENTFOX_ENVIRONMENT), which is what the runtime itself uses. |
agentfox policy simulate
Replay recorded traffic against a candidate policy. Exits non-zero when the change would newly block production traffic, so it can gate a policy PR the same way `eval gate` gates a code PR.
agentfox policy simulate [OPTIONS]| Argument / option | Meaning |
|---|---|
--file, -f path required | Candidate policy YAML. |
--agent text | — |
--since-days integer | — Default: 30. |
--limit integer | — Default: 1000. |
agentfox policy enforce
Promote a policy from observe to enforce.
agentfox policy enforce KEY| Argument / option | Meaning |
|---|---|
KEY required | — |
agentfox policy observe
Demote a policy from enforce to observe.
agentfox policy observe KEY| Argument / option | Meaning |
|---|---|
KEY required | — |
agentfox policy validate
Check, lint and compile a policy file without saving it. Runs the full lint (`policy lint FILE`), so a rule that can never fire or a condition naming an unknown value (`surface: [toolargs]`) fails validation. Exits 1 on a parse error or a critical/high finding.
agentfox policy validate FILE| Argument / option | Meaning |
|---|---|
FILE required | — |
agentfox policy export
Write every policy, custom rule and detector switch as one YAML file.
agentfox policy export [OPTIONS]| Argument / option | Meaning |
|---|---|
--out, -o path | Write to this file instead of stdout. |
agentfox policy apply
Make the workspace match a file from `policy export`. Shows the plan first. Anything the file leaves out is left alone. A policy the file moves to enforce is simulated against the last week first.
agentfox policy apply FILE [OPTIONS]| Argument / option | Meaning |
|---|---|
FILE required | — |
--yes, -y | Apply without asking. |
agentfox policy catalogue
Every kind of guardrail this product can enforce. The answer to "can we express our policy?" — asked before anyone writes YAML.
agentfox policy catalogue [OPTIONS]| Argument / option | Meaning |
|---|---|
--intent text | — |
--json | — |
agentfox policy compile
Turn a written policy into executable guardrails.
agentfox policy compile FILE [OPTIONS]| Argument / option | Meaning |
|---|---|
FILE required | Policy document (.txt or .md). |
--apply | Save the compiled rules. |
--json | — |
agentfox policy packs
Capability packs: the policies, controls, ladders, probes and cases a use case ships as one directory. Bare `agentfox policy packs` lists the policy files on disk and where each came from (`files`). `list`, `show`, `test` and `validate` work on the packs themselves.
agentfox policy packs [COMMAND]Run with no subcommand, it does policy packs files.
agentfox policy packs files
Policy files on disk, and where each came from. `policy list` reads the database: what is installed and what mode it is in. This reads the filesystem and answers the question an operator has about a policy they did not write — which file is this, and did something override it. A project pack replacing a shipped one is invisible in `policy list`, because by then they are the same row.
agentfox policy packs filesagentfox policy packs list
Capability packs: built in, installed, and the project's, and whether each loads.
agentfox policy packs list [OPTIONS]| Argument / option | Meaning |
|---|---|
--all | Also packs that do not load (maturity, version). |
--json | — |
agentfox policy packs show
One pack: its manifest, where it is, and what it ships.
agentfox policy packs show PACK_ID [OPTIONS]| Argument / option | Meaning |
|---|---|
PACK_ID required | A pack id (payments/refunds) or a pack directory. |
--json | — |
agentfox policy packs test
Run each pack's golden cases (`cases/*.yaml`). Exits 1 if any fails.
agentfox policy packs test [PACKS] [OPTIONS]| Argument / option | Meaning |
|---|---|
PACKS | Pack ids or directories; default all loaded. |
--json | — |
agentfox policy packs validate
Check a pack: its pack.yaml, that its policies load and lint clean, that its ladders, probes, controls and checks are well formed, and that its cases pass. Exits 1 on any problem.
agentfox policy packs validate [PACKS] [OPTIONS]| Argument / option | Meaning |
|---|---|
PACKS | Pack ids or directories; default all. |
--json | — |
--schema | Print pack.yaml's JSON Schema. |
agentfox policy packs new
Scaffold a pack from the template: pack.yaml, a policy, golden cases, a check.
agentfox policy packs new PACK_ID [OPTIONS]| Argument / option | Meaning |
|---|---|
PACK_ID required | The new pack's id, e.g. payments/chargebacks. |
--into path | Where to create it. The default is this project's packs directory. Default: .agentfox/packs. |
--builtin | Create it among the built-in packs (contributors). |
agentfox policy rules
Business rules in plain terms: apply, show, check, explain, suggest, graph.
agentfox policy rules COMMANDagentfox policy rules apply
Author or update a business rule from a YAML file.
agentfox policy rules apply FILE [OPTIONS]| Argument / option | Meaning |
|---|---|
FILE required | YAML ladder definition. |
--agent text | — |
--mode text | observe | enforce |
agentfox policy rules show
Show the resolved bands, so an author sees exactly what they wrote.
agentfox policy rules show [KEY]| Argument / option | Meaning |
|---|---|
KEY | Rule key; omit for all. |
agentfox policy rules check
Find where two teams' rules disagree. Two authors setting different thresholds on the same field is not a merge to be resolved by precedence — it is a disagreement between two people, and resolving it silently means one of them is wrong and does not know.
agentfox policy rules check [OPTIONS]| Argument / option | Meaning |
|---|---|
--json | — |
agentfox policy rules test
Try values against a rule without running anything.
agentfox policy rules test KEY VALUES| Argument / option | Meaning |
|---|---|
KEY required | Rule key. |
VALUES required | Comma-separated values to try. |
agentfox policy rules catalogue
Every kind of guardrail this product can enforce. The answer to "can we express our policy?" — asked before anyone writes YAML.
agentfox policy rules catalogue [OPTIONS]| Argument / option | Meaning |
|---|---|
--intent text | — |
--json | — |
agentfox policy rules explain
Parameters, inputs and a worked example for one guardrail kind.
agentfox policy rules explain KIND_ID| Argument / option | Meaning |
|---|---|
KIND_ID required | Guardrail kind id. |
agentfox policy rules suggest
Which guardrail kinds a written instruction probably needs. Deterministic signal matching, not a model — a starting point an operator confirms, so a wrong suggestion costs a glance rather than a silent misconfiguration.
agentfox policy rules suggest INSTRUCTION| Argument / option | Meaning |
|---|---|
INSTRUCTION required | A sentence from a policy document. |
agentfox policy rules graph
The decision path as it will actually run, stage by stage.
agentfox policy rules graphagentfox policy rules compile
Turn a written policy into executable guardrails.
agentfox policy rules compile FILE [OPTIONS]| Argument / option | Meaning |
|---|---|
FILE required | Policy document (.txt or .md). |
--apply | Save the compiled rules. |
--json | — |
agentfox policy proposals
Proposed changes to governance configuration: review, decide, apply, undo.
agentfox policy proposals COMMANDagentfox policy proposals list
List proposals, newest first.
agentfox policy proposals list [OPTIONS]| Argument / option | Meaning |
|---|---|
--status text | Filter by lifecycle status |
--kind text | Filter by change kind |
--scope text | org | team | agent | user |
--json | — |
agentfox policy proposals show
Show one proposal: its diff, evidence, proof and decisions.
agentfox policy proposals show PROPOSAL_ID [OPTIONS]| Argument / option | Meaning |
|---|---|
PROPOSAL_ID required | — |
--json | — |
agentfox policy proposals approve
Approve a proven proposal. An org-level loosening needs two different people.
agentfox policy proposals approve PROPOSAL_ID [OPTIONS]| Argument / option | Meaning |
|---|---|
PROPOSAL_ID required | — |
--actor text required | Your name or email — decisions are named |
--note text required | Why |
agentfox policy proposals reject
Reject a proposal.
agentfox policy proposals reject PROPOSAL_ID [OPTIONS]| Argument / option | Meaning |
|---|---|
PROPOSAL_ID required | — |
--actor text required | Your name or email — decisions are named |
--note text required | Why |
agentfox policy proposals apply
Apply an approved proposal (or settle one whose canary has finished).
agentfox policy proposals apply PROPOSAL_ID [OPTIONS]| Argument / option | Meaning |
|---|---|
PROPOSAL_ID required | — |
--actor text | Your name or email |
--automated | Apply as the improvement loop, subject to autonomy, freeze and daily cap |
agentfox policy proposals rollback
Undo an applied or canaried proposal.
agentfox policy proposals rollback PROPOSAL_ID [OPTIONS]| Argument / option | Meaning |
|---|---|
PROPOSAL_ID required | — |
--actor text required | Your name or email |
--reason text required | Why it is being undone |
agentfox policy proposals verify
Close the loop on an applied change: did it do what it promised? `--failed` rolls the change back. If undoing it would loosen a control, it stays applied with the failure recorded, because that rollback is a person's decision.
agentfox policy proposals verify PROPOSAL_ID [OPTIONS]| Argument / option | Meaning |
|---|---|
PROPOSAL_ID required | — |
--actor text required | Your name or email |
--note text required | What the evidence showed |
--failed | The change did not do what it promised: record it and roll back. |
agentfox policy proposals from-labels
File rule cut-off proposals from labelled false positives. Nothing is applied.
agentfox policy proposals from-labels [OPTIONS]| Argument / option | Meaning |
|---|---|
--days integer | Label window in days Default: 30. |
--json | — |
agentfox policy proposals from-traffic
Propose tool declarations and grants from what your agents have called. Learned permissions: observe, propose, approve. Reads every recorded tool call — refused ones included — and files a `tool.declare` for each undeclared tool and a `capability.grant` per agent and tool, with argument limits read off the calls and a provenance ceiling from benign calls only. A call a detector matched, or that was stopped for where its arguments came from and nobody approved, is never learned from. Nothing is applied: approve and apply each proposal.
agentfox policy proposals from-traffic [OPTIONS]| Argument / option | Meaning |
|---|---|
--agent text | Only this agent's calls (slug). |
--since text | Window: 7d, 24h, 30m or an ISO date. Default: the last 30 days. |
--json | — |
agentfox test
Prove the controls hold before you ship: score, gate, attack, and dry-run.
agentfox test COMMANDagentfox test run
Run an evaluation suite.
agentfox test run SUITE [OPTIONS]| Argument / option | Meaning |
|---|---|
SUITE required | — |
--provider text | — Default: echo. |
--model text | — Default: echo-1. |
--agent text | — |
--scorers text | Comma-separated scorer keys. |
agentfox test gate
Run the suite and fail the build on regression or on any errored case. Exits 1 on failure.
agentfox test gate SUITE [OPTIONS]| Argument / option | Meaning |
|---|---|
SUITE required | — |
--provider text | — Default: echo. |
--model text | — Default: echo-1. |
--baseline text | Baseline run id. |
--min-pass-rate float | — |
--agent text | Agent to fit the envelope for. Default: the baseline run's agent. |
--scorers text | Comma-separated scorer keys. Default: the baseline run's scorers. |
--junit path | Write JUnit XML here. |
--sarif path | Write SARIF here. |
agentfox test baseline
Mark a run as the regression baseline.
agentfox test baseline RUN_ID [OPTIONS]| Argument / option | Meaning |
|---|---|
RUN_ID required | — |
--label text | — Default: main. |
agentfox test suites
List the evaluation suites in this deployment.
agentfox test suitesagentfox test online
Sample production traffic and score it with the offline scorers.
agentfox test online AGENT [OPTIONS]| Argument / option | Meaning |
|---|---|
AGENT required | — |
--since-days integer | — Default: 7. |
--rate float | — |
agentfox test redteam
Run adversarial probes against the deployed configuration. This measures whether *this configuration* got weaker, against known attack classes. It is not a robustness certificate, and `--adaptive` does not make it one: every published result says an attacker who adapts eventually gets through. Exits 1 when any attack got through (unless --allow-escapes). Probes are simulated: their tool calls are evaluated without writing decisions, so they never show up in findings or in what `policy simulate` replays. The campaign itself, and a finding naming the attacks that got through, are recorded.
agentfox test redteam AGENT [OPTIONS]| Argument / option | Meaning |
|---|---|
AGENT required | — |
--probes text | — |
--adaptive | Mutate a blocked probe and try again, steering from the failure. Reports a posture delta against the last comparable campaign, not a pass rate. |
--budget integer | Attempts per probe in adaptive mode. Default: 3. |
--seed integer | Fixes the mutation program. Default: 1337. |
--deployment-probes, --no-deployment-probes | Adaptive mode only: also generate probes from this deployment's own grants, impacts and bound policies (on by default with --adaptive). The static suite always runs the built-in probes alone. |
--allow-escapes | Exit 0 even when an attack got through. By default an escaped attack exits 1, so the command can gate CI. |
agentfox test probes
List the probe suite (built in, and from capability packs) and the wrapped runners.
agentfox test probesagentfox test action
Read an artefact and say what running it would actually do. Deterministic, offline and immediate: no database, no model, no network. The point is that an engineer can check a generated statement before it is ever executed.
agentfox test action STATEMENT [OPTIONS]| Argument / option | Meaning |
|---|---|
STATEMENT required | SQL, shell command or URL to analyse |
--kind text | sql | shell | http Default: sql. |
--method text | HTTP method, when kind=http Default: GET. |
--dialect text | SQL dialect Default: postgres. |
--environment text | environment the action binds to Default: production. |
agentfox test boundary
Would this question be refused, and what would we say instead? Changes nothing, so it is safe to replay real traffic through before enforcing — which matters more here than anywhere else, because the false positives of this control are refusals shown to customers.
agentfox test boundary AGENT QUESTION| Argument / option | Meaning |
|---|---|
AGENT required | Agent slug. |
QUESTION required | A question to test. |
agentfox test rule
Try values against a rule without running anything.
agentfox test rule KEY VALUES| Argument / option | Meaning |
|---|---|
KEY required | Rule key. |
VALUES required | Comma-separated values to try. |
agentfox report
What you can show an auditor: posture, evidence, risk, sign-off. Bare `agentfox report` prints the summary; the subcommands go deeper.
agentfox report [COMMAND]Run with no subcommand, it does report summary.
agentfox report summary
A one-page summary of what your agents did and what was contained.
agentfox report summary [OPTIONS]| Argument / option | Meaning |
|---|---|
--agent, -a text | Only this agent. Repeat for several. Default: all. Repeatable. |
--since text | How far back: 24h, 7d, 2w, 30d. Default: 7d. |
--format, -f text | md or html. Default: md. |
--out, -o path | Write to this file instead of printing. |
agentfox report status
Show control posture, optionally for one framework.
agentfox report status [OPTIONS]| Argument / option | Meaning |
|---|---|
--framework text | — |
--verbose, --no-verbose | — |
agentfox report evidence
Build an auditor-ready evidence package.
agentfox report evidence [OPTIONS]| Argument / option | Meaning |
|---|---|
--agent text | Repeatable; default all. Repeatable. |
--from text | Start of the period, YYYY-MM-DD or ISO-8601. Default: --since-days. |
--to text | End of the period, inclusive of a whole day given as YYYY-MM-DD. |
--since-days integer | — Default: 30. |
--control text | Repeatable; default all. Repeatable. |
--requested-by text | — Default: cli. |
agentfox report verify
Verify the tamper-evident audit chain. Exits 1 if broken.
agentfox report verify [OPTIONS]| Argument / option | Meaning |
|---|---|
--start integer | — |
--end integer | — |
agentfox report risk
Show the agent risk register.
agentfox report riskagentfox report obligations
Regulatory obligation calendar against the agent inventory.
agentfox report obligationsagentfox report frameworks
List frameworks, coverage and review status.
agentfox report frameworksagentfox report board
Executive risk view.
agentfox report boardagentfox report review-packet
Everything a qualified reviewer needs to sign off one framework, in one file. Every mapping ships `DRAFT — UNVERIFIED / NOT LEGAL ADVICE` until a named human reviews it, and that is the loudest "not ready" signal in an audit conversation. The blocker has never been the workflow, it has been that nobody could hand a reviewer a reviewable artefact. This is that artefact: the control, what implements it, what evidence it produces, and the exact clause claimed — one row per decision the reviewer has to make.
agentfox report review-packet [OPTIONS]| Argument / option | Meaning |
|---|---|
--framework text required | Framework key, e.g. eu-ai-act. |
--out path | Write markdown here instead of stdout. |
agentfox report signoff
Record a qualified reviewer's sign-off on a control's framework mapping(s). This is an attestation by a named person, recorded and auditable. It is the step that moves a mapping from `DRAFT — UNVERIFIED / NOT LEGAL ADVICE` to reviewed, and it should be run by whoever is actually accountable for the claim — not by whoever runs the CLI.
agentfox report signoff CONTROL [OPTIONS]| Argument / option | Meaning |
|---|---|
CONTROL required | — |
--framework text required | — |
--reviewer text required | The human accountable for this sign-off. |
--reference text | Sign off one clause only; default is every clause for the control. |
agentfox report entitlement
How much more the agent can reach than its callers are entitled to. Worth running before any entitlement model exists — a ratio of 1.0 with no grants configured is exactly the point.
agentfox report entitlement [OPTIONS]| Argument / option | Meaning |
|---|---|
--days integer | — Default: 7. |
agentfox report escalations
Which conversations qualified for a human and never got one. The largest single failure family at 31%, and invisible from inside the system: a conversation where the agent kept going instead of handing off looks entirely ordinary in the telemetry.
agentfox report escalations [OPTIONS]| Argument / option | Meaning |
|---|---|
--hours integer | — Default: 24. |
--apply | Raise findings and retroactive hand-offs. |
agentfox report drift
Compare recent production scores against the baseline window.
agentfox report drift AGENT [OPTIONS]| Argument / option | Meaning |
|---|---|
AGENT required | — |
--scorer text | — Default: groundedness. |
agentfox doctor
Is the runtime configured the way you think it is? Reports only — it changes nothing. Every line is a fact about this deployment, and each one names the consequence rather than the setting, because "fail_mode=open" means nothing to someone who has not read the PRD.
agentfox doctor [OPTIONS]| Argument / option | Meaning |
|---|---|
--json | One record per check, for CI. Exits non-zero on a failed check either way. |
agentfox admin
Run the deployment: operators, tokens, schema, scheduled jobs, key rotation, catalog upkeep, hooks, seed data.
agentfox admin COMMANDagentfox admin checkpoint
Write a signed checkpoint over the current chain head.
agentfox admin checkpointagentfox admin seed
Load a demonstrable environment: three agents, policies, controls and an eval suite. It records no traffic; `agentfox demo` sends sample requests through the seeded agents, which is what fills traces, decisions and findings.
agentfox admin seed [OPTIONS]| Argument / option | Meaning |
|---|---|
--show-keys | Print newly issued agent API keys in full. Keys are shown only once, when first issued; this flag is the only way to see them. |
agentfox admin version
Show the version of everything that takes part in a decision.
agentfox admin versionagentfox admin auth
Operator tokens and authentication mode.
agentfox admin auth COMMANDagentfox admin auth issue
Mint an API token. The value is shown once and cannot be retrieved again.
agentfox admin auth issue EMAIL [OPTIONS]| Argument / option | Meaning |
|---|---|
EMAIL required | Operator the token acts as. |
--name, -n text | What this token is for. |
--days integer | Lifetime; 0 for no expiry. Default: 365. |
agentfox admin auth tokens
List tokens. Never shows a secret — there is nothing stored that could.
agentfox admin auth tokens [OPTIONS]| Argument / option | Meaning |
|---|---|
--json | — |
agentfox admin auth revoke
Revoke a token immediately.
agentfox admin auth revoke TOKEN_ID| Argument / option | Meaning |
|---|---|
TOKEN_ID required | Token id from `agentfox admin auth tokens`. |
agentfox admin auth status
How this deployment authenticates, and whether that is what you intended.
agentfox admin auth statusagentfox admin users
Operators: create the first one on a fresh install, list them.
agentfox admin users COMMANDagentfox admin users create
Create an operator — the first one on a fresh self-hosted install, with no demo data. Then `agentfox admin auth issue EMAIL` mints their API token (or pass --token).
agentfox admin users create EMAIL [OPTIONS]| Argument / option | Meaning |
|---|---|
EMAIL required | The operator's email; what `auth issue` takes. |
--role, -r text | owner | admin | security | compliance | developer | auditor. Default: owner. |
--name, -n text | Display name. |
--org text | Tenant to create them in. Default: this deployment's AGENTFOX_ORG_ID. |
--token | Also issue an API token for them now, shown once. |
agentfox admin users list
List operators in every tenant on this database.
agentfox admin users list [OPTIONS]| Argument / option | Meaning |
|---|---|
--json | — |
agentfox admin db
Apply, roll back and inspect the database schema.
agentfox admin db COMMANDagentfox admin db upgrade
Apply migrations. This is how a deployed instance is upgraded.
agentfox admin db upgrade [OPTIONS]| Argument / option | Meaning |
|---|---|
--revision text | — Default: head. |
agentfox admin db downgrade
Roll back migrations. Every migration ships with a tested downgrade.
agentfox admin db downgrade REVISION| Argument / option | Meaning |
|---|---|
REVISION required | Target revision, or 'base'. |
agentfox admin db current
Show the applied schema revision.
agentfox admin db currentagentfox admin catalog
Keep the control catalog and its computed status current.
agentfox admin catalog COMMANDagentfox admin catalog sync
Load the control catalog and obligation calendar from YAML.
agentfox admin catalog syncagentfox admin catalog compute
Recompute control status from telemetry.
agentfox admin catalog compute [OPTIONS]| Argument / option | Meaning |
|---|---|
--window-days integer | — Default: 30. |
agentfox admin catalog validate
Check the control catalog and obligation calendar are internally consistent. Read-only and offline: parses the compliance packs' controls.yaml and obligations.yaml (or those under `compliance_dir`, when it is set) and never touches the database. Exits 1 on any problem, so it can gate a catalog change the way `policy lint` gates a policy.
agentfox admin catalog validateagentfox admin hooks
Run AgentFox where the agent already is: a warm daemon and a thin per-call hook.
agentfox admin hooks COMMANDagentfox admin hooks daemon
Run the warm process a hook talks to. A harness spawns its hook as a fresh process per tool call, and importing AgentFox costs seconds — measured here at 3.9s on the first call against a cold daemon, then 6ms once warm. That gap is the whole reason this exists: a hook that costs two seconds a call is a hook the operator removes.
agentfox admin hooks daemon [OPTIONS]| Argument / option | Meaning |
|---|---|
--socket path | Override the socket path. |
agentfox admin hooks run
The per-call hook. Reads the harness payload on stdin, writes its reply. Everything in this path runs in a process the harness creates and destroys per tool call, so it does the least possible: parse, ask the daemon, print. Measured against a warm daemon, the round trip is about 6ms; the same work without one is 3.9 seconds, because `import agentfox` is.
agentfox admin hooks run [OPTIONS]| Argument / option | Meaning |
|---|---|
--harness text required | Which harness is calling. |
--agent text | Agent slug to govern this session as. |
agentfox admin hooks install
Show, or write, the hook configuration for a harness. Dry by default. This edits a file that decides whether the operator's agent runs at all, so it prints what it would do and waits to be told twice. With --write it also sets up a working baseline: the agent is registered (development unless --env says otherwise), the harness's built-in tools are declared with their real impact and granted to it, and the coding-agent pack is bound to it in observe. Destructive commands are still refused.
agentfox admin hooks install [OPTIONS]| Argument / option | Meaning |
|---|---|
--harness text | Which harness to install for. Default: the only one registered. |
--agent text required | Agent slug these calls are governed as. |
--path path | Project to install into. Default: .. |
--write | Actually write the settings file. |
--env text | Environment the agent runs in. Default: development for a new agent; an agent already registered keeps its own. |
--grant, --no-grant | Grant the harness's built-in tools to the agent (the default), so ordinary work is not refused by default-deny. Default: true. |
agentfox admin hooks status
Is the daemon up, and does a deny on this harness actually stop anything?
agentfox admin hooks statusagentfox admin jobs
Run scheduled work: monitors, drift, compliance, canaries.
agentfox admin jobs COMMANDagentfox admin jobs run-due
One pass of the job runner: enqueue due schedules, recover stuck jobs, run them. Put this on a scheduler (cron, a systemd timer, a Kubernetes CronJob) every 10-30 minutes on a self-hosted deployment. Safe to run as often as you like.
agentfox admin jobs run-due [OPTIONS]| Argument / option | Meaning |
|---|---|
--limit integer | Most jobs to run in this pass. Default: 50. |
--json | Print JSON. |
agentfox admin keys
Rotate the token encryption and audit signing keys.
agentfox admin keys COMMANDagentfox admin keys status
Fingerprints in use, and whether any data or checkpoint still needs a previous key.
agentfox admin keys status [OPTIONS]| Argument / option | Meaning |
|---|---|
--json | Print JSON. |
agentfox admin keys rotate
Re-encrypt stored secrets and re-sign audit checkpoints under the current keys. Values no configured key decrypts are reported and left untouched. A chain that fails verification is reported and not re-signed. Safe to run repeatedly.
agentfox admin keys rotate [OPTIONS]| Argument / option | Meaning |
|---|---|
--dry-run | Report only; change nothing. |
--json | Print JSON. |
agentfox admin mcp
Inspect the MCP server. To run it: `agentfox serve mcp`.
agentfox admin mcp COMMANDagentfox admin mcp tools
List the tools an MCP client gets, with a one-line description of each.
agentfox admin mcp tools