Metadata-Version: 2.4
Name: pretorin
Version: 0.9.3
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/main/CHANGELOG.md
Project-URL: Issues, https://github.com/pretorin-ai/pretorin-cli/issues
Author-email: Pretorin <support@pretorin.com>
License: MIT
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 :: MIT 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: httpx>=0.25.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: tenacity>=8.0.0
Requires-Dist: typer>=0.9.0
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: dev
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.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/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 evidence to Pretorin |
| `pretorin evidence search` | Search platform evidence |
| `pretorin evidence upsert <ctrl> <fw>` | Find-or-create evidence and link it |
| `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 notes create` | Create local note file |
| `pretorin notes list --local` | List local note files |
| `pretorin notes push` | Push local notes to Pretorin |
| `pretorin notes list <ctrl> <fw>` | List platform control notes |
| `pretorin notes add <ctrl> <fw> --content ...` | Add control note directly |
| `pretorin monitoring push` | Push a monitoring event |
| `pretorin agent run "<task>"` | Run Codex-powered compliance task |
| `pretorin review run --control-id <id> --path <dir>` | Review local code for control coverage |
| `pretorin skill install` | Install Pretorin skill for AI agents |
| `pretorin skill status` | Check skill install status per agent |
| `pretorin mcp-serve` | Start MCP server |

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 (`/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/harness flows (default: `https://platform.pretorin.com/v1`) |
| `OPENAI_API_KEY` | Optional model key override for agent runtime |

## 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
cd docs && mdbook build
# Output is in docs/book/
```

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

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

MIT License. See [LICENSE](LICENSE).
