pretorin

Pretorin

Compliance tools for developers. Integrate with AI agents or your CI pipeline.

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.

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

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.
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

uv tool install pretorin
pretorin login
pretorin skill install

Run the walkthrough:

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.

Authenticate with your Pretorin API key:

pretorin login

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

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.

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

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

Verify runtime setup:

pretorin agent doctor
pretorin agent install

Run an agent task:

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.

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:

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

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

Team setup via .mcp.json:

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

2. Codex CLI

Add to ~/.codex/config.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.

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.

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 parity lifecycle: preview_campaign, start_campaign, get_campaign, list_campaigns, resume_campaign, and cancel_campaign. Preview corresponds to CLI --dry-run; start requires explicit confirmation of the returned Plan ID and digest 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[campaign-runner]==0.29.5" alternative; MCP never executes or streams the terminal itself.

After installing the optional package extra, the minimal best-effort first run needs two Pretorin commands:

# Once per installation; omit --force for a fresh uv tool install.
uv tool install --force 'pretorin[campaign-runner]'

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

Use pretorin[builtin-agent,campaign-runner] when the same environment should support both interactive pretorin agent run sessions and Campaigns. The Campaign runner verifies its exact Hatchet SDK pin before resolving or installing native runtimes.

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.

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:

# 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

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.

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 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

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), and issue workflows. Run pretorin recipe list for the current set. Authoring docs live at docs/src/recipes/ and the contract spec at 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.

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:

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 for the full list (system/framework overrides, source providers, logging, telemetry, etc.).

Documentation

Full documentation is built with mdbook. To view it locally:

# 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:

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

Quick links

Development

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.

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.

Release files for pretorin 0.29.5

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pretorin 0.29.5
File	Size	Uploaded
pretorin-0.29.5.tar.gz	5.2 MB	Sep 10, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for pretorin 0.29.5
File	Interpreter	ABI	Platform	Reset
pretorin-0.29.5-py3-none-any.whl 1.3 MB Sep 10, 2026	Python 3	none	any	Details

Total release size: 6.5 MB

Release files / pretorin-0.29.5.tar.gz

Download URL	pretorin-0.29.5.tar.gz
Size	5.2 MB
Tags	Source
SHA-256 checksum How to use checksums	`4f9373a9e42e7ef53af082ff1d3eb91f1664885928e295dd87d62d8836c42394`
BLAKE2b-256 checksum How to use checksums	`cff0f9cd1672e8decae2a3f5413f64f40d5a0aae3d9f8535dabee4f73723a488`
Upload date	Sep 10, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Release files / pretorin-0.29.5-py3-none-any.whl

Download URL	pretorin-0.29.5-py3-none-any.whl
Size	1.3 MB
Tags	Python 3
SHA-256 checksum How to use checksums	`ab02158ecd9bbb298416251852651cc40fe22a746e86bcd555471be5fa79405c`
BLAKE2b-256 checksum How to use checksums	`617f6c3fcd57b22872a30c6bdcea135e424711d76d605ccfa4bbaee6e65bf18f`
Upload date	Sep 10, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`