Metadata-Version: 2.5
Name: pretorin
Version: 0.29.10
Summary: CLI and MCP server for Pretorin Compliance API
Project-URL: Homepage, https://pretorin.com
Project-URL: Documentation, https://platform.pretorin.com/api/docs
Project-URL: Repository, https://github.com/pretorin-ai/pretorin-cli
Project-URL: Changelog, https://github.com/pretorin-ai/pretorin-cli/blob/master/CHANGELOG.md
Project-URL: Issues, https://github.com/pretorin-ai/pretorin-cli/issues
Author-email: Pretorin <support@pretorin.com>
License: Apache-2.0
License-File: LICENSE
Keywords: cli,cmmc,compliance,fedramp,iso27001,mcp,nist,oscal,security,soc2
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: System :: Systems Administration
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: cryptography>=50.0.0
Requires-Dist: filelock<4.0.0,>=3.20.3
Requires-Dist: hatchet-sdk==1.39.0
Requires-Dist: httpx>=0.25.0
Requires-Dist: jsonschema>=4.0.0
Requires-Dist: mcp<3.0.0,>=1.28.1
Requires-Dist: pydantic>=2.11.0
Requires-Dist: pypdf>=6.16.1
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0.0
Requires-Dist: textual<2.0,>=1.0
Requires-Dist: typer>=0.15.4
Provides-Extra: agent
Requires-Dist: openai-agents>=0.2.9; extra == 'agent'
Requires-Dist: openai-codex-sdk>=0.1.11; extra == 'agent'
Requires-Dist: openai>=1.0.0; extra == 'agent'
Provides-Extra: binary-build
Requires-Dist: pyinstaller>=6.0; extra == 'binary-build'
Provides-Extra: builtin-agent
Requires-Dist: openai-agents>=0.2.9; extra == 'builtin-agent'
Requires-Dist: openai-codex-sdk>=0.1.11; extra == 'builtin-agent'
Requires-Dist: openai>=1.0.0; extra == 'builtin-agent'
Provides-Extra: campaign-runner
Provides-Extra: cloud-inventory
Requires-Dist: azure-identity>=1.16.1; extra == 'cloud-inventory'
Requires-Dist: azure-mgmt-compute>=30.0.0; extra == 'cloud-inventory'
Requires-Dist: boto3>=1.34.0; extra == 'cloud-inventory'
Provides-Extra: dev
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=1.4.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=9.0.3; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Requires-Dist: types-jsonschema>=4.0; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
Description-Content-Type: text/markdown

<p align="center">
  <img src="assets/Logo_White+Orange.png" alt="Pretorin" width="400">
</p>

<p align="center">
  <strong>Compliance tools for developers. Integrate with AI agents or your CI pipeline.</strong>
</p>

<p align="center">
  <a href="https://pypi.org/project/pretorin/"><img src="https://img.shields.io/pypi/v/pretorin" alt="PyPI version"></a>
  <a href="https://registry.modelcontextprotocol.io/"><img src="https://img.shields.io/badge/MCP_Registry-Listed-green" alt="MCP Registry"></a>
  <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-Compatible-green" alt="MCP Compatible"></a>
  <a href="https://opensource.org/licenses/Apache-2.0"><img src="https://img.shields.io/badge/License-Apache%202.0-yellow.svg" alt="License: Apache-2.0"></a>
  <a href="https://github.com/pretorin-ai/pretorin-cli/actions"><img src="https://github.com/pretorin-ai/pretorin-cli/actions/workflows/test.yml/badge.svg" alt="Tests"></a>
  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.10%2B-blue" alt="Python 3.10+"></a>
</p>

---

> **Beta** — Pretorin is currently in closed beta. Framework/control browsing works for authenticated users. Platform write features (evidence, narratives, monitoring) require a beta code. [Sign up for early access](https://pretorin.com/early-access/).

Pretorin CLI gives developers and AI agents direct access to compliance data, implementation context, and evidence workflows.

The CLI and MCP tooling in this repository are open source. Access to Pretorin-hosted platform services, APIs, and account-scoped data is authenticated and governed separately by the applicable platform terms.

`mcp-name: io.github.pretorin-ai/pretorin`

## Two Usage Modes

1. Built-in agent mode: run `pretorin agent run` with the selectable Codex or OpenCode harness. Codex defaults to Pretorin-hosted model endpoints; either harness can be configured independently.
2. Bring-your-own-agent mode: run `pretorin mcp-serve` and connect the MCP server to your existing AI tool (Claude Code, Codex CLI, Cursor, etc.).

## Quick Start

```bash
uv tool install pretorin
pretorin login
pretorin skill install
```

Run the walkthrough:

```bash
bash tools/demo-walkthrough.sh
```

## Built-in Agent Workflow (Recommended)

Use this flow when you want Pretorin to launch the local agent harness. Codex is
the default. You can select OpenCode instead, and the same saved choice is used
by `pretorin agent run` and new Campaigns.

1. Authenticate with your Pretorin API key:

```bash
pretorin login
```

2. Choose and configure the harness. Omit this command to keep the Codex default:

```bash
pretorin agent configure --agent codex
# Or, for OpenCode, save an explicit provider/model and reasoning profile:
pretorin agent configure --agent opencode \
  --model openai/gpt-5.6-terra --reasoning-effort low
```

If no harness has been selected, the first `pretorin agent install --agent
codex|opencode` or `pretorin campaign install --agent codex|opencode` saves
that explicit choice; without `--agent`, either interactive install prompts
and saves the answer. Once a default exists, installing the other harness does
not change it—use `agent configure` for that. Harness selection remains
non-secret; provider credentials stay in their normal environment or
authentication store.

Reasoning effort is a shared optional setting with portable `low`, `medium`,
and `high` values. An explicit `--reasoning-effort` on `agent run` or
`campaign start` overrides the selected harness's saved value. If neither is
set, Pretorin leaves the choice to the provider/harness default. OpenCode maps
the value through its native `--variant`; Pretorin validates support against
the exact authenticated model before execution and rejects unsupported pairs
rather than silently using the model default.

3. Optional: point Codex model traffic to a custom/self-hosted Pretorin endpoint:

```bash
pretorin config set model_api_base_url https://platform.pretorin.com/api/v1/public/model
```

4. Verify runtime setup:

```bash
pretorin agent doctor
pretorin agent install
```

5. Run an agent task:

```bash
pretorin agent run "Assess AC-2 implementation gaps for my system"
```

Runtime selection in the default `auto` mode is configured executable →
compatible executable on `PATH` → Pretorin-managed binary. `system` permits
only the configured path or compatible `PATH` discovery and never downloads;
`managed` ignores configured and `PATH` executables and uses only Pretorin's
managed artifact. `agent install` resolves only the selected harness. Provider
credential resolution remains harness-specific; credentials are never saved by
`agent configure`.

## Add to Your AI Tool

Use this flow when you already have an AI agent/tool and want Pretorin as an MCP capability provider.

<img src="assets/Rome-bot_Basic-1.png" alt="Rome-bot" width="120" align="right">

### Install the Skill

The Pretorin skill teaches your AI agent how to use MCP tools effectively for compliance workflows. Install it for Claude Code and/or Codex CLI:

```bash
pretorin skill install                # both agents
pretorin skill install --agent claude # claude only
pretorin skill install --agent codex  # codex only
pretorin skill status                 # check what's installed
```

### 1. Claude Code

```bash
claude mcp add --transport stdio pretorin -- pretorin mcp-serve
```

Team setup via `.mcp.json`:

```json
{
  "mcpServers": {
    "pretorin": {
      "type": "stdio",
      "command": "pretorin",
      "args": ["mcp-serve"]
    }
  }
}
```

### 2. Codex CLI

Add to `~/.codex/config.toml`:

```toml
[mcp_servers.pretorin]
command = "pretorin"
args = ["mcp-serve"]
```

If you installed Pretorin with `uv tool install` or `pipx`, prefer pinning the absolute path from `command -v pretorin` to avoid PATH drift between shells and GUI apps.

For Claude Desktop, Cursor, and Windsurf setup, see [docs/MCP.md](docs/MCP.md).

## Core Commands

Platform-backed review and update workflows are single-scope: set one active `system + framework` first with `pretorin context set`, then run evidence, issue, monitoring, narrative, or MCP-assisted compliance commands inside that scope. Multi-framework work must be split into separate runs. Evidence, narratives, and issues all support a local-first workflow: create locally, list, then push to the platform.

| Command | Purpose |
|---------|---------|
| `pretorin login` | Authenticate with the Pretorin API |
| `pretorin logout` | Clear stored credentials |
| `pretorin whoami` | Show current authenticated user |
| `pretorin frameworks list` | List available frameworks |
| `pretorin frameworks get <framework>` | Show framework metadata and coverage |
| `pretorin frameworks families <framework>` | List a framework's control families |
| `pretorin frameworks controls <framework> [family]` | List controls, optionally scoped to one family |
| `pretorin frameworks control <framework> <control>` | Get control details and guidance |
| `pretorin context list` | List all systems and their compliance status |
| `pretorin context set` | Set active system/framework context |
| `pretorin context show` | Inspect and validate the active context |
| `pretorin context verify` | Verify the active context with source attestation |
| `pretorin context manifest` | Show the resolved source manifest and evaluate detected sources |
| `pretorin context clear` | Clear the active context |
| `pretorin control status` | Start/reopen control authoring with `in_progress` |
| `pretorin control context` | Get full control context for the active scope |
| `pretorin evidence create` | Create local evidence file |
| `pretorin evidence format-markdown` | Reformat evidence Markdown (headings → bold section labels) |
| `pretorin evidence list` | List local evidence files |
| `pretorin evidence push` | Push local evidence to Pretorin |
| `pretorin evidence search` | Search platform evidence |
| `pretorin evidence link` | Link evidence to a control |
| `pretorin evidence link-cci` | Link evidence to a CCI implementation row |
| `pretorin evidence link-stig` | Link evidence to a STIG rule workflow |
| `pretorin evidence upsert <ctrl> <fw>` | Find-or-create evidence and link it |
| `pretorin evidence mark-current <id>` | Re-affirm evidence freshness (bump `expires_at`, transition expired→valid) |
| `pretorin evidence validate <id>` | Validate freshness against recorded source provenance; mark-current if unchanged, replace artifact + send drift note if changed |
| `pretorin evidence upload` | Upload a file as evidence to the platform |
| `pretorin evidence delete` | Delete an evidence record |
| `pretorin evidence attestation get <id>` | Fetch the DSSE attestation envelope for an evidence record (`--lineage` for full history) |
| `pretorin evidence attestation verify <id>` | Verify the DSSE signature against the deployment key registry (`--env`, `--key-fingerprint`) |
| `pretorin narrative create` | Create local narrative file |
| `pretorin narrative list` | List local narrative files |
| `pretorin narrative push` | Push local narratives to Pretorin |
| `pretorin narrative get <ctrl> <fw>` | Get current control narrative |
| `pretorin narrative push-file <ctrl> <fw> <sys> <file>` | Push a single narrative file |
| `pretorin issues create` | Create local issue file |
| `pretorin issues list --local` | List local issue files |
| `pretorin issues push` | Push local issues to Pretorin |
| `pretorin issues list <ctrl> <fw>` | List platform control issues |
| `pretorin issues inbox [fw]` | List issues across a whole system/framework, not just one control |
| `pretorin issues add <ctrl> <fw> --title ... --content ... --likelihood ... --impact ...` | Add canonical Issue + provisional risk |
| `pretorin issues risk-history/risk-add <control_impl_id> <issue_id>` | Read or append Issue risk evaluations |
| `pretorin issues poam-set <control_impl_id> <issue_id>` | Populate formal POA&M facts |
| `pretorin issues plan-*` / `pretorin issues action-*` | Build plans/actions and execute approved work |
| `pretorin issues resolve <ctrl> <fw> <issue_id> --resolution-note ...` | Resolve (close) a control issue |
| `pretorin notes ...` | Deprecated compatibility alias for issue workflows |
| `pretorin monitoring push` | Push a monitoring event |
| `pretorin agent configure --agent codex\|opencode` | Select the shared built-in harness and optionally save model/provider/reasoning settings |
| `pretorin agent run "<task>"` | Run a compliance task with the selected harness and optional `--reasoning-effort` |
| `pretorin review run --control-id <id> --path <dir>` | Review local code for control coverage |
| `pretorin review status --control-id <id>` | Show the implementation status for a specific control |
| `pretorin skill install` | Install Pretorin skill for AI agents |
| `pretorin skill status` | Check skill install status per agent |
| `pretorin skill uninstall` | Remove the installed skill from one or more agents |
| `pretorin skill list-agents` | List known agents and their skill directories |
| `pretorin mcp-serve` | Start MCP server |
| `pretorin mcp-smoke-test` | Smoke-test the MCP tool surface (exits non-zero on failure) |
| `pretorin version` | Show CLI version, runtime kind, and resolved executable path |
| `pretorin link` | Pin the canonical MCP path `~/.pretorin/bin/pretorin` at this executable |
| `pretorin update [version]` | Update the CLI to the latest (or a specific) version |
| `pretorin config set/get/list/path` | Read and write stored configuration |

### Assessment Objectives

Assessment objectives are the assessable leaves beneath controls in CMMC and compatible catalogs such as NIST 800-171A. The `objective` group reads and updates their per-system implementation rows through the same governed public API the MCP tools use. See [Assessment Objectives](docs/src/cli/objectives.md).

| Command | Purpose |
|---------|---------|
| `pretorin objective list` | List objective implementations with stable IDs and readiness state |
| `pretorin objective show <id>` | Show objective detail, coverage, provenance, and merged history |
| `pretorin objective seed <control_id>` | Idempotently initialize the catalog objectives for one control |
| `pretorin objective start <id>` | Start objective work (`in_progress`, the only public write status) |
| `pretorin objective narrative <id> <text>` | Write the current objective narrative draft |
| `pretorin objective approve <id>` | Approve a grounded objective without approving its parent control |
| `pretorin objective reopen <id>` | Reopen an approved objective through the public unapprove route |
| `pretorin objective link-evidence/unlink-evidence <id> <evidence_id>` | Link or unlink one evidence item at objective grain |

### Campaign Workflows

Campaigns run a frozen set of compliance items through a local parent Plan and
one deterministic child Plan per item. CLI and MCP share one transport-neutral
coordinator that creates or strictly reconciles
those Plans before dispatch, and each isolated process using the selected Codex
or OpenCode harness adopts its exact assigned child. Embedded Hatchet owns
durable local dispatch and retries; the child follows its selected workflow
through the existing MCP and platform APIs.

| Command | Purpose |
|---------|---------|
| `pretorin campaign start initial-pass` | Run a first best-effort control assessment |
| `pretorin campaign start interim-pass` | Revisit selected controls or review findings |
| `pretorin campaign start issue-triage` | Reconcile existing open Issues and next actions |
| `pretorin campaign start evidence-review` | Review selected evidence or control evidence coverage |
| `pretorin campaign list` | List local Campaign Plans |
| `pretorin campaign status <plan-id>` | Show persisted execution, assessment, and last-recorded platform-review state |
| `pretorin campaign watch <plan-id>` | Attach the read-only observer and live-refresh recorded queued/running review jobs |
| `pretorin campaign resume <plan-id>` | Adopt live Hatchet runs, submit unfinished work, or reopen failed items on this host |
| `pretorin campaign cancel <plan-id>` | Durably request cancellation; terminal acknowledgement may be asynchronous |

The normal MCP profile provides the seven-tool parity lifecycle:
`check_campaign_runtime`, `preview_campaign`, `start_campaign`,
`get_campaign`, `list_campaigns`, `resume_campaign`, and `cancel_campaign`.
Runtime readiness is a read-only first gate: when `launch_ready=false`, stop,
follow the structured remediation, restart the MCP process, and check again.
Only a ready host proceeds to preview, where the coordinator performs the one
shared source preflight and freezes the Plan hierarchy and confirmation digest.
Start requires explicit confirmation of that exact Plan ID and digest, rechecks
the execution dependencies, and then returns while the detached supervisor
continues. Campaigns created through either surface can be managed through the
other. Every single-Campaign MCP response suggests the same-host
`pretorin campaign watch <plan-id>` TUI command and a pinned
`uvx --from "pretorin==0.29.10"` alternative; MCP never executes or streams the
terminal itself.

The standard Pretorin install includes the Campaign coordinator's exact Python
dependencies. The former `campaign-runner` extra remains accepted as a
compatibility-only alias, but is not required for a new install. The minimal
best-effort first run needs two Pretorin commands:

```bash
pretorin campaign install --agent codex
pretorin campaign start initial-pass \
  --system "My System" --framework cmmc-l1 --all-controls --agent codex
```

Use `pretorin[builtin-agent]` when the same environment should also support
interactive `pretorin agent run` sessions. `pretorin update` preserves selected
supported extras across uv, pipx, and pip-style upgrades. The Campaign runner
verifies its exact Hatchet SDK pin before source preflight, Plan creation, or
native-runtime resolution.

`campaign install`, `campaign doctor`, and `campaign version` accept
`--agent codex|opencode` and otherwise use the saved shared default. They
resolve only that harness plus embedded Hatchet. In `auto` mode the order is an
explicitly configured executable, a compatible executable on `PATH`, then a
checksum-pinned managed binary. `system` never downloads and `managed` is
managed-only. On a fresh configuration, `campaign install` uses the same
prompt-and-persist rule as `agent install`. No global npm installation is
performed.

`campaign start` also accepts `--agent`, `--model`, `--model-provider`, and
`--reasoning-effort low|medium|high`.
The selected harness, concrete model/provider/reasoning effort, Codex model
endpoint, exact executable source, version, managed status, and SHA-256
identity are frozen into the Campaign record together with the shared preflight
snapshot and worker contract; retry and resume keep those coordinates and
refuse endpoint, source, identity, or Plan drift rather than following a
changed global setting, package definition, or `PATH` entry. If reasoning
effort is unset, the provider/harness default remains in effect.
OpenCode's authenticated variant check currently requires POSIX process-group
isolation. On Windows, leave the OpenCode effort unset to retain its native
default, or use Codex for an explicit effort.
OpenCode Campaigns require a concrete model, either saved with `agent
configure` or supplied with `--model` (for example `provider/model`).
Both harnesses use a stricter Campaign profile than an interactive run: one
ephemeral home/config per attempt, the frozen least-privilege assignment, the
assigned Pretorin MCP server with an assignment-specific tool allowlist, a
read-only workspace, and no web or delegated-task tools. OpenCode denies its
native shell. Codex retains sandboxed inspection commands with native network
disabled and a credential-free shell environment; before model launch,
Pretorin behaviorally verifies that the exact workspace cannot be written and
rejects roots that expose owner credentials or cannot enforce that boundary.
Model-provider, platform, and preflight-authorized evidence-source credentials
remain separate and are never persisted in Campaign state.
Before either an interactive agent task or a Campaign starts work, Pretorin runs
the same ordinary preflight once for the active system/framework and target
workspace. A previously unprovisioned scope deterministically pins runnable
official recipes; `pretorin recipe activate` remains the explicit customization
surface. Campaigns freeze that artifact and digest with the roster, and every
child/retry gets a private read-only copy instead of re-running preflight.
Repository-scoped automatic resolvers are filtered to the target Git workspace,
so preparing the same system/framework from another clone cannot carry that
clone's source verdicts into the run.
Missing sources become visible `needs_input` limitations instead of fabricated
evidence or automatic Issues.
Control passes publish each frozen objective's truthful agent draft, exact
evidence roster, and `in_progress` status through the existing objective API;
they do not approve objectives or parent controls.
Platform review is never requested by default; pass `campaign start --review`
for an eligible control pass. Platform artifacts and review remain authoritative on the existing platform,
and Campaign completion never approves a control. See the
[Campaign guide](docs/src/cli/campaigns.md).

The local Sentinel Shield CMMC demo uses the ordinary Campaign CLI. Seed the
larger platform demo from the monorepo, then start the Campaign from the clean
root of the locally cloned target repository so that repository is frozen as
the Campaign workspace:

```bash
# Seed/reset only the CMMC demo data.
make -C /path/to/monorepo seed-demo-cmmc

cd /path/to/sentinel-shield-platform

# Two-control workflow smoke test.
pretorin campaign start initial-pass \
  --system "Sentinel Shield JWIP" --framework cmmc-l1 \
  --controls AC.L1-3.1.1,IA.L1-3.5.2 \
  --agent opencode --model openai/gpt-5.6-terra \
  --reasoning-effort low --yes --detach

# Replace --controls above with --all-controls for all 17 controls / 59 objectives.
pretorin campaign watch <campaign-plan-id>
```

Use `--dry-run` to inspect the frozen Plan without launching a model or writing
platform artifacts. The CLI uses the shared configured Codex or OpenCode
harness when the explicit agent/model options are omitted.

### Vendor Management & Inheritance

Manage vendor entities (CSPs, SaaS, managed services) and track control inheritance through vendor responsibility edges.

| Command | Purpose |
|---------|---------|
| `pretorin vendor list` | List all vendors, with optional search/filter/sort |
| `pretorin vendor create <name> --type csp --inherent-risk high` | Create a vendor entity |
| `pretorin vendor get <id>` | Get vendor details |
| `pretorin vendor update <id>` | Update vendor fields (name, description, type, authorization level, owner, inherent risk) |
| `pretorin vendor delete <id>` | Delete a vendor entity |
| `pretorin vendor dashboard` | Portfolio view across vendors (risk, lifecycle, assessment state) |
| `pretorin vendor lifecycle <id> <stage>` | Move a vendor through its lifecycle stages |
| `pretorin vendor history <id>` | Show vendor audit and evidence history |
| `pretorin vendor systems attach/detach <id>` | Attach or detach systems that inherit from a vendor |
| `pretorin vendor contact list/add/update/delete <id>` | Manage vendor contacts |
| `pretorin vendor contract list/add/update/delete <id>` | Manage vendor contracts |
| `pretorin vendor upload-doc <id> <file>` | Upload vendor evidence document |
| `pretorin vendor list-docs <id>` | List vendor documents |
| `pretorin vendor template list` | List assessment templates |
| `pretorin vendor template import <xlsx> --source-format sig_lite` | Preview or import SIG-Lite/CAIQ-Lite templates |
| `pretorin vendor assessment launch <vendor_id> --template-id <template_id>` | Launch a vendor assessment |
| `pretorin vendor assessment save-responses <vendor_id> <assessment_id> --answers-file answers.json` | Save assessment answers |
| `pretorin vendor assessment review <vendor_id> <assessment_id>` | Finalize residual likelihood and impact |
| `pretorin vendor assessment reopen <vendor_id> <assessment_id> [--reason ...]` | Reopen a reviewed assessment for correction |

Reopening moves a `reviewed` assessment back to `in_progress`, revokes its live
portal token, and resets its AI advisory. The prior completed review remains in
the audit history as superseded. A positive `review_revision` on an assessment
whose status is not `reviewed` therefore means its displayed residual ratings
and risk tier describe that prior review, not the current in-progress work.

### Risk Management

Populate a system's risk register: list and create risks, attach artifact links (controls, evidence, findings, vendors), record mitigation strategies, and refresh AI summaries. Risks are system-scoped; the library is org-level. Every `risk` command takes the system as `--system/-s` (ID or name) and falls back to the active context when the flag is unset.

| Command | Purpose |
|---------|---------|
| `pretorin risk list` | List risks for a system (filter by category, level, status) |
| `pretorin risk show <risk_id>` | Show full risk including artifact links |
| `pretorin risk create --title ...` | Create a risk; pass `--framework` for control auto-link |
| `pretorin risk seed` | Seed risks from library templates |
| `pretorin risk update <risk_id>` | Update fields including `--treatment` (mitigation surface) |
| `pretorin risk link add <risk_id>` | Attach a control / evidence / finding / vendor to a risk |
| `pretorin risk link rm <risk_id> <link_id>` | Remove a risk artifact link |
| `pretorin risk refresh-summary <risk_id>` | Re-score risk and trigger best-effort AI summary |
| `pretorin risk posture` | System-scoped risk posture (inherent/residual distribution, overdue attestations, top 5) |
| `pretorin risk attest <risk_id> --type ... --statement ...` | Produce a DSSE-signed risk attestation (`residual_accepted`, `mitigation_approved`, `inherent_validated`) |
| `pretorin risk attestations <risk_id>` | List DSSE attestation envelopes for a risk (newest first) |
| `pretorin risk library list` | Browse the org-level template library |

### Policy & Scope Questionnaires

Stateful questionnaire workflows for organization policies and system scope.
Answer questions interactively or in bulk through the domain-specific policy
and scope workflows; the four Plan-backed Campaign types do not cover these
questionnaires. Policies also carry a full authoring lifecycle: define a custom
policy, generate its narrative, run AI review, map it to framework controls, and
submit it for human approval. Before editing a generated policy, use policy
narrative search to check whether the concept is already covered.

| Command | Purpose |
|---------|---------|
| `pretorin policy list` | List org policies available for questionnaire work |
| `pretorin policy show --policy <policy_id>` | Show questionnaire state and saved review findings |
| `pretorin policy populate` | Auto-populate policy answers from context |
| `pretorin policy narrative --policy <policy_id>` | Show a policy's generated narrative sections, in order |
| `pretorin policy search <policy_id> "<query>"` | Search one policy narrative for ranked, excerpt-bearing coverage matches |
| `pretorin policy create` | Validate, preview, and optionally create a custom policy |
| `pretorin policy definition --policy <policy_id>` | Show the resolved definition and concurrency revision |
| `pretorin policy configure --policy <policy_id>` | Validate, preview, and optionally replace a policy definition |
| `pretorin policy generate --policy <policy_id>` | Generate a ready policy and wait for its durable job |
| `pretorin policy review --policy <policy_id>` | Run AI review for a ready policy and wait for completion |
| `pretorin policy submit --policy <policy_id>` | Submit for human review (never approves it) |
| `pretorin policy mappings --policy <policy_id>` | List a policy's persisted mappings in one framework |
| `pretorin policy map --policy <policy_id>` | Preview or replace mappings for exactly one framework |
| `pretorin policy reopen --policy <policy_id>` | Reopen an approved policy for editing (regress to draft) |
| `pretorin scope show` | Show scope questionnaire for active context |
| `pretorin scope populate` | Auto-populate scope answers from context |
| `pretorin scope target-tier [tier]` | Read or set the scope's target scale tier |
| `pretorin scope reopen` | Reopen an approved scope for editing |

### System Spec & Asset Inventory

Manage the 5 auditor-required system_spec artifact kinds (asset inventory + 4 snapshot kinds). Inventory writes classify rows client-side into added/modified/decommissioned before posting a single diff.

| Command | Purpose |
|---------|---------|
| `pretorin scope artifacts list` | List the 5 system_spec artifact kinds with required/toggle/attest state |
| `pretorin scope artifacts toggle <kind>` | Toggle an artifact kind required/optional (`--optional`, `--rationale`) |
| `pretorin scope artifacts inventory show` | Show the current (or historical) asset inventory (`--as-of`) |
| `pretorin scope artifacts inventory upload <csv>` | Parse a CSV, classify rows, and post a single inventory diff |
| `pretorin scope artifacts inventory scan <source>` | Run a recipe-driven scan (`aws`, `azure`, `k8s`, `iac-workspace`) and post the diff |

Live `aws` and `azure` enumeration needs the cloud SDKs: install
`pretorin[cloud-inventory]`. The `k8s` scan needs `kubectl` on `PATH`, and
`iac-workspace` reads the local workspace; neither needs an extra.

### STIG & CCI Browsing

Browse STIG benchmarks, rules, and CCIs with full traceability from NIST 800-53 controls down to individual STIG check rules.

| Command | Purpose |
|---------|---------|
| `pretorin stig list` | List STIG benchmarks |
| `pretorin stig show <id>` | Show STIG benchmark detail |
| `pretorin stig rules <id>` | List rules for a benchmark |
| `pretorin stig applicable` | Show applicable STIGs for active system |
| `pretorin stig infer` | AI-infer applicable STIGs from system profile |
| `pretorin cci list` | List CCIs with optional control filter |
| `pretorin cci show <id>` | Show CCI detail with bounded/filterable linked rules |
| `pretorin cci chain <control_id>` | Full traceability: Control -> CCIs -> STIG rules |
| `pretorin cci impl <cci_uuid>` | Show per-system CCI implementation (status, narrative, evidence) |

STIG checklists are asset-scoped and round-trip through the DISA formats:

| Command | Purpose |
|---------|---------|
| `pretorin stig checklists` | List STIG checklists for the active system |
| `pretorin stig create-checklist -b <benchmark> -a <asset>` | Create an asset-scoped checklist |
| `pretorin stig export <checklist_id>` | Download a checklist as `.ckl` (XML) or `.cklb` (JSON) |
| `pretorin stig import <checklist_id> <file>` | Import a `.ckl`/`.cklb` checklist or an XCCDF scan |

### Custom Frameworks

Author your own compliance framework or fork an existing one. The toolchain ships a vendored unified-framework JSON Schema, OSCAL ↔ unified converters with lossless round-trip, and an end-to-end build / validate / upload workflow against the platform's framework revision lifecycle.

| Command | Purpose |
|---------|---------|
| `pretorin frameworks init-custom <id>` | Scaffold a minimal valid `unified.json` template |
| `pretorin frameworks validate-custom <path>` | Local JSON Schema pre-flight before upload |
| `pretorin frameworks build-custom <input> -f <id>` | Auto-detect input shape and normalize to `unified.json` |
| `pretorin frameworks upload-custom <path> [--publish]` | POST a draft revision; `--publish` immediately promotes it |
| `pretorin frameworks fork-framework <upstream_id> <new_id>` | Create a linked-fork draft anchored on upstream |
| `pretorin frameworks rebase-fork <id>` | Create a fresh rebase draft against the latest upstream |
| `pretorin frameworks revisions <id>` | List draft and published revisions |
| `pretorin frameworks export-oscal <unified.json>` | Regenerate an OSCAL catalog from a unified artifact |

### OSCAL Artifacts

Browse and download the platform's validated OSCAL export artifacts (SSP, SAP, SAR, POA&M, component definitions, bundles) for the active system, with SHA-256 checksum verification on download.

| Command | Purpose |
|---------|---------|
| `pretorin oscal artifacts list` | List validated OSCAL artifacts (filter by `--type`, `--framework`, `--assessment`) |
| `pretorin oscal artifacts show <id>` | Show artifact metadata including the validation report |
| `pretorin oscal artifacts download <id>` | Download an artifact, verifying its SHA-256 checksum |
| `pretorin oscal artifacts latest --type ssp` | Show (or download) the latest validated artifact of a given type |

### Preflight & Source Resolution

Preflight maps the source kinds a scope recommends (code repositories, cloud control planes, CI systems, etc.) to host-local resolvers and probes them, so an agent knows what evidence it can actually collect on this machine before it starts. It also seeds the active recipe set from the resolvers that verify here.

| Command | Purpose |
|---------|---------|
| `pretorin preflight show` | Show the current preflight verdict for the active (or given) scope |
| `pretorin preflight verify` | Probe every bound resolver, persist results, and show the refreshed verdict |
| `pretorin preflight init` | Bind sensible host-local resolver defaults for this machine, then optionally verify |
| `pretorin preflight provision` | Propose (and optionally seed) the active recipe set from the ready-set |
| `pretorin preflight bind <kind>` | Add one resolver to a source kind's collection |
| `pretorin preflight unbind <kind>` | Remove one resolver binding from a source kind by display name |

### Recipes

Recipes are agent-executable playbooks bundled with pretorin (markdown + scripts) that the calling AI agent reads, plans against, and runs. Twenty-one recipes ship built in, covering scanners (OpenSCAP, InSpec, AWS/Azure cloud baselines, PostgreSQL STIG), asset inventory (AWS, Azure, Kubernetes, IaC workspace), evidence capture (code, CI, workspace, manual attestation), authoring (evidence/narrative composition, scope artifacts, policy and scope question answering), SSP document gap analysis, and issue workflows. Run `pretorin recipe list` for the current set. Authoring docs live at [docs/src/recipes/](docs/src/recipes/) and the contract spec at [docs/rfcs/0001-recipes.md](docs/rfcs/0001-recipes.md).

| Command | Purpose |
|---------|---------|
| `pretorin recipe list` | List all loaded recipes (built-in + user + project) |
| `pretorin recipe active` | Show the active recipe set plus a provisioning proposal for the scope |
| `pretorin recipe activate <id>...` | Add recipe(s) to the active set for this compliance effort |
| `pretorin recipe deactivate <id>...` | Remove recipe(s) from the active set |
| `pretorin recipe show <id>` | Show recipe detail and shadowing sources |
| `pretorin recipe new <id>` | Scaffold a new community recipe in the user folder |
| `pretorin recipe validate <id>` | Validate a recipe against the RFC 0001 contract |
| `pretorin recipe run <id>` | Run a recipe end-to-end (typically invoked by an agent) |
| `pretorin recipe execute <id>` | Run a recipe non-interactively with platform reads and declared writes |

### Work Plans

Inspect and manage the work plans agents author while orchestrating multi-step tasks. Plans are stored locally and track step-by-step progress across a workflow run.

| Command | Purpose |
|---------|---------|
| `pretorin plan list` | List stored plans (filter by `--state` / `--workflow`) |
| `pretorin plan show <id>` | Show a single plan's full details (full UUID or unique prefix) |
| `pretorin plan cancel <id>` | Cancel an active plan (`--reason`) |
| `pretorin plan prune` | Prune terminal plans older than N days (`--older-than-days`, default 30) |

### Customer-Managed Deployments

For self-hosted Pretorin installs, the `deployment` group manages the deployment identity, license lifecycle, and signed Flux reconciliation of the release channel. See [Customer-Managed Deployment Overview](docs/src/deployments/overview.md).

| Command | Purpose |
|---------|---------|
| `pretorin deployment identity show/ensure` | Print or create the non-secret deployment ID used for license requests |
| `pretorin deployment license request` | Build the non-secret payload to send to Pretorin for license issuance |
| `pretorin deployment license install` | Install or renew a license without restarting or redeploying Pretorin |
| `pretorin deployment license status` | Read redacted license state and deployment-wide system usage |
| `pretorin deployment flux bootstrap` | Bootstrap signed, registry-only Flux reconciliation |
| `pretorin deployment flux suspend/resume` | Hold or approve applying discovered stable release artifacts |
| `pretorin deployment flux status` | Machine-readable release source and component readiness |

Quick context checks:

```bash
pretorin context show --quiet
pretorin context show --quiet --check
```

`pretorin login` clears the stored active context when you switch API keys or platform endpoints, which helps prevent old localhost or deleted-system scope from leaking into a new environment.

## Artifact Authoring Rules

- Narrative and evidence markdown must be human-readable for auditors: no markdown headings, use lists/tables/code blocks/links.
- Markdown image embeds are temporarily disabled until platform-side file upload support is available.

## Configuration

Credentials are stored at `~/.pretorin/config.json`.

| Variable | Description |
|----------|-------------|
| `PRETORIN_API_KEY` | API key for platform access (overrides stored config) |
| `PRETORIN_PLATFORM_API_BASE_URL` | Platform REST API base URL (default: `https://platform.pretorin.com/api/v1/public`) |
| `PRETORIN_API_BASE_URL` | Backward-compatible alias for `PRETORIN_PLATFORM_API_BASE_URL` |
| `PRETORIN_MODEL_API_BASE_URL` | Model API base URL used by agent flows (default: `https://platform.pretorin.com/api/v1/public/model`) |
| `OPENAI_API_KEY` | Optional model key override for agent runtime |

See [Environment Variables](docs/src/reference/environment.md) for the full list (system/framework overrides, source providers, logging, telemetry, etc.).

## Documentation

Full documentation is built with [mdbook](https://rust-lang.github.io/mdBook/). To view it locally:

```bash
# Install mdbook (if you don't have it)
cargo install mdbook

# Serve the docs and open in your browser
cd docs && mdbook serve --open
```

This starts a local server at `http://localhost:3000` with live-reload.

To build static HTML without serving:

```bash
./tools/build-docs.sh
# Output is in docs/book/ and includes llms.txt / llms-full.txt
```

### Quick links

- [CLI reference](docs/src/cli/command-reference.md)
- [MCP integration guide](docs/src/mcp/overview.md)
- [Bundled skill guide](pretorin-skill/SKILL.md)
- [Contributing](CONTRIBUTING.md)
- [Trademarks](TRADEMARKS.md)

## Development

```bash
git clone https://github.com/pretorin-ai/pretorin-cli.git
cd pretorin-cli
uv pip install -e ".[dev]"
pytest
ruff check src/pretorin
ruff format --check src/pretorin
```

## License

Licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE).

The Apache-2.0 license applies to the source code in this repository. It does not grant rights to Pretorin trademarks, logos, or branding, and it does not change the separate terms that govern access to Pretorin-hosted platform services and data. See [TRADEMARKS.md](TRADEMARKS.md).
