CLI reference

Every secfoo command, grouped the way the CLI itself groups them. Options in brackets are optional; ... marks a repeatable flag.

Core

secfoo run

Run one or more security skills against a target using the chosen agent. Multiple --skill flags run concurrently, not one after another.

If --assessment is omitted, a case file is created automatically for you — no separate secfoo assessment create step needed for the common case. On a real terminal, you'll be prompted for a project name and application ID (skip either by passing --project-name/--app-id directly, or leave both unset for a non-interactive run, e.g. in CI). A repeat run against the same target with the same --app-id attaches to that same assessment instead of creating a new one each time, so history accumulates in one case file across rescans.

secfoo run --skill <id>... [--target] [--confluence...] [--agent] [--depth] [--timeout] [--assessment] [--project-name] [--app-id] [--exclude...]

--skill, -sSecurity skill to run. Repeatable — required.

--target, -tGitHub URL or local directory. Defaults to the current directory.

--confluence, -cConfluence page URL for extra context. Repeatable.

--agent, -aclaude | agent (Cursor) | agy (Antigravity) | gemini. Falls back to config, then claude.

--depth, -dquick (fast triage) or standard (full checklist). Falls back to config, then quick.

--timeoutPer-skill timeout in seconds.

--assessmentAttach this run to an existing assessment case file. Skips auto-creation and the --project-name/--app-id prompt entirely.

--project-nameFriendly name for the project, shown across the dashboard instead of the raw URL/path. Only used when --assessment is omitted.

--app-idApplication ID recorded on the auto-created (or reused) assessment — e.g. from your CMDB/asset inventory. Only used when --assessment is omitted.

--exclude, -xPath to exclude from the scan. Repeatable, additive on top of config.

secfoo list

List past assessment runs.

secfoo list [--project] [--limit] [--status]

--project, -pFilter by project name/URL substring.

--limitMaximum runs to show. Default 50.

--statusFilter by run status.

secfoo show <run-uuid>

Show a single assessment run's report.

secfoo show <run-uuid> [--json]

--jsonPrint the run record as JSON instead of the report.

secfoo serve

Launch the local web dashboard.

secfoo serve [--host] [--port]

--hostDefault 127.0.0.1.

--portDefault 8787.

secfoo agents

List known agent adapters and whether their CLI is installed on this machine. No options.

secfoo agents

assessment case files

An assessment is a case-file container — an Application ID / Security Assessment Request, a review status, and one or more attached runs or uploaded files.

secfoo assessment create

Create a new assessment case file that runs and file attachments can attach to.

secfoo assessment create --type <internal|third-party> [--project] [--name] [--status] [--app-id] [--sar] [--reviewer] [--review-date] [--notes]

--project, -pGitHub repo URL or local directory. Defaults to the current directory.

--nameFriendly project name. Defaults to the name derived from --project.

--typeinternal or third-party. Required.

--statusready | in_progress | completed | blocked. Default ready.

--app-idApplication ID.

--sarSecurity Assessment Request number.

--reviewerReviewer name.

--review-dateReview date.

--notesFree-text notes.

secfoo assessment list

List assessment case files.

secfoo assessment list [--type] [--status] [--search]

secfoo assessment show <id>

Show a single assessment's details, attachments, and attached runs.

secfoo assessment show <assessment-id>

secfoo assessment update <id>

Update fields on an existing assessment.

secfoo assessment update <assessment-id> [--status] [--app-id] [--sar] [--reviewer] [--review-date] [--notes]

secfoo assessment upload <id> <file>

Attach a file to an assessment. AI-BOM files (name containing "ai-bom", .json or .csv) are parsed immediately into a model/tool inventory.

secfoo assessment upload <assessment-id> ai-bom.json

secfoo assessment delete <id>

Delete an assessment. Attached runs are detached, not deleted; attachments are removed.

secfoo assessment delete <assessment-id>

exception risk acceptance

A risk acceptance against a project, with an expiry the dashboard tracks in 30/60/90-day buckets.

secfoo exception create

Grant a risk acceptance / waiver against a project.

secfoo exception create --title --justification --granted-by --expires-at [--project] [--control] [--assessment]

--titleShort description of what's being accepted. Required.

--justificationWhy this risk is being accepted. Required.

--granted-byWho approved this exception. Required.

--expires-atExpiry date, YYYY-MM-DD. Required.

--controlCCM domain code or standard clause, e.g. IAM or "SOC 2 CC6.1".

--assessmentOptionally scope to one assessment.

secfoo exception list

List exceptions, soonest-expiring first.

secfoo exception list [--status]

secfoo exception show <id>

Show a single exception's details.

secfoo exception show <exception-id>

secfoo exception update <id>

Update an exception — e.g. revoke it, or extend its expiry.

secfoo exception update <exception-id> [--status] [--expires-at] [--justification]

secfoo exception delete <id>

Delete an exception record.

secfoo exception delete <exception-id>

miss post-build findings

A threat an earlier model missed — recorded by hand, since nothing in a report can know what it missed.

secfoo miss create

Record a threat found after build that an earlier threat model missed.

secfoo miss create --title --discovered-at [--project] [--description] [--discovered-by] [--run]

--titleWhat was found. Required.

--discovered-atWhen it was found, YYYY-MM-DD. Required.

--descriptionFree-text description.

--discovered-byWho/what found it — incident, pen test, …

--runRun UUID of the threat model that should have caught this, if known.

secfoo miss list

List threats found post-build, most recent first.

secfoo miss list

secfoo miss show <id>

Show a single post-build finding's details.

secfoo miss show <finding-id>

secfoo miss delete <id>

Delete a post-build finding record.

secfoo miss delete <finding-id>

accept threat acceptance

The human loop-back for accepting one threat from a Threat Register — a named owner and justification, tracked independently of the model's own Disposition call.

secfoo accept create

Record a human risk acceptance for one threat from a Threat Register.

secfoo accept create --threat-id --title --justification --accepted-by [--project] [--expires-at] [--run]

--threat-idThe Threat Register row ID from the report, e.g. T4. Required.

--titleShort description of the threat being accepted. Required.

--justificationWhy this risk is being accepted. Required.

--accepted-byWho is accepting this risk. Required.

--expires-atOptional review-by date, YYYY-MM-DD.

--runRun UUID this threat came from, if known.

secfoo accept list

List recorded threat acceptances, most recent first.

secfoo accept list [--status]

secfoo accept show <id>

Show a single threat acceptance's details.

secfoo accept show <acceptance-id>

secfoo accept update <id>

Update a threat acceptance — e.g. revoke it, or extend its review date.

secfoo accept update <acceptance-id> [--status] [--expires-at] [--justification]

secfoo accept delete <id>

Delete a threat acceptance record.

secfoo accept delete <acceptance-id>

cloud enterprise portal

Connect this machine to the secfoo enterprise portal. Every future successful secfoo run is pushed automatically — nothing local changes, and secfoo serve keeps working exactly as before.

secfoo cloud login

Connect this machine to the secfoo enterprise portal.

secfoo cloud login --api-key <key> [--portal-url]

--api-keyIngest-scoped key from your enterprise portal admin. Required.

--portal-urlOverride if your org uses a non-default portal.

secfoo cloud logout

Disconnect this machine from the enterprise portal.

secfoo cloud logout

secfoo cloud status

Show portal connection status and how many local runs are unsynced.

secfoo cloud status

secfoo cloud sync

Push any local runs not yet synced to the portal.

secfoo cloud sync

vendor optional assets

secfoo vendor mermaid

Download Mermaid so architecture diagrams render in the dashboard. Not bundled by default — ~3.5MB, fetched once and served locally afterwards.

secfoo vendor mermaid [--url] [--force]

--urlWhere to fetch the bundle from.

--forceRe-download even if already present.

config ~/.secfoo/config.toml

secfoo config init

Write a starter config.toml (defaults + an MCP server example).

secfoo config init [--force]

--forceOverwrite an existing config.toml.

mcp agent integration

secfoo mcp list

Show MCP servers configured in ~/.secfoo/config.toml.

secfoo mcp list

secfoo mcp sync

Register configured MCP servers persistently into gemini's or Cursor's own config. claude doesn't need this — it picks up config.toml automatically on every run. agy isn't supported yet.

secfoo mcp sync --agent <agent>

--agent, -aWhich agent's MCP config to update. Required.