Skip to main content

​
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.
Your API key starts with RF and should be kept secure. Never commit it to version control (e.g. GitHub). Use environment variables instead.

​
What Does the CLI Do?

The Rafter CLI allows you to:
  • Run security audits of your remote repositories (rafter run or rafter scan) — agentic deep dives backed by a full SAST/SCA toolchain
  • Choose scan depth with scan modes — fast for rapid SAST/SCA analysis, plus for 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.
When you run a scan:
  1. The CLI detects your repository and branch from Git
  2. It uploads your code securely to Rafter’s analysis engine
  3. 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
  4. Your code is deleted from Rafter’s engine immediately after analysis
  5. Results are returned and displayed in your terminal

​
Scan Modes

Rafter supports two scan modes, selected with the --mode (or -m) flag:
ModeFlagDescription
Fast--mode fast (default)Rapid security scan using industry-standard SAST, secret detection, and dependency checks combined with Rafter’s proprietary analysis.
Plus--mode plusEverything in fast, plus agentic deep-dive passes that analyze your codebase the way a professional cybersecurity auditor would — tracing data flows, reasoning about business logic, and surfacing vulnerabilities that static rules miss. Takes longer but produces significantly more detailed findings.
# Fast scan (default — same as omitting --mode)
rafter run --format md --mode fast

# Plus scan for deeper analysis
rafter run --format md --mode plus

# Short flag
rafter run --format md -m plus

​
Basic Commands

Make sure you configure an environment variable or pass in your RAFTER API_KEY with the flag --api-key or -k (more details below).

​
Start a Scan with rafter run

The most common command for running security scans are below. They auto-detect the repo and branch and require an environment variable RAFTER_API_KEY: 
# Basic scan (defaults to fast mode)
rafter run --format md

# `scan` is an alias for `run`
rafter scan --format md

# Run a Plus scan for deeper coverage with additional agent passes
rafter run --format md --mode plus

# Save results to a file
rafter run --format md > security-report-$(date +%Y-%m-%d-%H-%M-%S).md

# Scan specific repository and branch
rafter run --format md --repo myorg/myrepo --branch main

# Non-interactive scan (don't wait for completion)
rafter run --format md --skip-interactive

​
Retrieve Results with rafter get

Get results from a completed scan: 
# Get scan results by ID
rafter get <scan-id>

# Wait for scan completion
rafter get <scan-id> --interactive

# Get results in Markdown format
rafter get <scan-id> --format md

# Save results to a file
rafter get <scan-id> --format md --interactive > security-report-$(date +%Y-%m-%d-%H-%M-%S).md

​
Check Quota with rafter usage

Check your API usage and remaining scans: 
rafter usage

​
Basic Workflow

Here’s a typical workflow for running your first scan:

​
1. Install the CLI

npm install -g @rafter-security/cli
Python 3.10+ required for pip installs. Verify your version:
python3 --version   # Must be 3.10 or higher
On Ubuntu/Debian, Python and pip may not be installed by default:
sudo apt update && sudo apt install -y python3 python3-pip python3-venv
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

export RAFTER_API_KEY="RFabc-your-api-key-here"

​
3. Run a Scan

# Navigate to your repository
cd /path/to/your/repo

# Run the scan
rafter run --format md

​
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 multiple output formats for different use cases:

​
JSON Format (Default)

rafter get <scan-id> --format json
JSON output is perfect for:
  • Automation and scripting
  • Integration with other tools
  • Parsing with tools like jq
We’ll go into detail on how to process these results in the Output Processing section.

​
Markdown Format

rafter get <scan-id> --format md
Markdown output is great for:
  • 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
Example output (truncated): 
You are a senior application-security, web-application, and cloud-reliability
engineer. Implement production-grade solutions that scale. Never mock data,
suppress linter security rules, or shortcut the fix. Think step-by-step.

# Security Issues and Vulnerabilities

**Total Issues:** 2

This report contains 2 security issues found in the repository.
Each issue requires attention and remediation. Proceed one-by-one,
thinking step-by-step to understand and remediate each.

## Issues Summary

### Issue 1
**Rule ID:** a1b2c3d4
**File:** src/auth.js
**Line:** 42
**Description:** Hardcoded API key detected

### Issue 2
**Rule ID:** e5f6a7b8
**File:** src/database.js
**Line:** 78
**Description:** SQL injection vulnerability

Please analyze these 2 security vulnerabilities and provide:
1. A comprehensive analysis of the security risks
2. Prioritized remediation steps
3. Code examples for fixes
4. Prevention strategies for future development

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