> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rafter.so/llms.txt
> Use this file to discover all available pages before exploring further.
# Basics
> Learn the fundamentals of using the Rafter CLI for security scanning workflows.
## 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](https://rafter.so/) and get your API key from your [account page](https://rafter.so/account).
Your API key starts with `RF` and should be kept secure. Never commit it to version control (e.g. GitHub). Use [environment variables](https://configu.com/blog/environment-variables-how-to-use-them-and-4-critical-best-practices/) 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:
| 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. |
```bash theme={null}
# 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`:
```bash theme={null}
# 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:
```bash theme={null}
# Get scan results by ID
rafter get
# Wait for scan completion
rafter get --interactive
# Get results in Markdown format
rafter get --format md
# Save results to a file
rafter get --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:
```bash theme={null}
rafter usage
```
## Basic Workflow
Here's a typical workflow for running your first scan:
### 1. Install the CLI
```bash npm theme={null}
npm install -g @rafter-security/cli
```
```bash pnpm theme={null}
pnpm add -g @rafter-security/cli
```
```bash yarn theme={null}
yarn global add @rafter-security/cli
```
```bash pip theme={null}
pip install rafter-cli
```
**Python 3.10+ required for pip installs.** Verify your version:
```bash theme={null}
python3 --version # Must be 3.10 or higher
```
On Ubuntu/Debian, Python and pip may not be installed by default:
```bash theme={null}
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](https://python.org) — pip is included.
### 2. Set Your API Key
```bash theme={null}
export RAFTER_API_KEY="RFabc-your-api-key-here"
```
### 3. Run a Scan
```bash theme={null}
# 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)
```bash theme={null}
rafter get --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](/guides/advanced#output-processing) section.
### Markdown Format
```bash theme={null}
rafter get --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):
```markdown theme={null}
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
Learn the fundamentals of using the Rafter CLI.
Master advanced CLI features and automation.
Build custom integrations with the REST API.
Set up automated scanning in your pipelines.