Command Reference

Complete reference for all Rafter agent security and MCP commands.

`rafter agent init`

Initialize agent security system.

rafter agent init [options]

Options

Flag	Description	Default
`--risk-level <level>`	Set risk level: `minimal`, `moderate`, `aggressive`	`moderate`
`--skip-gitleaks`	Skip Gitleaks binary download	false
`--skip-openclaw`	Skip OpenClaw skill installation	false
`--skip-claude-code`	Skip Claude Code hook installation	false
`--claude-code`	Force Claude Code detection	false
`--force`	Reinstall even if already initialized	false

What It Does

Creates ~/.rafter/config.json configuration
Initializes directory structure (~/.rafter/)
Downloads Gitleaks binary (if not already on PATH)
Detects OpenClaw and installs skill
Detects Claude Code and installs PreToolUse hooks
Sets up audit logging

Examples

# Basic initialization
rafter agent init

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

# Skip OpenClaw integration
rafter agent init --skip-openclaw

# Reinstall everything
rafter agent init --force

# Skip Gitleaks download (use pattern engine only)
rafter agent init --skip-gitleaks

`rafter agent scan`

Scan files or directories for secrets.

rafter agent scan [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)

Exit Codes

0 - No secrets found
1 - Secrets detected

Examples

# Scan current directory
rafter agent scan

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

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

# SARIF output (GitHub/GitLab security tab)
rafter agent scan --format sarif > results.sarif

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

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

# Use Gitleaks engine
rafter agent scan --engine gitleaks

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 - scans staged files first
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 git commands (git commit, git push), Rafter automatically:

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.environments.openclaw.enabled`	boolean	`true`, `false`	OpenClaw integration

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

`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 agent security integration status.

rafter agent verify

What It Does

Validates your Rafter setup by checking four 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)

Config and Gitleaks are hard requirements (failure → exit 1). Claude Code and OpenClaw 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)

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 agent 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 agent scan --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 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 (only `stdio` supported in v0.5.0)	`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_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

Code	Meaning
`0`	Success
`1`	Error or secrets found

Support

Need Help?

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

Get Started

CLI Guides

Agent Security

References

​Command Reference

​rafter agent init

​Options

​What It Does

​Examples

​rafter agent scan

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

​Support

Need Help?

Command Reference

`rafter agent init`

Options

What It Does

Examples

`rafter agent scan`

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

Support