Command Reference

Complete reference for all Rafter local security and MCP commands.

`rafter agent init`

Initialize local security system.

rafter agent init [options]

Options

Flag	Description	Default
`--risk-level <level>`	Set risk level: `minimal`, `moderate`, `aggressive`	`moderate`
`--with-openclaw`	Install OpenClaw integration	false
`--with-claude-code`	Install Claude Code integration (hooks + skills)	false
`--with-codex`	Install Codex CLI integration (skills)	false
`--with-gemini`	Install Gemini CLI integration (MCP server)	false
`--with-cursor`	Install Cursor integration (MCP server)	false
`--with-windsurf`	Install Windsurf integration (MCP server)	false
`--with-continue`	Install Continue.dev integration (MCP server)	false
`--with-aider`	Install Aider integration (MCP server)	false
`--with-gitleaks`	Download and install Gitleaks binary	false
`--all`	Install all detected integrations and download Gitleaks	false
`-i, --interactive`	Guided setup — prompts for each detected integration	false
`--update`	Re-download gitleaks and reinstall integrations without resetting config	false

What It Does

Creates ~/.rafter/config.json configuration
Initializes directory structure (~/.rafter/)
Detects installed development environments (~/.claude, ~/.codex, ~/.gemini, etc.)
Installs opted-in integrations (skills, hooks, or MCP server configs)
Downloads Gitleaks binary if --with-gitleaks or --all is passed

Examples

# Basic initialization (config only, no integrations)
rafter agent init

# Install all detected integrations
rafter agent init --all

# Set aggressive security from start
rafter agent init --risk-level aggressive --all

# Install only Claude Code integration
rafter agent init --with-claude-code

# Install only Codex CLI integration
rafter agent init --with-codex

# Re-download Gitleaks and reinstall
rafter agent init --all --update

`rafter agent init-project`

Generate project-level instruction files so AI agents discover Rafter at session start.

rafter agent init-project [options]

Options

Flag	Description
`--only <platforms>`	Comma-separated list of platforms to generate for
`--list`	Dry-run — show which files would be created without writing them

What It Does

Creates instruction files in the current project for all 7 supported agent platforms:

Platform	File Created
Claude Code	`.claude/CLAUDE.md`
Codex CLI	`AGENTS.md`
Gemini CLI	`GEMINI.md`
Cursor	`.cursor/rules/rafter-security.mdc`
Windsurf	`.windsurfrules`
Continue.dev	`.continuerules`
Aider	`.aider/conventions.md`

Each file contains a Rafter security context block with scanning commands, integration tips, and CLI reference pointers. Files use marker comments () for idempotent updates — safe to re-run without duplicating content.

Examples

# Generate for all platforms
rafter agent init-project

# Preview what would be created
rafter agent init-project --list

# Generate only for specific platforms
rafter agent init-project --only claude-code,cursor

# Generate for a single platform
rafter agent init-project --only codex

Commit the generated files so every contributor’s agent session sees Rafter security context automatically.

`rafter scan local`

Note: rafter agent scan still works but is deprecated — it will be removed in a future major version.

Scan files or directories for secrets.

rafter scan local [path] [options]

Arguments

Argument	Description	Default
`path`	File or directory to scan	`.` (current directory)

Options

Flag	Description
`-q, --quiet`	Only output if secrets found
`--json`	Output results as JSON (alias for `--format json`)
`--format <type>`	Output format: `text` (default), `json`, or `sarif`
`--staged`	Scan only git-staged files
`--diff <ref>`	Scan only files changed since a git ref (e.g. `HEAD~1`, `main`)
`--engine <type>`	Scan engine: `patterns`, `gitleaks`, or `auto` (default)
`--baseline`	Filter findings present in the saved baseline
`--watch`	Watch for file changes and re-scan on change

Exit Codes

0 - No secrets found
1 - Secrets detected
2 - Runtime error (path not found, not a git repo, invalid ref)

Examples

# Scan current directory
rafter scan local

# Scan specific file
rafter scan local ./config.js

# Scan with JSON output
rafter scan local --json > results.json

# CI/CD usage (quiet mode)
rafter scan local --quiet || exit 1

# Scan only changed files
rafter scan local --diff main

# Use Gitleaks engine
rafter scan local --engine gitleaks

# Watch for changes and re-scan
rafter scan local --watch .

Detected Patterns

View All 21+ Secret Types

Cloud Providers:

AWS Access Keys (AKIA...)
AWS Secret Keys
Google API Keys (AIza...)
Google OAuth credentials

Version Control:

GitHub Personal Access Tokens (ghp_...)
GitHub OAuth Tokens (gho_...)
GitHub App Tokens (ghu_..., ghs_...)
GitHub Refresh Tokens (ghr_...)

Payment & SaaS:

Stripe API Keys (sk_live_..., rk_live_...)
Slack Tokens (xox[baprs]-...)
Slack Webhooks
Twilio API Keys (SK...)

Package Registries:

npm Access Tokens (npm_...)
PyPI API Tokens (pypi-...)

General:

Database connection strings
Private keys (RSA, DSA, EC, OpenSSH)
JWT tokens
Bearer tokens
Generic API keys
Generic secrets/passwords

`rafter agent exec`

Execute command with security validation.

rafter agent exec <command> [options]

Arguments

Argument	Description
`command`	Shell command to execute

Options

Flag	Description
`--skip-scan`	Skip pre-execution file scanning
`--force`	Skip approval prompts (logged in audit)

Command Risk Levels

🔴 Critical (Always Blocked)

rm -rf /
:(){ :|:& };: (fork bomb)
dd if=/dev/zero of=/dev/sda
> /dev/sda
mkfs.*
fdisk, parted

🟠 High (Requires Approval)

rm -rf <dir>
sudo rm
chmod 777
curl ... | sh
git push --force
npm publish
docker system prune

🟡 Medium (Moderate+ Requires Approval)

sudo
chmod
chown
kill -9
systemctl

🟢 Low (Allowed)

npm install
git commit
File read operations (ls, cat, grep)
Basic file operations (echo, touch)

Examples

# Safe command - executes immediately
rafter agent exec "npm test"

# Git commit - evaluates risk, then scans staged files
rafter agent exec "git commit -m 'Add feature'"

# High-risk - requires approval
rafter agent exec "sudo systemctl restart nginx"

# Force execution (skip approval, logged)
rafter agent exec "git push --force" --force

# Skip file scanning
rafter agent exec "git commit -m 'Fix typo'" --skip-scan

Pre-Execution Scanning

For all commands, Rafter first evaluates the command against risk rules. For git commands (git commit, git push), it additionally:

Gets list of staged files
Scans each file for secrets
Blocks if secrets detected
Allows if clean

Skip with --skip-scan if needed.

`rafter agent config`

Manage agent configuration.

rafter agent config <subcommand> [options]

Subcommands

`show`

Display full configuration:

rafter agent config show

`get <key>`

Get specific configuration value:

rafter agent config get <key>

Example:

rafter agent config get agent.riskLevel
# Output: moderate

`set <key> <value>`

Set configuration value:

rafter agent config set <key> <value>

Example:

rafter agent config set agent.riskLevel aggressive

Configuration Keys

Key	Type	Options	Description
`agent.riskLevel`	string	`minimal`, `moderate`, `aggressive`	Overall security stance
`agent.commandPolicy.mode`	string	`allow-all`, `approve-dangerous`, `deny-list`	Command handling mode
`agent.commandPolicy.blockedPatterns`	array	-	Always-blocked command patterns
`agent.commandPolicy.requireApproval`	array	-	Patterns requiring approval
`agent.outputFiltering.redactSecrets`	boolean	`true`, `false`	Redact secrets in output
`agent.audit.logAllActions`	boolean	`true`, `false`	Log all security events
`agent.audit.retentionDays`	number	-	Log retention period (days)
`agent.audit.logLevel`	string	`debug`, `info`, `warn`, `error`	Log verbosity
`agent.notifications.webhook`	string	-	Webhook URL to POST notifications to
`agent.notifications.minRiskLevel`	string	`"high"`, `"critical"`	Minimum risk level to trigger notification

Examples

# View all config
rafter agent config show

# Get risk level
rafter agent config get agent.riskLevel

# Set to aggressive
rafter agent config set agent.riskLevel aggressive

# Change policy mode
rafter agent config set agent.commandPolicy.mode deny-list

# Enable secret redaction
rafter agent config set agent.outputFiltering.redactSecrets true

# Set log retention
rafter agent config set agent.audit.retentionDays 60

# Configure webhook notifications
rafter agent config set agent.notifications.webhook https://hooks.slack.com/services/T.../B.../xxx
rafter agent config set agent.notifications.minRiskLevel critical

`rafter agent audit`

View security audit logs. For the full JSONL schema specification, see Audit Log.

rafter agent audit [options]

Options

Flag	Description	Default
`--last <n>`	Show last N entries	`10`
`--event <type>`	Filter by event type	-
`--agent <type>`	Filter by agent (`openclaw`, `claude-code`)	-
`--since <date>`	Show entries since date (YYYY-MM-DD)	-

Event Types

Event	Description
`command_intercepted`	Command execution attempt
`secret_detected`	Secret found in files
`content_sanitized`	Output redacted
`policy_override`	User override of policy
`scan_executed`	File scan performed
`config_changed`	Configuration modified

Examples

# Show recent logs
rafter agent audit

# Show last 20 entries
rafter agent audit --last 20

# Filter by event type
rafter agent audit --event command_intercepted

# Filter by agent
rafter agent audit --agent openclaw

# Show logs since date
rafter agent audit --since 2026-02-01

# Combine filters
rafter agent audit --event secret_detected --last 50

Output Format

🛡️ [2026-02-02 10:30:45] command_intercepted
   Agent: openclaw
   Command: git commit -m 'Add feature'
   Risk: medium
   Check: PASSED
   Action: allowed

🔑 [2026-02-02 10:25:12] secret_detected
   Agent: openclaw
   Risk: critical
   Check: FAILED
   Reason: AWS Access Key detected in config.js
   Action: blocked

`rafter agent verify`

Check local security integration status.

rafter agent verify

What It Does

Validates your Rafter setup by checking five things in order:

Config — ~/.rafter/config.json exists and is valid JSON
Gitleaks — Binary available on PATH or at ~/.rafter/bin/gitleaks
Claude Code — ~/.claude/settings.json has PreToolUse hooks installed (optional)
OpenClaw — ~/.openclaw/skills/rafter-security.md exists (optional)
Codex CLI — ~/.agents/skills/rafter/SKILL.md and ~/.agents/skills/rafter-agent-security/SKILL.md exist (optional)
Gemini CLI — MCP server configured for Gemini (optional)

Config and Gitleaks are hard requirements (failure → exit 1). Claude Code, OpenClaw, Codex, and Gemini are optional integrations (failure → warning only, exit 0).

Exit Codes

Code	Meaning
`0`	All required checks passed (optional checks may warn)
`1`	One or more required checks failed

Examples

# Run health check
rafter agent verify

# Example output (all passing):
# ✓ Config        ~/.rafter/config.json
# ✓ Gitleaks      8.21.0 (/usr/local/bin/gitleaks)
# ✓ Claude Code   PreToolUse hook installed
# ✓ OpenClaw      rafter-security.md skill present

# Example output (optional checks absent):
# ✓ Config        ~/.rafter/config.json
# ✓ Gitleaks      8.21.0 (/usr/local/bin/gitleaks)
# ⚠  Claude Code   Not detected — run: rafter agent init (optional)
# ⚠  OpenClaw      Not detected (optional)
# ⚠  Gemini CLI    Not detected (optional)

Run rafter agent verify after rafter agent init to confirm everything installed correctly, and after system updates to catch binary incompatibilities.

`rafter agent status`

Show a live dashboard of your Rafter local security setup.

rafter agent status

What It Shows

Section	Details
Config	Presence and validity of `~/.rafter/config.json`; risk level, audit log path
Gitleaks	Version string and binary path
Hooks	Whether `PreToolUse` and `PostToolUse` hooks are registered in Claude Code settings
OpenClaw	Whether the `rafter-security.md` skill is installed
Audit Log	Total event count + 5 most recent events (type, timestamp, risk)

Example Output

rafter agent status

# Rafter Agent Status
# ─────────────────────────────────
# Config:    ~/.rafter/config.json  (risk: medium)
# Gitleaks:  8.21.0  (/usr/local/bin/gitleaks)
# Hooks:     PreToolUse ✓  PostToolUse ✓
# OpenClaw:  rafter-security.md ✓
#
# Audit Log: 142 events
#   [2026-02-21 14:32] command_allowed      low
#   [2026-02-21 14:31] secret_detected      high
#   [2026-02-21 14:28] command_intercepted  critical
#   [2026-02-21 14:20] command_allowed      low
#   [2026-02-21 14:18] command_allowed      low

`rafter agent install-hook`

Install a git pre-commit hook that scans staged files for secrets before each commit.

rafter agent install-hook [options]

Options

Flag	Description	Default
`--global`	Install for all git repos on this machine	false (local only)

What It Does

Without --global (local install):

Writes hook to .git/hooks/pre-commit in the current repo
Backs up any existing hook before overwriting

With --global (global install):

Writes hook to ~/.rafter/git-hooks/pre-commit
Sets git config --global core.hooksPath ~/.rafter/git-hooks
Applies to every git repo on the machine

When git commit runs, the hook calls rafter scan local --staged. If secrets are detected the commit is blocked. Pass git commit --no-verify to bypass (not recommended).

Examples

# Install for current repo
rafter agent install-hook

# Install globally for all repos
rafter agent install-hook --global

# Remove global hook
git config --global --unset core.hooksPath

`rafter agent audit-skill`

Security audit of a Claude Code or OpenClaw skill file.

rafter agent audit-skill <skill-path> [options]

Arguments

Argument	Description
`<skill-path>`	Path to the skill file to audit (required)

Options

Flag	Description
`--skip-openclaw`	Skip OpenClaw integration; print manual review prompt instead
`--json`	Output results as JSON

What It Does

Performs deterministic security analysis on the skill file:

Secret detection — Scans for hardcoded API keys, tokens, and credentials
URL extraction — Lists all external HTTP/HTTPS URLs
High-risk command patterns — Detects 11 dangerous patterns: rm -rf /, sudo rm, curl|sh, wget|sh, eval(), exec(), chmod 777, fork bombs, dd /dev/xyz, mkfs, base64 -d|sh

If OpenClaw is available, the command routes the skill to the /rafter-audit-skill slash command for a deeper 12-dimension security review covering trust, network access, credential handling, obfuscation, supply chain, and more.

Exit Codes

Code	Meaning
`0`	No secrets or high-risk commands detected
`1`	Secrets or high-risk commands found

Examples

# Audit a skill file
rafter agent audit-skill ~/.claude/skills/github-integration/SKILL.md

# JSON output for scripting
rafter agent audit-skill skill.md --json

# Skip OpenClaw (prints manual review prompt)
rafter agent audit-skill skill.md --skip-openclaw

JSON Output

rafter agent audit-skill skill.md --json

{
  "skill": "skill.md",
  "path": "/absolute/path/to/skill.md",
  "quickScan": {
    "secrets": 0,
    "urls": ["https://api.example.com"],
    "highRiskCommands": []
  },
  "openClawAvailable": true,
  "rafterSkillInstalled": true
}

`rafter ci init`

Generate CI/CD workflow files for your project.

rafter ci init [options]

Options

Flag	Description	Default
`--platform <type>`	Target platform: `github`, `gitlab`, `circleci`	Auto-detected
`--output <path>`	Output file path	Platform default
`--with-backend`	Include API-based security audit job	false

What It Does

Detects your CI platform from project files (.github/, .gitlab-ci.yml, .circleci/)
Generates a workflow file with secret scanning and security checks
Optionally adds a backend scan job using the Rafter API

Examples

# Auto-detect platform and generate config
rafter ci init

# Generate GitHub Actions workflow
rafter ci init --platform github

# Include backend scanning job
rafter ci init --platform github --with-backend

`rafter brief`

Print rafter knowledge reformatted for CLI output. Designed for any agent on any platform — pipe to memory, save to instructions, or just read in-session.

rafter brief [topic]

Arguments

Argument	Description
`[topic]`	Topic to display (optional — lists available topics if omitted)

Topics

Topic	Description
`security`	Local security toolkit — scanning, auditing, policy enforcement
`scanning`	Remote SAST/SCA code analysis via Rafter API
`commands`	Condensed command reference for all rafter commands
`setup`	Setup instructions for all supported agent platforms
`setup/<platform>`	Platform-specific setup (claude-code, codex, gemini, cursor, windsurf, aider, openclaw, continue, generic)
`all`	Everything — full security + scanning + setup briefing

Examples

# List available topics
rafter brief

# Get the local security briefing
rafter brief security

# Platform-specific setup guide
rafter brief setup/claude-code

# For agents without native skill support — load context manually
rafter brief security    # save to memory/instructions
rafter brief commands    # save command reference

# Pipe to a file for manual skill creation
rafter brief scanning > ~/.agents/skills/rafter/SKILL.md

rafter brief works on any platform — use it to bootstrap agent knowledge when skill auto-install isn’t available.

`rafter mcp serve`

Start an MCP server exposing Rafter security tools over stdio transport. Works with any MCP-compatible client.

rafter mcp serve [options]

Options

Flag	Description	Default
`--transport <type>`	Transport type (`stdio`)	`stdio`

Tools Provided

Tool	Description	Required Params
`scan_secrets`	Scan for hardcoded secrets	`path`
`evaluate_command`	Check if command is allowed by policy	`command`
`read_audit_log`	Read audit log entries	(none)
`get_config`	Read Rafter configuration	(none)

Resources Provided

URI	Description
`rafter://config`	Current Rafter configuration
`rafter://policy`	Active security policy (merged `.rafter.yml` + config)

MCP Client Config

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

See MCP Integration for platform-specific setup.

`rafter hook pretool`

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

rafter hook pretool

Evaluates Bash tool calls against command policy and scans Write/Edit content for secrets. See Claude Code Integration for setup.

`rafter hook posttool`

PostToolUse hook handler for Claude Code. Reads tool result JSON from stdin, logs security-relevant events to the audit log.

rafter hook posttool

Logs completed Bash, Write, and Edit tool executions with their outcome and risk level. Useful for auditing what an agent actually did (vs. what was blocked at pretool). See Claude Code Integration for setup.

`rafter policy export`

Export Rafter security policy for agent platforms.

rafter policy export --format <claude|codex> [--output <path>]

Options

Flag	Description
`--format <type>`	Target format: `claude` (Claude Code hooks JSON) or `codex` (Codex rules TOML)
`--output <path>`	Write to file instead of stdout

`rafter completion`

Generate shell completion scripts for rafter.

rafter completion <shell>

Arguments

Argument	Description
`<shell>`	Target shell: `bash`, `zsh`, or `fish`

Setup

# Bash — add to ~/.bashrc
eval "$(rafter completion bash)"

# Zsh — add to ~/.zshrc
eval "$(rafter completion zsh)"

# Fish — saves directly to completions directory
rafter completion fish

Global Flags

Available on all commands:

Flag	Description
`-h, --help`	Display help for command
`-V, --version`	Output version number

Environment Variables

Variable	Description
`RAFTER_API_KEY`	API key for backend scanning
`RAFTER_GITHUB_TOKEN`	GitHub PAT for private repo scanning (needs `Contents:Read` scope)
`RAFTER_CONFIG_PATH`	Custom config file location

File Locations

Path	Description
`~/.rafter/config.json`	Configuration file
`~/.rafter/audit.jsonl`	Audit log (JSONL format, see Audit Log)
`~/.rafter/bin/`	Binary tools (Gitleaks, etc.)
`~/.rafter/patterns/`	Custom secret patterns (`.txt` or `.json`)
`~/.rafter/.rafterignore`	Findings suppression rules (path globs, optional `:pattern-name` qualifier)
`.rafter.yml`	Project-level policy file (see Policy File)
`~/.openclaw/skills/rafter-security.md`	OpenClaw skill file

Exit Codes

Local Security (`rafter agent *`, `rafter scan local`)

Code	Meaning
`0`	Success / no secrets found
`1`	Error or secrets found
`2`	Runtime error (path not found, not a git repo, invalid ref)

Remote Code Analysis (`rafter run`, `rafter get`, `rafter usage`)

Code	Meaning
`0`	Success
`1`	General error
`2`	Scan not found (HTTP 404)
`3`	Quota exhausted (HTTP 429 or 403 scan-mode limit)
`4`	Insufficient scope / forbidden (HTTP 403)

Support

Need Help?

Documentation: docs.rafter.so
GitHub: rafter-cli/issues
Support: rafter.so/help

Get Started

CLI Guides

Local Security

References

​Command Reference

​rafter agent init

​Options

​What It Does

​Examples

​rafter agent init-project

​Options

​What It Does

​Examples

​rafter scan local

​Arguments

​Options

​Exit Codes

​Examples

​Detected Patterns

​rafter agent exec

​Arguments

​Options

​Command Risk Levels

​Examples

​Pre-Execution Scanning

​rafter agent config

​Subcommands

​show

​get <key>

​set <key> <value>

​Configuration Keys

​Examples

​rafter agent audit

​Options

​Event Types

​Examples

​Output Format

​rafter agent verify

​What It Does

​Exit Codes

​Examples

​rafter agent status

​What It Shows

​Example Output

​rafter agent install-hook

​Options

​What It Does

​Examples

​rafter agent audit-skill

​Arguments

​Options

​What It Does

​Exit Codes

​Examples

​JSON Output

​rafter ci init

​Options

​What It Does

​Examples

​rafter brief

​Arguments

​Topics

​Examples

​rafter mcp serve

​Options

​Tools Provided

​Resources Provided

​MCP Client Config

​rafter hook pretool

​rafter hook posttool

​rafter policy export

​Options

​rafter completion

​Arguments

​Setup

​Global Flags

​Environment Variables

​File Locations

​Exit Codes

​Local Security (rafter agent *, rafter scan local)

Command Reference

`rafter agent init`

Options

What It Does

Examples

`rafter agent init-project`

Options

What It Does

Examples

`rafter scan local`

Arguments

Options

Exit Codes

Examples

Detected Patterns

`rafter agent exec`

Arguments

Options

Command Risk Levels

Examples

Pre-Execution Scanning

`rafter agent config`

Subcommands

`show`

`get <key>`

`set <key> <value>`

Configuration Keys

Examples

`rafter agent audit`

Options

Event Types

Examples

Output Format

`rafter agent verify`

What It Does

Exit Codes

Examples

`rafter agent status`

What It Shows

Example Output

`rafter agent install-hook`

Options

What It Does

Examples

`rafter agent audit-skill`

Arguments

Options

What It Does

Exit Codes

Examples

JSON Output

`rafter ci init`

Options

What It Does

Examples

`rafter brief`

Arguments

Topics

Examples

`rafter mcp serve`

Options

Tools Provided

Resources Provided

MCP Client Config

`rafter hook pretool`

`rafter hook posttool`

`rafter policy export`

Options

`rafter completion`

Arguments

Setup

Global Flags

Environment Variables

File Locations

Exit Codes

Local Security (`rafter agent *`, `rafter scan local`)

Remote Code Analysis (`rafter run`, `rafter get`, `rafter usage`)

Support