Metadata-Version: 2.4
Name: rafter-cli
Version: 0.7.1
Summary: Rafter CLI — the default security agent for AI workflows. Free for individuals and open source.
License: MIT
Author: Rafter Team
Author-email: hello@rafter.so
Requires-Python: >=3.10,<4.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: click (>=8.0.0,<9.0.0)
Requires-Dist: mcp (>=1.9.0,<2.0.0)
Requires-Dist: python-dotenv (>=1.0.1,<2.0.0)
Requires-Dist: pyyaml (>=6.0.1,<7.0.0)
Requires-Dist: requests (>=2.31.0,<3.0.0)
Requires-Dist: rich (>=13.7.1,<14.0.0)
Requires-Dist: typer (>=0.15.0,<0.16.0)
Requires-Dist: urllib3 (>=2.6.0,<3)
Requires-Dist: watchdog (>=4.0.0,<5.0.0)
Description-Content-Type: text/markdown

# rafter-cli (Python)

Python CLI for [Rafter](https://rafter.so) — the security toolkit for developers. Full feature parity with the Node.js package.

**Local security toolkit** — Fast, deterministic secret scanning (21+ patterns, Gitleaks), policy enforcement with risk-tiered rules, pre-commit hooks, pretool hooks, extension auditing, custom rule authoring, and full audit logging. Works with Claude Code, Codex CLI, OpenClaw, and 5 more platforms. No API key required. No data leaves your machine.

**Remote code analysis** — Deep security audits that combine agentic analysis with a full SAST/SCA toolchain. The engine examines your codebase the way a professional cybersecurity auditor would — tracing data flows, reasoning about business logic, and surfacing vulnerabilities that static rules alone miss — then cross-references findings with industry-standard static analysis and dependency scanning. Structured JSON reports with documented exit codes. Your code is deleted immediately after analysis completes.

**MCP server** — Expose Rafter security tools to any MCP-compatible client (Cursor, Windsurf, Claude Desktop, Cline) over stdio.

## Installation

```bash
pip install rafter-cli
```

Requires Python 3.10+.

## Quick Start

### Backend Code Analysis

```bash
export RAFTER_API_KEY="your-key"   # or add to .env file

rafter run                                    # scan current repo (auto-detected)
rafter scan --repo myorg/myrepo --branch main # scan specific repo
rafter get SCAN_ID                            # retrieve results
rafter get SCAN_ID --interactive              # poll until complete
rafter usage                                  # check quota
```

**Important**: The code analysis engine runs against the **remote repository** on GitHub, not your local files. Your code is deleted immediately after analysis completes.

### Local Security

```bash
rafter agent init                # initialize config + detect environments
rafter agent init --all          # install all detected integrations
rafter agent scan .              # scan for secrets
rafter agent scan --diff HEAD~1  # scan changed files
rafter agent exec "git commit"   # execute with risk assessment
rafter agent audit               # view security logs
rafter agent config show         # view configuration
```

### Pretool Hooks (Claude Code)

```bash
rafter agent init --with-claude-code  # install PreToolUse hooks
rafter hook pretool              # hook handler (reads stdin, writes decision)
rafter policy export --format claude  # export hook config
```

### MCP Server

```bash
rafter mcp serve                 # start MCP server over stdio
```

Add to any MCP client config:

```json
{
  "rafter": {
    "command": "rafter",
    "args": ["mcp", "serve"]
  }
}
```

**Tools:** `scan_secrets`, `evaluate_command`, `read_audit_log`, `get_config`
**Resources:** `rafter://config`, `rafter://policy`

## Commands

### `rafter run [options]`

Alias: `rafter scan`

Trigger a new security scan for your repository.

- `-r, --repo <repo>` — org/repo (default: auto-detected from git remote)
- `-b, --branch <branch>` — branch (default: current branch or 'main')
- `-k, --api-key <key>` — API key (or `RAFTER_API_KEY` env var)
- `-f, --format <format>` — `json` or `md` (default: `md`)
- `--skip-interactive` — don't wait for scan completion
- `--quiet` — suppress status messages

### `rafter get <scan-id> [options]`

Retrieve results from a scan.

- `-k, --api-key <key>` — API key
- `-f, --format <format>` — `json` or `md` (default: `md`)
- `--interactive` — poll until scan completes
- `--quiet` — suppress status messages

### `rafter usage [options]`

Check API quota and usage.

- `-k, --api-key <key>` — API key

### `rafter mcp serve [options]`

Start MCP server over stdio transport.

- `--transport <type>` — Transport type (default: `stdio`)

### `rafter hook pretool`

PreToolUse hook handler. Reads tool input JSON from stdin, writes decision to stdout.

### `rafter policy export [options]`

Export Rafter policy for agent platforms.

- `--format <type>` — Target format: `claude` or `codex`
- `--output <path>` — Write to file instead of stdout

## Piping and Automation

```bash
# Filter high-severity vulnerabilities (SARIF levels: error, warning, note)
rafter get SCAN_ID --format json | jq '.vulnerabilities[] | select(.level=="error")'

# CI gate
if rafter get SCAN_ID --format json | jq -e '.vulnerabilities | length > 0'; then
    echo "Vulnerabilities found!" && exit 1
fi
```

## Exit Codes

| Code | Meaning |
|------|---------|
| 0 | Success |
| 1 | General error / secrets found |
| 2 | Scan not found |
| 3 | Quota exhausted |

## Documentation

Full docs at [docs.rafter.so](https://docs.rafter.so).

