Basics

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:

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:

Mode	Flag	Description
Fast	`--mode fast` (default)	Rapid security scan using industry-standard SAST, secret detection, and dependency checks combined with Rafter’s proprietary analysis.
Plus	`--mode plus`	Everything 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

pnpm add -g @rafter-security/cli

yarn global add @rafter-security/cli

pip install rafter-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.

Get Started

CLI Guides

Local Security

References

Getting Started with the CLI

Core Concepts

How Do I get My API Key?

What Does the CLI Do?

How Does Scanning Work?

Scan Modes

Basic Commands

Start a Scan with `rafter run`

Retrieve Results with `rafter get`

Check Quota with `rafter usage`

Basic Workflow

1. Install the CLI

2. Set Your API Key

3. Run a Scan

4. Check Results

Output Formats

JSON Format (Default)

Markdown Format

Next Steps

CLI Basics

Advanced CLI

API Reference

CI/CD Integration

​Getting Started with the CLI

​Core Concepts

​How Do I get My API Key?

​What Does the CLI Do?

​How Does Scanning Work?

​Scan Modes

​Basic Commands

​Start a Scan with rafter run

​Retrieve Results with rafter get

​Check Quota with rafter usage

​Basic Workflow

​1. Install the CLI

​2. Set Your API Key

​3. Run a Scan

​4. Check Results

​Output Formats

​JSON Format (Default)

​Markdown Format

​Next Steps

CLI Basics

Advanced CLI

API Reference

CI/CD Integration

Getting Started with the CLI

Core Concepts

How Do I get My API Key?

What Does the CLI Do?

How Does Scanning Work?

Scan Modes

Basic Commands

Start a Scan with `rafter run`

Retrieve Results with `rafter get`

Check Quota with `rafter usage`

Basic Workflow

1. Install the CLI

2. Set Your API Key

3. Run a Scan

4. Check Results

Output Formats

JSON Format (Default)

Markdown Format

Next Steps