Complete Command Reference

Global Options

Option	Description
`--json`	JSON output mode for scripting and AI agents
`--version`, `-V`	Show version and exit
`--help`	Show command help

Root Commands

Command	Description
`pretorin login`	Authenticate with the Pretorin API (`--api-key/-k`, `--api-url`)
`pretorin logout`	Clear stored credentials
`pretorin whoami`	Display authentication status
`pretorin version`	Show CLI version, runtime kind, and resolved executable path
`pretorin link`	Pin the canonical MCP path `~/.pretorin/bin/pretorin` at this executable so host config survives reinstalls/upgrades (`--force`)
`pretorin update [VERSION]`	Update to latest version, or a specific version
`pretorin mcp-serve`	Start the MCP server (stdio transport)
`pretorin mcp-smoke-test`	Smoke-test the cross-harness MCP tool surface (`check_context`, `list_tools`, `get_instructions`, `get_workflow` schema bundling); exits 1 on failure

Framework Commands

Command	Description
`pretorin frameworks list`	List all frameworks
`pretorin frameworks get <id>`	Get framework details
`pretorin frameworks families <id>`	List control families
`pretorin frameworks family <fw> <family>`	Get control family details
`pretorin frameworks controls <id> [FAMILY_ID]`	List controls (`--family/-f`, `--limit/-n`)
`pretorin frameworks control <fw> <ctrl>`	Get control details (`--brief/-b`)
`pretorin frameworks metadata <id>`	Get per-control framework metadata
`pretorin frameworks submit-artifact <file>`	Submit a compliance artifact JSON file

Custom Frameworks

Subcommands of pretorin frameworks for authoring, validating, and uploading custom or forked frameworks. See Custom Frameworks for the full authoring workflow.

Command	Description
`pretorin frameworks init-custom <framework_id>`	Scaffold a minimal valid `unified.json` (`--title/-t`, `--output/-o`, `--force/-f`)
`pretorin frameworks validate-custom <file>`	Validate a `unified.json` artifact against the bundled JSON Schema
`pretorin frameworks build-custom <input>`	Normalize a source catalog (unified, OSCAL, or known custom) into uploadable `unified.json` (`--framework-id/-f` required, `--output/-o`, `--force`)
`pretorin frameworks upload-custom <file>`	Upload a `unified.json` artifact as a draft revision (`--framework-id/-f`, `--version-label/-v`, `--publish`)
`pretorin frameworks fork-framework <source_id> <new_id>`	Create a linked-fork draft from an upstream framework (`--version-label/-v`)
`pretorin frameworks rebase-fork <framework_id>`	Create a rebase draft for a fork against the latest upstream revision (`--version-label/-v`)
`pretorin frameworks revisions <framework_id>`	List all draft and published revisions for a framework
`pretorin frameworks export-oscal <file>`	Regenerate an OSCAL catalog from a `unified.json` artifact (`--output/-o`, `--force`)

Context Commands

Command	Description
`pretorin context list`	List systems and frameworks with progress
`pretorin context set`	Set active system/framework context (`--system/-s`, `--framework/-f`, `--no-verify`)
`pretorin context show`	Display and validate current active context (`--quiet/-q`, `--check`)
`pretorin context clear`	Clear active context
`pretorin context verify`	Verify active context with source attestation (`--ttl`, `--quiet/-q`)
`pretorin context manifest`	Show resolved source manifest and evaluate against detected sources (`--quiet/-q`)

Control Commands

Command	Description
`pretorin control status <ctrl> <status>`	Start/reopen control authoring; `status` must be `in_progress` (`--framework-id/-f`, `--system/-s`)
`pretorin control context <ctrl>`	Get rich control context with AI guidance (`--framework-id/-f`, `--system/-s`)

Evidence Commands

Command	Description
`pretorin evidence create <ctrl> <fw>`	Create a local evidence file (`--name/-n`, `--description/-d`, `--artifact-content`, `--type/-t`)
`pretorin evidence format-markdown [file]`	Convert Markdown headings to report-safe bold section labels (`--write`, `--check`)
`pretorin evidence list`	List local evidence files (`--framework/-f`)
`pretorin evidence push`	Push local evidence to the platform (`--dry-run`)
`pretorin evidence search`	Search platform evidence (`--control-id/-c`, `--framework-id/-f`, `--system/-s`, `--query/-q`, `--include-attached/--no-attached`, `--include-unattached/--no-unattached`, `--min-similarity`, `--limit/-n`)
`pretorin evidence upsert <ctrl> <fw>`	Find-or-create evidence and link it (`--name/-n`, `--description/-d`, `--artifact-content`, `--type/-t`, `--system/-s`, `--code-file`, `--code-lines`, `--code-repo`, `--code-commit`, `--coverage-start`, `--coverage-end`, `--capture-query`, `--source-uri`, `--source-label`, `--source-locator`, `--source-excerpt`, `--capture-method`, `--cadence-days`)
`pretorin evidence upload <file> <ctrl> <fw>`	Upload a file as evidence (`--name/-n`, `--type/-t`, `--description/-d`, `--system/-s`)
`pretorin evidence link <evidence_id> <ctrl>`	Link evidence to a control (`--framework-id/-f`, `--system/-s`)
`pretorin evidence link-cci <evidence_id> <cci_implementation_id>`	Link evidence to a per-system CCI implementation row (`--system/-s`, `--override-system-mismatch`, `--override-reason`)
`pretorin evidence link-stig <evidence_id> <stig_rule_id>`	Link evidence to a STIG rule workflow (lazy-creates the row) (`--system/-s`, `--override-system-mismatch`, `--override-reason`)
`pretorin evidence mark-current <evidence_id>`	Re-affirm evidence freshness; bumps `expires_at` by the refresh cadence and resolves any expiring/expired monitoring events (`--system/-s`)
`pretorin evidence validate <evidence_id>`	Compare recorded source-material hash before re-verifying or replacing a drifted Markdown artifact (`--system/-s`, `--source-root`, `--artifact-content`/`--artifact`, `--description/-d`, `--drift-note`)
`pretorin evidence delete <evidence_id>`	Delete an evidence item (`--system/-s`, `--framework-id/-f`, `--yes/-y`)

Evidence Attestation

Subcommands of pretorin evidence attestation for fetching and verifying DSSE attestation envelopes per ADR 0003.

Command	Description
`pretorin evidence attestation get <evidence_id>`	Fetch the latest DSSE envelope for an evidence record (`--lineage`, `--include-archived`); pair with `--json` to pipe into `cosign verify-blob-attestation`
`pretorin evidence attestation verify <evidence_id>`	Verify the DSSE signature against the deployment’s signing-key registry (`--env`, `--key-fingerprint`)

Narrative Commands

Command	Description
`pretorin narrative create <ctrl> <fw>`	Create a local narrative file (`--content/-c`, `--name/-n`, `--ai-generated`)
`pretorin narrative list`	List local narrative files (`--framework/-f`)
`pretorin narrative push`	Push local narratives to the platform (`--dry-run`)
`pretorin narrative push-file <ctrl> <fw> <sys> <file>`	Push a single narrative file to the platform
`pretorin narrative get <ctrl> <fw>`	Get current control narrative (`--system/-s`)

Issues Commands

Command	Description
`pretorin issues create <ctrl> <fw>`	Create a local issue file (`--content/-c`, `--name/-n`)
`pretorin issues list [ctrl] [fw]`	List issues — platform (`--system/-s`) or local (`--local`, `--framework/-f`)
`pretorin issues push`	Push local issues to the platform (`--dry-run`)
`pretorin issues add <ctrl> <fw>`	Add an issue directly on the platform (`--content/-c`, `--system/-s`)
`pretorin issues resolve <ctrl> <fw> <issue_id>`	Resolve or reopen a control issue (`--system/-s`, `--resolution-note/--justification`, `--reopen`, `--content/-c`, `--pinned`)

Notes Commands (Deprecated alias of `issues`)

The notes command group is a deprecated alias for issues; use issues for new workflows. The commands accept the same arguments and call the same platform APIs.

Command	Description
`pretorin notes create <ctrl> <fw>`	Create a local note file (`--content/-c`, `--name/-n`)
`pretorin notes list [ctrl] [fw]`	List notes — platform (`--system/-s`) or local (`--local`, `--framework/-f`)
`pretorin notes push`	Push local notes to the platform (`--dry-run`)
`pretorin notes add <ctrl> <fw>`	Add a note directly on the platform (`--content/-c`, `--system/-s`)
`pretorin notes resolve <ctrl> <fw> <note_id>`	Resolve or reopen a control note (`--system/-s`, `--resolution-note/--justification`, `--reopen`, `--content/-c`, `--pinned`)

Monitoring Commands

Command	Description
`pretorin monitoring push`	Push a monitoring event (`--system/-s`, `--framework/-f`, `--title/-t`, `--event-type`, `--severity`, `--control/-c`, `--description/-d`, `--update-control-status`)

Policy Commands

Command	Description
`pretorin policy list`	List org policies available for questionnaire work
`pretorin policy show`	Show persisted policy questionnaire state (`--policy`)
`pretorin policy populate`	Draft policy questionnaire updates from the current workspace (`--policy`, `--path/-p`, `--apply`)

Scope Commands

Command	Description
`pretorin scope show`	Show scope questionnaire state and review findings (`--system/-s`, `--framework-id/-f`)
`pretorin scope populate`	Draft scope questionnaire updates from the current workspace (`--system/-s`, `--framework-id/-f`, `--path/-p`, `--apply`)

Subcommands of pretorin scope artifacts for managing the auditor-required system_spec artifacts (asset inventory + 4 snapshot kinds). The inventory group wraps the recipe-driven scan flow and posts a classified diff (added / modified / decommissioned) against the platform inventory.

Command	Description
`pretorin scope artifacts list`	List the 5 system_spec artifact kinds with required/toggle/attest state (`--system/-s`)
`pretorin scope artifacts toggle <kind>`	Toggle an artifact kind required/optional; rationale required on toggle-off (`--system/-s`, `--optional/--required`, `--rationale/-r`)
`pretorin scope artifacts inventory show`	Show the current (or historical) asset inventory (`--system/-s`, `--as-of`)
`pretorin scope artifacts inventory upload <csv>`	Parse a CSV client-side, classify rows, and post a single inventory diff (`--system/-s`, `--yes/-y`)
`pretorin scope artifacts inventory scan <source>`	Run a recipe-driven scan (`aws`, `azure`, `k8s`, `iac-workspace`) and post the resulting diff (`--system/-s`, `--yes/-y`, `--dry-run`)

Agent Commands

Command	Description
`pretorin agent run "<task>"`	Run a compliance task (`--skill/-s`, `--model/-m`, `--base-url`, `--working-dir/-w`, `--no-stream`, `--legacy`, `--max-turns`, `--no-mcp`)
`pretorin agent doctor`	Validate Codex runtime setup
`pretorin agent install`	Download the pinned Codex binary
`pretorin agent version`	Show pinned Codex version and install status
`pretorin agent skills`	List available agent skills
`pretorin agent mcp-list`	List configured MCP servers for the agent
`pretorin agent mcp-add <name> <transport> <cmd>`	Add an MCP server configuration (`--arg/-a`, `--scope`)
`pretorin agent mcp-remove <name>`	Remove an MCP server configuration

Plan Commands

Operator-facing view onto the agent-authored work plans persisted locally under ~/.pretorin/plans/. Plans move through active → completed/cancelled.

Command	Description
`pretorin plan list`	List recent plans, newest first (`--state/-s` active\|completed\|cancelled, `--workflow/-w`, `--system`, `--framework`, `--control`, `--limit/-n`)
`pretorin plan show <plan_id>`	Show a single plan’s full details; `plan_id` accepts a full UUID or unique prefix
`pretorin plan cancel <plan_id>`	Cancel an active plan; refuses already-completed plans, no-op on already-cancelled (`--reason/-r`, `--yes/-y`)
`pretorin plan prune`	Remove old terminal (completed/cancelled) plans; active plans never removed (`--older-than-days/-d` default 30, `--dry-run/-n`, `--include-corrupt`, `--yes/-y`)

Skill Commands

Command	Description
`pretorin skill install`	Install the Pretorin skill for AI coding agents (`--agent/-a`, `--path/-p`, `--force/-f`)
`pretorin skill uninstall`	Uninstall the Pretorin skill (`--agent/-a`, `--path/-p`)
`pretorin skill status`	Show installation status of the Pretorin skill
`pretorin skill list-agents`	List all known agents and their skill directories

Review Commands

Command	Description
`pretorin review run`	Review code against a control (`--control-id/-c`, `--framework-id/-f`, `--system/-s`, `--path/-p`, `--local`, `--output-dir/-o`)
`pretorin review status`	Check implementation status for a control (`--control-id/-c`, `--framework-id/-f`, `--system/-s`)

Config Commands

Command	Description
`pretorin config list`	List all configuration
`pretorin config get <key>`	Get a config value
`pretorin config set <key> <value>`	Set a config value
`pretorin config path`	Show config file path

Campaign Commands

Command	Description
`pretorin campaign controls`	Run bulk control narrative/evidence campaign (`--system`, `--framework-id`, `--mode`, `--family`, `--controls`, `--all-controls`, `--all-open-issues`, `--issue-source`, `--issue-control`, `--issue-family`, `--include-resolved`, `--artifacts`, `--review-job`, `--concurrency`, `--max-retries`, `--checkpoint`, `--apply`, `--output`)
`pretorin campaign policy`	Run bulk policy questionnaire campaign (`--mode`, `--policies`, `--all-incomplete`, `--system`, `--concurrency`, `--max-retries`, `--checkpoint`, `--apply`, `--output`)
`pretorin campaign scope`	Run bulk scope questionnaire campaign (`--system`, `--framework-id`, `--mode`, `--concurrency`, `--max-retries`, `--checkpoint`, `--apply`, `--output`)
`pretorin campaign status`	Show campaign progress from a checkpoint file (`--checkpoint`, `--output`)

Campaign Modes

Domain	Mode	Description
controls	`initial`	Draft new narratives and evidence for controls
controls	`issues-fix`	Address platform issues on existing controls
controls	`notes-fix`	Deprecated alias for `issues-fix`
controls	`review-fix`	Fix findings from a family review job
policy	`answer`	Generate answers for policy questions
policy	`review-fix`	Fix findings from a policy review
scope	`answer`	Generate answers for scope questions
scope	`review-fix`	Fix findings from a scope review

Vendor Commands

Command	Description
`pretorin vendor list`	List all vendors in the organization (`--search`, `--type/-t`, `--risk-tier`, `--owner-user-id`, `--assessment-status`, `--sort-by`, `--sort-dir`)
`pretorin vendor create <name>`	Create a vendor (`--type/-t`, `--description/-d`, `--authorization-level/-a`, `--owner-user-id`, `--inherent-risk`)
`pretorin vendor get <vendor_id>`	Get vendor details
`pretorin vendor update <vendor_id>`	Update vendor fields (`--name`, `--description/-d`, `--type/-t`, `--authorization-level/-a`, `--owner-user-id`, `--inherent-risk`)
`pretorin vendor delete <vendor_id>`	Delete a vendor (`--force/-f`)
`pretorin vendor history <vendor_id>`	Show vendor audit and evidence history (`--limit`)
`pretorin vendor upload-doc <vendor_id> <file>`	Upload a vendor evidence document (`--name/-n`, `--description/-d`, `--attestation-type`)
`pretorin vendor list-docs <vendor_id>`	List documents linked to a vendor

Vendor Types

csp, saas, managed_service, internal

Vendor Risk Bands

low, moderate, high, critical. medium is a deprecated input alias for moderate.

Risk Commands

Manage a system’s risk register. Risks are system-scoped except for the org-level risk library subgroup. See Risk Management for the full workflow.

Command	Description
`pretorin risk list <system_id>`	List risks for a system (`--category`, `--risk-level`, `--status`)
`pretorin risk show <system_id> <risk_id>`	Show full risk including eager-loaded artifact links
`pretorin risk create <system_id>`	Create a custom risk (`--title`, `--category`, `--description/-d`, `--cia-category`, `--likelihood`, `--impact`, `--owner-id`, `--treatment`, `--treatment-plan`, `--treatment-due-date`, `--review-frequency-days`, `--framework`, `--suggested-control-family` repeatable)
`pretorin risk seed <system_id>`	Seed risks from library templates (`--framework`, `--template-id` repeatable)
`pretorin risk update <system_id> <risk_id>`	Update fields including mitigation (`--title`, `--description/-d`, `--category`, `--cia-category`, `--likelihood`, `--impact`, `--owner-id`, `--status`, `--review-frequency-days`, `--treatment`, `--treatment-plan`, `--treatment-due-date`)
`pretorin risk link add <system_id> <risk_id>`	Attach an artifact (`--link-type`, exactly one of `--control` + `--framework`, `--evidence`, `--finding`, `--vendor`, `--monitoring-event`)
`pretorin risk link rm <system_id> <risk_id> <link_id>`	Remove a risk artifact link
`pretorin risk refresh-summary <system_id> <risk_id>`	Re-score risk and trigger best-effort AI summary regeneration
`pretorin risk posture <system_id>`	System-scoped risk posture summary (inherent vs residual, overdue, top 5)
`pretorin risk attest <system_id> <risk_id>`	Produce a DSSE-signed attestation over the current risk state (`--type`, `--statement/-m`)
`pretorin risk attestations <system_id> <risk_id>`	List DSSE attestation envelopes for a risk (newest first)
`pretorin risk library list`	Browse the org-level risk template library (`--category`)

Risk Attestation Types

residual_accepted, mitigation_approved, inherent_validated

Risk Treatment Values

mitigate, accept, transfer, avoid

Risk Link Types

contributes_to_risk, mitigates_risk, evidence_of_risk

STIG Commands

Command	Description
`pretorin stig list`	List STIG benchmarks (`--technology-area/-t`, `--product/-p`, `--limit/-l`)
`pretorin stig show <stig_id>`	Show STIG benchmark detail with severity breakdown
`pretorin stig rules <stig_id>`	List rules for a benchmark (`--severity/-s`, `--cci`, `--limit/-l`)
`pretorin stig applicable`	Show applicable STIGs for the active system (`--system/-s`)
`pretorin stig infer`	AI-infer applicable STIGs from system profile (`--system/-s`)
`pretorin stig checklists`	List per-asset STIG checklists (`--system/-s`, `--asset/-a`, `--limit/-l`, `--offset`)
`pretorin stig create-checklist`	Create a checklist bound to a benchmark + asset (`--benchmark/-b`, `--asset/-a`, `--title`, `--system/-s`)
`pretorin stig export <checklist_id>`	Download a regenerated `.ckl`/`.cklb`, print SHA-256 (`--format/-f`, `--output/-o`, `--system/-s`)
`pretorin stig import <checklist_id> <file>`	Import a `.ckl`/`.cklb` (review axis) or XCCDF (`--format xccdf`, test axis) (`--format/-f`, `--system/-s`)

CCI Commands

Command	Description
`pretorin cci list`	List CCIs (`--control/-c`, `--status`, `--limit/-l`)
`pretorin cci show <cci_id>`	Show CCI detail with linked SRGs and STIG rules (e.g., `CCI-000015`)
`pretorin cci chain <control_id>`	Full traceability chain: Control -> CCIs -> SRGs -> STIG rules (`--system/-s`)
`pretorin cci impl <cci_uuid>`	Show the per-system CCI implementation row (status, narrative, evidence_ids, eMASS fields) — 404 means uninitialized (`--system/-s`)

OSCAL Artifact Commands

Read-only access to validated OSCAL export artifacts. See OSCAL Artifacts.

Command	Description
`pretorin oscal artifacts list`	List validated OSCAL artifacts for a system (`--type/-t`, `--framework/-f`, `--assessment/-a`, `--system/-s`, `--limit/-l`, `--offset`)
`pretorin oscal artifacts show <artifact_id>`	Show artifact metadata and the two-tier validation report (`--system/-s`)
`pretorin oscal artifacts download <artifact_id>`	Download an artifact, verifying SHA-256 (`--output/-o`, `--verify/--no-verify`, `--system/-s`)
`pretorin oscal artifacts latest --type <type>`	Show (or `--download/-d`) the latest validated artifact of a type (`--framework/-f`, `--assessment/-a`, `--output/-o`, `--verify/--no-verify`, `--system/-s`)

Preflight & Source Resolution Commands

Preflight verifies that the source material each recipe needs is actually reachable on this host before evidence work begins, then seeds the scope’s active recipe set from what’s runnable. Artifacts are per-scope (system + framework). See Recipes for how recipes consume sources.

Command	Description
`pretorin preflight show`	Show the current preflight verdict for the active (or given) scope (`--system`, `--framework`)
`pretorin preflight verify`	Probe every bound resolver, persist results, and show the refreshed verdict (`--system`, `--framework`)
`pretorin preflight init`	Bind sensible host-local defaults for this machine, then optionally verify (`--workspace`, `--replace`, `--verify/--no-verify`, `--system`, `--framework`)
`pretorin preflight provision`	Propose (and with `--apply` seed) the active recipe set from the ready-set (`--apply`, `--include-unofficial`, `--system`, `--framework`)
`pretorin preflight bind <kind>`	Add one resolver to a source kind’s collection, creating the artifact if needed (`--type` required, `--name`, `--constraint`, `--scope` repeatable, `--probe`, `--param` repeatable, `--capability` repeatable, `--recommended`, `--system`, `--framework`)
`pretorin preflight unbind <kind>`	Remove one resolver binding from a source kind by display name (`--name` required, `--system`, `--framework`)

Recipe Commands

Recipes are markdown + script playbooks the calling AI agent executes. See Recipes for authoring guidance.

Command	Description
`pretorin recipe list`	List all loaded recipes with id, name, tier, author, and source path (`--tier`, `--source`, `--system`, `--active`)
`pretorin recipe show <recipe_id>`	Display a recipe’s manifest, body, and (with `--sources`) all loader paths
`pretorin recipe new <recipe_id>`	Scaffold a new recipe directory (`--location` user/project/builtin, `--author`, `--name`)
`pretorin recipe validate <recipe_id>`	Validate a recipe’s manifest, scripts, and description quality (`--path` for path-based override)
`pretorin recipe run <recipe_id>`	Run a recipe’s script locally for testing (`--script/-s`, `--param/-p` repeatable, `--path`, `--system`, `--framework`, `--no-context`)
`pretorin recipe active`	Show the scope’s active recipe set + a provisioning proposal (`--system`, `--framework`)
`pretorin recipe activate <recipe_id...>`	Add recipe(s) to the scope’s active set (`--system`, `--framework`)
`pretorin recipe deactivate <recipe_id...>`	Remove recipe(s) from the scope’s active set (`--system`, `--framework`)

Scanning

The legacy pretorin scan command was removed when the recipes system landed. Scanning now happens through built-in recipes that the calling AI agent invokes via MCP. See STIG Scanning for the recipe-based workflow.

Recipe ID	Wraps	CLI requirement
`inspec-baseline`	Chef InSpec	`inspec`
`openscap-baseline`	OpenSCAP	`oscap`
`cloud-aws-baseline`	AWS APIs	`aws`
`cloud-azure-baseline`	Azure APIs	`az`
`manual-attestation`	Human attestation	—

Deprecated Commands

Command	Description
`pretorin harness init`	Deprecated: initialize harness config
`pretorin harness doctor`	Deprecated: validate harness setup
`pretorin harness run "<task>"`	Deprecated: run task through harness backend

Pretorin Developer & Agent Docs