Skip to main content

Command Reference

Complete reference for all Rafter local security and MCP commands.

rafter agent init

Initialize local security system.

Options

The legacy --with-gitleaks, --engine gitleaks, and rafter agent update-gitleaks flags were removed in v0.8.0. Use the -betterleaks equivalents. rafter agent verify and rafter agent status still detect a leftover ~/.rafter/bin/gitleaks and tell you to run rafter agent update-betterleaks.

What It Does

  1. Creates ~/.rafter/config.json configuration
  2. Initializes directory structure (~/.rafter/)
  3. Detects installed development environments (~/.claude, ~/.codex, ~/.gemini, etc.)
  4. Installs opted-in integrations (skills, hooks, sub-agents, per-skill rules, or MCP server configs)
  5. Downloads Betterleaks binary if --with-betterleaks or --all is passed

Examples


rafter agent init-project

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

Options

What It Does

Creates instruction files in the current project for all 7 supported agent platforms: Each file contains a Rafter security context block with scanning commands, integration tips, and CLI reference pointers. Files use marker comments (<!-- rafter:start/end -->) for idempotent updates — safe to re-run without duplicating content.

Examples

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

rafter secrets

Note: rafter agent scan still works but is deprecated — it will be removed in a future major version.
Scan files or directories for secrets.

Arguments

Options

Exit Codes

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

Examples

Detected Patterns

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.

Arguments

Options

Command Risk Levels

  • rm -rf /
  • :(){ :|:& };: (fork bomb)
  • dd if=/dev/zero of=/dev/sda
  • > /dev/sda
  • mkfs.*
  • fdisk, parted
  • rm -rf <dir>
  • sudo rm
  • chmod 777
  • curl ... | sh
  • git push --force
  • npm publish
  • docker system prune
  • sudo
  • chmod
  • chown
  • kill -9
  • systemctl
  • npm install
  • git commit
  • File read operations (ls, cat, grep)
  • Basic file operations (echo, touch)

Examples

Pre-Execution Scanning

For all commands, Rafter first evaluates the command against risk rules. For git commands (git commit, git push), it additionally:
  1. Gets list of staged files
  2. Scans each file for secrets
  3. Blocks if secrets detected
  4. Allows if clean
Skip with --skip-scan if needed.

rafter agent config

Manage agent configuration.

Subcommands

show

Display full configuration:

get <key>

Get specific configuration value:
Example:

set <key> <value>

Set configuration value:
Example:

Configuration Keys

Examples


rafter agent audit

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

Options

Event Types

Examples

Output Format


rafter agent verify

Check local security integration status across all 8 supported platforms.

What It Does

Validates your Rafter setup by checking 10 things in order:
  1. Config~/.rafter/config.json exists and is valid JSON
  2. Betterleaks — Binary available on PATH or at ~/.rafter/bin/betterleaks (legacy ~/.rafter/bin/gitleaks is detected and surfaced as an “upgrade needed” hint, not an error)
  3. Claude Code~/.claude/settings.json has PreToolUse hooks installed (optional)
  4. OpenClaw~/.openclaw/workspace/skills/rafter-security/SKILL.md exists with ClawHub frontmatter (optional)
  5. Codex CLI~/.agents/skills/rafter/SKILL.md and ~/.agents/skills/rafter-agent-security/SKILL.md exist (optional)
  6. Gemini CLI — MCP server configured for Gemini (optional)
  7. Cursor — hooks + per-skill rules + sub-agent installed (optional)
  8. Windsurf — per-skill rules + AGENTS.md + MCP entry installed (optional)
  9. Continue.dev — MCP entry + per-skill rules installed (optional)
  10. AiderRAFTER.md present and listed in .aider.conf.yml’s read: (optional)
Config and Betterleaks are hard requirements (failure → exit 1). Everything else is an optional integration (failure → warning only, exit 0).

Options

Exit Codes

Examples

Run rafter agent verify after rafter agent init to confirm everything installed correctly, and after system updates to catch binary incompatibilities. Use --probe in CI/post-install to catch hook regressions that file-presence checks miss.

rafter agent status

Show a live dashboard of your Rafter local security setup.

What It Shows

Example Output


rafter agent install-hook

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

Options

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 secrets --staged. If secrets are detected the commit is blocked. Pass git commit --no-verify to bypass (not recommended).

Examples


rafter agent audit-skill

Security audit of a Claude Code or OpenClaw skill file.

Arguments

Options

What It Does

Performs deterministic security analysis on the skill file:
  1. Secret detection — Scans for hardcoded API keys, tokens, and credentials
  2. URL extraction — Lists all external HTTP/HTTPS URLs
  3. 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

Examples

JSON Output


rafter ci init

Generate CI/CD workflow files for your project.

Options

What It Does

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

Examples


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.

Arguments

Topics

Examples

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.

Options

Tools Provided

Resources Provided

MCP Client Config

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

Options


rafter completion

Generate shell completion scripts for rafter.

Arguments

Setup


Global Flags

Available on all commands:

Environment Variables


File Locations


Exit Codes

Local Security (rafter agent *, rafter secrets)

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


Support

Need Help?