Getting Started with the CLI
The Rafter CLI provides a simple command-line interface for running security scans on your repositories. This guide covers the essential concepts and basic workflows.Core Concepts
How Do I get My API Key?
To use the Rafter CLI or API, you need an API key. Sign up and get your API key from your account page.What Does the CLI Do?
The Rafter CLI allows you to:- Run security audits of your remote repositories (
rafter runorrafter scan) — agentic deep dives backed by a full SAST/SCA toolchain - Choose scan depth with scan modes —
fastfor rapid SAST/SCA analysis,plusfor professional-grade agentic audits that trace data flows and reason about business logic - Retrieve results from completed scans
- Check usage and quota information
- Automate security workflows in scripts and CI/CD
- Enforce security locally with secret scanning and policy enforcement
How Does Scanning Work?
The CLI scans remote repositories (e.g., on GitHub), not your local files. It can use your local Git configuration to determine which repository and branch to scan.
- The CLI detects your repository and branch from Git
- It uploads your code securely to Rafter’s analysis engine
- The engine audits your code the way a professional penetration tester would — following data flows across files, reasoning about authentication and authorization logic, and identifying vulnerabilities that pattern-matching alone cannot catch — backed by industry-standard SAST, SCA, and secret-detection tooling
- Your code is deleted from Rafter’s engine immediately after analysis
- Results are returned and displayed in your terminal
Scan Modes
Rafter supports two scan modes, selected with the--mode (or -m) flag:
Plus is a paid tier that consumes credits. If your organization enables the approval gate —
scan.plus_requires_approval in .rafter.yml, or agent.scan.plusRequiresApproval in the global config — a Plus scan run without a TTY refuses with exit code 5 unless you pass -y/--yes or set RAFTER_CONFIRM=1. Fast scans are never gated. This is off by default.Basic Commands
Start a Scan with rafter run
The most common command for running security scans are below. They auto-detect the repo and branch and resolve the API key in this order: the -k/--api-key flag, then the RAFTER_API_KEY environment variable, then a key stored with rafter agent config set backend.apiKey <key>.
Retrieve Results with rafter get
Get results from a completed scan:
Check Quota with rafter usage
Check your API usage and remaining scans:
Basic Workflow
Here’s a typical workflow for running your first scan:1. Install the CLI
Node.js 22+ required for npm/pnpm/yarn installs (Rafter 0.11.1 and later; 0.11.0 supports Node 18+). Verify your version:Upgrade with nvm (
nvm install 22) or from nodejs.org.Python 3.11+ required for pip installs (Rafter 0.11.1 and later; 0.11.0 supports Python 3.10+). Verify your version:On Ubuntu/Debian, Python and pip may not be installed by default:On Fedora/RHEL:
sudo dnf install python3 python3-pip.
macOS: brew install python. Windows: install from python.org — pip is included.2. Set Your API Key
3. Run a Scan
4. Check Results
The CLI will display scan results directly in your terminal, showing:- Vulnerabilities found with severity levels
- File locations where issues were detected
- Recommendations for fixing the issues
Output Formats
The CLI supports two output formats, selected with-f/--format. The CLI default is md (Markdown) — pass --format json explicitly when you need structured output for scripting.
JSON Format
- Automation and scripting
- Integration with other tools
- Parsing with tools like
jq
Markdown Format (Default)
- Human-readable reports
- Documentation and sharing
- GitHub issues and pull requests
- LLM-assisted remediation — the report includes role-priming, step-by-step instructions, and structured issue metadata
Next Steps
CLI Basics
Learn the fundamentals of using the Rafter CLI.
Advanced CLI
Master advanced CLI features and automation.
API Reference
Build custom integrations with the REST API.
CI/CD Integration
Set up automated scanning in your pipelines.

