{"id":46356563,"url":"https://github.com/pretorin-ai/pretorin-cli","last_synced_at":"2026-05-30T01:04:02.911Z","repository":{"id":336305660,"uuid":"1138644045","full_name":"pretorin-ai/pretorin-cli","owner":"pretorin-ai","description":"This is the cli utility for the pretorin compliance platform. It is used to access the api directly or with an mcp/skill","archived":false,"fork":false,"pushed_at":"2026-05-23T23:59:01.000Z","size":12470,"stargazers_count":5,"open_issues_count":0,"forks_count":3,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-05-24T01:21:05.700Z","etag":null,"topics":["cli","compliance","compliance-automation","mcp"],"latest_commit_sha":null,"homepage":"https://pretorin.com","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pretorin-ai.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-01-20T23:55:13.000Z","updated_at":"2026-05-23T23:58:19.000Z","dependencies_parsed_at":null,"dependency_job_id":"d9a3e97d-416e-4b95-a4f0-c801d1ff6c56","html_url":"https://github.com/pretorin-ai/pretorin-cli","commit_stats":null,"previous_names":["pretorin-ai/pretorin-cli"],"tags_count":68,"template":false,"template_full_name":null,"purl":"pkg:github/pretorin-ai/pretorin-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pretorin-ai%2Fpretorin-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pretorin-ai%2Fpretorin-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pretorin-ai%2Fpretorin-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pretorin-ai%2Fpretorin-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pretorin-ai","download_url":"https://codeload.github.com/pretorin-ai/pretorin-cli/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pretorin-ai%2Fpretorin-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33676192,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-29T02:00:06.066Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","compliance","compliance-automation","mcp"],"created_at":"2026-03-05T00:26:52.773Z","updated_at":"2026-05-30T01:04:02.899Z","avatar_url":"https://github.com/pretorin-ai.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/Logo_White+Orange.png\" alt=\"Pretorin\" width=\"400\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eCompliance tools for developers. Integrate with AI agents or your CI pipeline.\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://pypi.org/project/pretorin/\"\u003e\u003cimg src=\"https://img.shields.io/pypi/v/pretorin\" alt=\"PyPI version\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://registry.modelcontextprotocol.io/\"\u003e\u003cimg src=\"https://img.shields.io/badge/MCP_Registry-Listed-green\" alt=\"MCP Registry\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://modelcontextprotocol.io\"\u003e\u003cimg src=\"https://img.shields.io/badge/MCP-Compatible-green\" alt=\"MCP Compatible\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://opensource.org/licenses/Apache-2.0\"\u003e\u003cimg src=\"https://img.shields.io/badge/License-Apache%202.0-yellow.svg\" alt=\"License: Apache-2.0\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/pretorin-ai/pretorin-cli/actions\"\u003e\u003cimg src=\"https://github.com/pretorin-ai/pretorin-cli/actions/workflows/test.yml/badge.svg\" alt=\"Tests\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.python.org/downloads/\"\u003e\u003cimg src=\"https://img.shields.io/badge/python-3.10%2B-blue\" alt=\"Python 3.10+\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n\u003e **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/).\n\nPretorin CLI gives developers and AI agents direct access to compliance data, implementation context, and evidence workflows.\n\nThe 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.\n\n`mcp-name: io.github.pretorin-ai/pretorin`\n\n## Two Usage Modes\n\n1. Pretorin-hosted model mode: run `pretorin agent run` and route model calls through Pretorin `/v1` endpoints.\n2. 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.).\n\n## Quick Start\n\n```bash\nuv tool install pretorin\npretorin login\npretorin skill install\n```\n\nRun the walkthrough:\n\n```bash\nbash tools/demo-walkthrough.sh\n```\n\n## Hosted Model Workflow (Recommended)\n\nUse this flow when you want `pretorin agent run` to go through Pretorin-hosted model endpoints.\n\n1. Authenticate with your Pretorin API key:\n\n```bash\npretorin login\n```\n\n2. Optional: point model traffic to a custom/self-hosted Pretorin endpoint:\n\n```bash\npretorin config set model_api_base_url https://platform.pretorin.com/api/v1/public/model\n```\n\n3. Verify runtime setup:\n\n```bash\npretorin agent doctor\npretorin agent install\n```\n\n4. Run an agent task:\n\n```bash\npretorin agent run \"Assess AC-2 implementation gaps for my system\"\n```\n\nKey behavior:\n- Preferred setup is `pretorin login` with no shell-level `OPENAI_API_KEY` override.\n- Model key precedence is: `OPENAI_API_KEY` -\u003e `config.api_key` -\u003e `config.openai_api_key`.\n- If `OPENAI_API_KEY` is set in your shell, it overrides stored login credentials.\n\n## Add to Your AI Tool\n\nUse this flow when you already have an AI agent/tool and want Pretorin as an MCP capability provider.\n\n\u003cimg src=\"assets/Rome-bot_Basic-1.png\" alt=\"Rome-bot\" width=\"120\" align=\"right\"\u003e\n\n### Install the Skill\n\nThe Pretorin skill teaches your AI agent how to use MCP tools effectively for compliance workflows. Install it for Claude Code and/or Codex CLI:\n\n```bash\npretorin skill install                # both agents\npretorin skill install --agent claude # claude only\npretorin skill install --agent codex  # codex only\npretorin skill status                 # check what's installed\n```\n\n### 1. Claude Code\n\n```bash\nclaude mcp add --transport stdio pretorin -- pretorin mcp-serve\n```\n\nTeam setup via `.mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"pretorin\": {\n      \"type\": \"stdio\",\n      \"command\": \"pretorin\",\n      \"args\": [\"mcp-serve\"]\n    }\n  }\n}\n```\n\n### 2. Codex CLI\n\nAdd to `~/.codex/config.toml`:\n\n```toml\n[mcp_servers.pretorin]\ncommand = \"pretorin\"\nargs = [\"mcp-serve\"]\n```\n\nIf 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.\n\nFor Claude Desktop, Cursor, and Windsurf setup, see [docs/MCP.md](docs/MCP.md).\n\n## Core Commands\n\nPlatform-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.\n\n| Command | Purpose |\n|---------|---------|\n| `pretorin login` | Authenticate with the Pretorin API |\n| `pretorin logout` | Clear stored credentials |\n| `pretorin whoami` | Show current authenticated user |\n| `pretorin frameworks list` | List available frameworks |\n| `pretorin frameworks control \u003cframework\u003e \u003ccontrol\u003e` | Get control details and guidance |\n| `pretorin context set` | Set active system/framework context |\n| `pretorin context show` | Inspect and validate the active context |\n| `pretorin context clear` | Clear the active context |\n| `pretorin control status` | Start/reopen control authoring with `in_progress` |\n| `pretorin control context` | Get full control context for the active scope |\n| `pretorin evidence create` | Create local evidence file |\n| `pretorin evidence list` | List local evidence files |\n| `pretorin evidence push` | Push local evidence to Pretorin |\n| `pretorin evidence search` | Search platform evidence |\n| `pretorin evidence link` | Link evidence to a control |\n| `pretorin evidence link-cci` | Link evidence to a CCI implementation row |\n| `pretorin evidence link-stig` | Link evidence to a STIG rule workflow |\n| `pretorin evidence upsert \u003cctrl\u003e \u003cfw\u003e` | Find-or-create evidence and link it |\n| `pretorin evidence mark-current \u003cid\u003e` | Re-affirm evidence freshness (bump `expires_at`, transition expired→valid) |\n| `pretorin evidence validate \u003cid\u003e` | Validate freshness against recorded source provenance; mark-current if unchanged, replace artifact + send drift note if changed |\n| `pretorin evidence upload` | Upload a file as evidence to the platform |\n| `pretorin evidence delete` | Delete an evidence record |\n| `pretorin narrative create` | Create local narrative file |\n| `pretorin narrative list` | List local narrative files |\n| `pretorin narrative push` | Push local narratives to Pretorin |\n| `pretorin narrative get \u003cctrl\u003e \u003cfw\u003e` | Get current control narrative |\n| `pretorin narrative push-file \u003cctrl\u003e \u003cfw\u003e \u003csys\u003e \u003cfile\u003e` | Push a single narrative file |\n| `pretorin issues create` | Create local issue file |\n| `pretorin issues list --local` | List local issue files |\n| `pretorin issues push` | Push local issues to Pretorin |\n| `pretorin issues list \u003cctrl\u003e \u003cfw\u003e` | List platform control issues |\n| `pretorin issues add \u003cctrl\u003e \u003cfw\u003e --content ...` | Add control issue directly |\n| `pretorin issues resolve \u003cctrl\u003e \u003cfw\u003e \u003cissue_id\u003e --resolution-note ...` | Resolve (close) a control issue |\n| `pretorin notes ...` | Deprecated compatibility alias for issue workflows |\n| `pretorin monitoring push` | Push a monitoring event |\n| `pretorin agent run \"\u003ctask\u003e\"` | Run Codex-powered compliance task |\n| `pretorin review run --control-id \u003cid\u003e --path \u003cdir\u003e` | Review local code for control coverage |\n| `pretorin skill install` | Install Pretorin skill for AI agents |\n| `pretorin skill status` | Check skill install status per agent |\n| `pretorin mcp-serve` | Start MCP server |\n\n### Campaign Workflows\n\nCampaigns let you run bulk compliance operations across multiple controls, policies, or scope questions in a single coordinated run. Campaigns support an external-agent-first pattern with checkpoint persistence and lease-based concurrency.\n\n| Command | Purpose |\n|---------|---------|\n| `pretorin campaign controls --mode initial --family AC` | Draft narratives/evidence for a control family |\n| `pretorin campaign controls --mode issues-fix --all-open-issues` | Fix controls flagged by platform issues |\n| `pretorin campaign controls --mode notes-fix --family AC` | Deprecated alias for issue-fix behavior |\n| `pretorin campaign controls --mode review-fix --family AC` | Fix controls flagged by family review |\n| `pretorin campaign policy --mode answer --all-incomplete` | Answer all incomplete policy questions |\n| `pretorin campaign scope --mode answer` | Answer scope questions for a system/framework |\n| `pretorin campaign status --checkpoint \u003cpath\u003e` | Check campaign progress |\n\n### Vendor Management \u0026 Inheritance\n\nManage vendor entities (CSPs, SaaS, managed services) and track control inheritance through vendor responsibility edges.\n\n| Command | Purpose |\n|---------|---------|\n| `pretorin vendor list` | List all vendors |\n| `pretorin vendor create \u003cname\u003e --type csp` | Create a vendor entity |\n| `pretorin vendor get \u003cid\u003e` | Get vendor details |\n| `pretorin vendor upload-doc \u003cid\u003e \u003cfile\u003e` | Upload vendor evidence document |\n| `pretorin vendor list-docs \u003cid\u003e` | List vendor documents |\n\n### Risk Management\n\nPopulate 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.\n\n| Command | Purpose |\n|---------|---------|\n| `pretorin risk list \u003csystem_id\u003e` | List risks for a system (filter by category, level, status) |\n| `pretorin risk show \u003csystem_id\u003e \u003crisk_id\u003e` | Show full risk including artifact links |\n| `pretorin risk create \u003csystem_id\u003e --title ...` | Create a risk; pass `--framework` for control auto-link |\n| `pretorin risk seed \u003csystem_id\u003e` | Seed risks from library templates |\n| `pretorin risk update \u003csystem_id\u003e \u003crisk_id\u003e` | Update fields including `--treatment` (mitigation surface) |\n| `pretorin risk link add \u003csystem_id\u003e \u003crisk_id\u003e` | Attach a control / evidence / finding / vendor to a risk |\n| `pretorin risk link rm \u003csystem_id\u003e \u003crisk_id\u003e \u003clink_id\u003e` | Remove a risk artifact link |\n| `pretorin risk refresh-summary \u003csystem_id\u003e \u003crisk_id\u003e` | Re-score risk and trigger best-effort AI summary |\n| `pretorin risk library list` | Browse the org-level template library |\n\n### Policy \u0026 Scope Questionnaires\n\nStateful questionnaire workflows for organization policies and system scope. Answer questions interactively or in bulk via campaigns.\n\n| Command | Purpose |\n|---------|---------|\n| `pretorin policy list` | List organization policies |\n| `pretorin policy show \u003cpolicy_id\u003e` | Show policy detail and questions |\n| `pretorin policy populate` | Auto-populate policy answers from context |\n| `pretorin scope show` | Show scope questionnaire for active context |\n| `pretorin scope populate` | Auto-populate scope answers from context |\n\n### STIG \u0026 CCI Browsing\n\nBrowse STIG benchmarks, rules, and CCIs with full traceability from NIST 800-53 controls down to individual STIG check rules.\n\n| Command | Purpose |\n|---------|---------|\n| `pretorin stig list` | List STIG benchmarks |\n| `pretorin stig show \u003cid\u003e` | Show STIG benchmark detail |\n| `pretorin stig rules \u003cid\u003e` | List rules for a benchmark |\n| `pretorin stig applicable` | Show applicable STIGs for active system |\n| `pretorin stig infer` | AI-infer applicable STIGs from system profile |\n| `pretorin cci list` | List CCIs with optional control filter |\n| `pretorin cci show \u003cid\u003e` | Show CCI detail with linked SRGs and rules |\n| `pretorin cci chain \u003ccontrol_id\u003e` | Full traceability: Control -\u003e CCIs -\u003e STIG rules |\n| `pretorin cci impl \u003ccci_uuid\u003e` | Show per-system CCI implementation (status, narrative, evidence) |\n\n### Custom Frameworks\n\nAuthor 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.\n\n| Command | Purpose |\n|---------|---------|\n| `pretorin frameworks init-custom \u003cid\u003e` | Scaffold a minimal valid `unified.json` template |\n| `pretorin frameworks validate-custom \u003cpath\u003e` | Local JSON Schema pre-flight before upload |\n| `pretorin frameworks build-custom \u003cinput\u003e -f \u003cid\u003e` | Auto-detect input shape and normalize to `unified.json` |\n| `pretorin frameworks upload-custom \u003cpath\u003e [--publish]` | POST a draft revision; `--publish` immediately promotes it |\n| `pretorin frameworks fork-framework \u003cupstream_id\u003e \u003cnew_id\u003e` | Create a linked-fork draft anchored on upstream |\n| `pretorin frameworks rebase-fork \u003cid\u003e` | Create a fresh rebase draft against the latest upstream |\n| `pretorin frameworks revisions \u003cid\u003e` | List draft and published revisions |\n| `pretorin frameworks export-oscal \u003cunified.json\u003e` | Regenerate an OSCAL catalog from a unified artifact |\n\n### Recipes\n\nRecipes are agent-executable playbooks bundled with pretorin (markdown + scripts) that the calling AI agent reads, plans against, and runs. Built-in recipes include OpenSCAP, InSpec, and AWS/Azure cloud baselines, manual attestation, and code-evidence capture. 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).\n\n| Command | Purpose |\n|---------|---------|\n| `pretorin recipe list` | List all loaded recipes (built-in + user + project) |\n| `pretorin recipe show \u003cid\u003e` | Show recipe detail and shadowing sources |\n| `pretorin recipe new \u003cid\u003e` | Scaffold a new community recipe in the user folder |\n| `pretorin recipe validate \u003cid\u003e` | Validate a recipe against the RFC 0001 contract |\n| `pretorin recipe run \u003cid\u003e` | Run a recipe end-to-end (typically invoked by an agent) |\n\nQuick context checks:\n\n```bash\npretorin context show --quiet\npretorin context show --quiet --check\n```\n\n`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.\n\n## Artifact Authoring Rules\n\n- Narrative and evidence markdown must be human-readable for auditors: no markdown headings, use lists/tables/code blocks/links.\n- Markdown image embeds are temporarily disabled until platform-side file upload support is available.\n\n## Configuration\n\nCredentials are stored at `~/.pretorin/config.json`.\n\n| Variable | Description |\n|----------|-------------|\n| `PRETORIN_API_KEY` | API key for platform access (overrides stored config) |\n| `PRETORIN_PLATFORM_API_BASE_URL` | Platform REST API base URL (default: `https://platform.pretorin.com/api/v1/public`) |\n| `PRETORIN_API_BASE_URL` | Backward-compatible alias for `PRETORIN_PLATFORM_API_BASE_URL` |\n| `PRETORIN_MODEL_API_BASE_URL` | Model API base URL used by agent flows (default: `https://platform.pretorin.com/api/v1/public/model`) |\n| `OPENAI_API_KEY` | Optional model key override for agent runtime |\n\nSee [Environment Variables](docs/src/reference/environment.md) for the full list (system/framework overrides, source providers, logging, telemetry, etc.).\n\n## Documentation\n\nFull documentation is built with [mdbook](https://rust-lang.github.io/mdBook/). To view it locally:\n\n```bash\n# Install mdbook (if you don't have it)\ncargo install mdbook\n\n# Serve the docs and open in your browser\ncd docs \u0026\u0026 mdbook serve --open\n```\n\nThis starts a local server at `http://localhost:3000` with live-reload.\n\nTo build static HTML without serving:\n\n```bash\n./tools/build-docs.sh\n# Output is in docs/book/ and includes llms.txt / llms-full.txt\n```\n\n### Quick links\n\n- [CLI reference](docs/src/cli/command-reference.md)\n- [MCP integration guide](docs/src/mcp/overview.md)\n- [Bundled skill guide](pretorin-skill/SKILL.md)\n- [Contributing](CONTRIBUTING.md)\n- [Trademarks](TRADEMARKS.md)\n\n## Development\n\n```bash\ngit clone https://github.com/pretorin-ai/pretorin-cli.git\ncd pretorin-cli\nuv pip install -e \".[dev]\"\npytest\nruff check src/pretorin\nruff format --check src/pretorin\n```\n\n## License\n\nLicensed under the Apache License, Version 2.0. See [LICENSE](LICENSE).\n\nThe 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).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpretorin-ai%2Fpretorin-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpretorin-ai%2Fpretorin-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpretorin-ai%2Fpretorin-cli/lists"}