Pretorin Compliance

Install

Config snippet generator goes here (5 client tabs)

README

<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/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></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 everyone. 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.

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

## Two Usage Modes

1. Pretorin-hosted model mode: run `pretorin agent run` and route model calls through Pretorin `/v1` endpoints.
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 scripts/demo-walkthrough.sh
```

## Hosted Model Workflow (Recommended)

Use this flow when you want `pretorin agent run` to go through Pretorin-hosted model endpoints.

1. Authenticate with your Pretorin API key:

```bash
pretorin login
```

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

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

3. Verify runtime setup:

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

4. Run an agent task:

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

Key behavior:
- Preferred setup is `pretorin login` with no shell-level `OPENAI_API_KEY` override.
- Model key precedence is: `OPENAI_API_KEY` -> `config.api_key` -> `config.openai_api_key`.
- If `OPENAI_API_KEY` is set in your shell, it overrides stored login credentials.

## 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, note, monitoring, narrative, or MCP-assisted compliance commands inside that scope. Multi-framework work must be split into separate runs. Evidence, narratives, and notes all support a local-first workflow: create locally, list, then push to the platform.

| Command | Purpose |
|---------|---------|
| `pretorin frameworks list` | List available frameworks |
| `pretorin frameworks control <framework> <control>` | Get control details and guidance |
| `pretorin context set` | Set active system/framework context |
| `pretorin context show` | Inspect and validate the active context |
| `pretorin context clear` | Clear the active context |
| `pretorin evidence create` | Create local evidence file |
| `pretorin evidence list` | List local evidence files |
| `pretorin evidence push` | Push local evid