Usage - Fraim

This guide provides comprehensive documentation for using the Fraim command-line interface to run security analysis workflows.

Overview

The Fraim CLI is your primary interface for running AI-powered security analysis on code repositories and local directories. It supports multiple input sources, workflows, and output formats.

Basic Syntax

fraim [GLOBAL_OPTIONS] run WORKFLOW [WORKFLOW_OPTIONS]

Quick Start Examples

Analyze a Git Repository

# Analyze with specific workflows
fraim run code --location https://github.com/username/repository-name

Analyze Local Directory

# Analyze specific directory
fraim run code --location /path/to/your/project

Workflows

Specify which security analysis workflows to run. Available workflows:

code - Source code security analysis
iac - Infrastructure as Code analysis
risk_flagger - Risk analysis for security team investigation
system_analysis - System purpose and business context analysis

Examples:

fraim run code --location .                # Run code analysis on the path
fraim run iac --location .                 # Run IaC analysis on the path
fraim run risk_flagger --location .        # Run risk flagging analysis
fraim run system_analysis --location .     # Run system analysis

Command-Line Options

Input Sources

`--location <URL>`

Specify a Git repository URL to clone and analyze. Fraim will automatically clone the repository to a temporary directory and analyze its contents. Examples:

fraim run code --location https://github.com/microsoft/typescript
fraim run code --location git@github.com:company/private-repo.git

`--location <DIRECTORY>`

Analyze a local directory or file path. This is useful for analyzing code that’s already on your local system. Examples:

fraim run code --location .                    # Current directory
fraim run code --location /Users/dev/myproject # Absolute path
fraim run code --location ../sibling-project   # Relative path

File Filtering

`--globs <PATTERN_LIST>`

Specify custom file patterns to include in the analysis. If not provided, Fraim uses default patterns based on the selected workflows. Examples:

# Only analyze Python files
fraim run code --location . --globs "*.py"

# Analyze multiple file types
fraim run code --location . --globs "*.py" "*.js" "*.ts"

# Include files in specific directories
fraim run code --location . --globs "src/**/*.py" "tests/**/*.py"

Default patterns by workflow:

Code workflow: *.py, *.c, *.cpp, *.h, *.go, *.ts, *.js, *.java, *.rb, *.php, *.swift, *.rs, *.kt, *.scala, *.tsx, *.jsx
IAC workflow: *.tf, *.tfvars, *.tfstate, *.yaml, *.yml, *.json, Dockerfile, .dockerfile, docker-compose.yml, docker-compose.yaml, and various Kubernetes/Ansible files
Risk Flagger workflow: Uses the same patterns as the Code workflow
System Analysis workflow: Documentation files (*.md, *.rst, *.txt), configuration files (package.json, setup.py, etc.), and application entry points

`--limit <NUMBER>`

Limit the number of files to analyze. Useful for testing or when working with very large repositories. Examples:

fraim run code --location . --limit 50        # Analyze only first 50 matching files

AI Model Configuration

`--model <MODEL_NAME>`

Specify the AI model to use for analysis. Fraim supports multiple model providers through LiteLLM. Default: anthropic/claude-sonnet-4-20250514 Examples:

# Use Claude Sonnet 4.0 (default)
fraim run code --location . --model anthropic/claude-sonnet-4-20250514

# Use OpenAI GPT-4
fraim run code --location . --model gpt-4

# Use OpenAI GPT-3.5 Turbo
fraim run code --location . --model gpt-3.5-turbo

# Use Google Gemini
fraim run code --location . --model gemini/gemini-2.5-flash

`--temperature <NUMBER>`

Set the temperature setting for the model (0.0-1.0). Lower values make the model more deterministic, higher values make it more creative. Default: 0 Examples:

# Use default temperature (deterministic)
fraim run code --location . --temperature 0

# Use slightly more creative responses
fraim run code --location . --temperature 0.3

# Use more creative responses
fraim run code --location . --temperature 0.7

Performance Configuration

`--chunk-size <NUMBER>`

Set the number of lines per chunk when processing large files. Smaller chunks provide more granular analysis but may increase processing time. Default: 500 Examples:

fraim run code --location . --chunk-size 250   # Smaller chunks, more detailed analysis
fraim run code --location . --chunk-size 1000  # Larger chunks, faster processing

Guidelines:

Detailed analysis: 100-300 lines
Balanced: 400-600 lines (default)
Performance: 800-1200 lines

`--max-concurrent-chunks <NUMBER>`

Set the maximum number of chunks to process concurrently. Higher values can speed up analysis but use more system resources. Default: 5 Examples:

fraim run code --location . --max-concurrent-chunks 3   # Conservative resource usage
fraim run code --location . --max-concurrent-chunks 10  # Faster processing, more resources

`--max-concurrent-triagers <NUMBER>` (Code workflow only)

Set the maximum number of triager requests per chunk to run concurrently. This controls how many vulnerability assessments happen in parallel. Default: 3 Examples:

fraim run code --location . --max-concurrent-triagers 2   # Conservative triaging
fraim run code --location . --max-concurrent-triagers 5   # Faster triaging

Quality Control

`--confidence <NUMBER>`

Set the minimum confidence threshold (1-10) for filtering findings. Higher values reduce false positives but may miss some issues. Default: 7 Examples:

fraim run code --location . --confidence 5    # Include more potential issues
fraim run code --location . --confidence 9    # Only high-confidence findings

Guidelines:

1-3: Include all potential findings (high false positive rate)
4-6: Include likely findings (moderate false positive rate)
7-8: Include probable findings (balanced - default range)
9-10: Include only very confident findings (low false positive rate)

Git Diff Analysis

`--diff`

Enable git diff analysis mode. This analyzes only the changes in a git repository rather than the entire codebase. Examples:

fraim run code --location . --diff                    # Analyze changes from empty tree to HEAD
fraim run risk_flagger --location . --diff            # Risk analysis on git changes (required for risk_flagger)

`--head <COMMIT>`

Specify the head commit for diff analysis. Uses HEAD if not provided. Examples:

fraim run code --location . --diff --head main        # Compare to main branch
fraim run code --location . --diff --head abc123      # Compare to specific commit

`--base <COMMIT>`

Specify the base commit for diff analysis. Uses empty tree if not provided. Examples:

fraim run code --location . --diff --base origin/main --head HEAD    # Compare current changes to origin/main
fraim run code --location . --diff --base HEAD~5 --head HEAD         # Compare last 5 commits

Output Configuration

`--output <PATH>`

Specify a custom path for output files. If not provided, Fraim uses a default output directory. Default: fraim_output/ in the project directory Examples:

fraim run code --location . --output /tmp/fraim-results/
fraim run code --location . --output ./security-reports/

Output files:

fraim_report_[repo]_[timestamp].sarif - SARIF JSON report
fraim_report_[repo]_[timestamp].html - HTML report

Global Options

`--debug`

Enable debug logging for troubleshooting and development. This provides detailed information about the analysis process. Example:

fraim --debug run code --location .

`--show-logs <BOOLEAN>`

Control whether logs are printed to standard error output. Default: true Examples:

fraim --show-logs false run code --location .    # Suppress log output
fraim --show-logs true run code --location .     # Show log output (default)

`--log-output <PATH>`

Specify the output directory for log files. Default: fraim_output Examples:

fraim --log-output /tmp/logs run code --location .
fraim --log-output ./logs run code --location .

Observability

`--observability <BACKEND_LIST>`

Enable LLM observability backends for monitoring and analyzing AI model usage. Available backends:

langfuse - Langfuse observability platform

Examples:

fraim --observability langfuse run code --location .

Requirements:

Langfuse: Set LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY, and LANGFUSE_HOST environment variables

Instructions: 📖 For detailed setup instructions, see the Observability Guide.

Workflow-Specific Options

Risk Flagger Workflow Options

The risk_flagger workflow has additional options for customizing risk analysis and GitHub integration:

`--pr-url <URL>`

URL of the pull request to analyze. Used for GitHub integration. Example:

fraim run risk_flagger --location . --diff --pr-url https://github.com/owner/repo/pull/123

`--approver <USERNAME>`

GitHub username or group to notify for approval when risks are found. Example:

fraim run risk_flagger --location . --diff --approver security-team

`--custom-risk-list-action <append|replace>`

Whether to append to or replace the default risks list with custom risks. Default: append

`--custom-risk-list-filepath <PATH>`

Path to JSON/YAML file containing additional risks to consider. Example:

fraim run risk_flagger --location . --diff --custom-risk-list-filepath ./custom-risks.yaml

`--custom-risk-list-json <JSON>`

JSON string containing additional risks to consider.

`--custom-false-positive-considerations <LIST>`

List of additional considerations to help reduce false positives. Example:

fraim run risk_flagger --location . --diff --custom-false-positive-considerations "Consider test files" "Ignore demo code"

System Analysis Workflow Options

The system_analysis workflow has options for understanding system context:

`--business-context <TEXT>`

Additional business context to consider during analysis. Example:

fraim run system_analysis --location . --business-context "E-commerce platform for small businesses"

`--focus-areas <AREAS>`

Specific areas to focus on during analysis. Example:

fraim run system_analysis --location . --focus-areas "authentication,data_processing,api_endpoints"

Environment Variables

Fraim requires API keys for AI model providers. Set these in your environment or .env file:

Anthropic Claude

export ANTHROPIC_API_KEY="your_api_key_here"

OpenAI

export OPENAI_API_KEY="your_api_key_here"

Google Gemini

export GEMINI_API_KEY="your_api_key_here"

Langfuse Observability

export LANGFUSE_PUBLIC_KEY="your_public_key"
export LANGFUSE_SECRET_KEY="your_secret_key"
export LANGFUSE_HOST="your_langfuse_host"

Advanced Usage Examples

Comprehensive Analysis

# Code analysis with custom settings
fraim --model anthropic/claude-sonnet-4-20250514 \
      --observability langfuse \
      --debug \
      run code --location https://github.com/company/app \
      --confidence 6 \
      --chunk-size 600 \
      --max-concurrent-triagers 5

CI/CD Integration

# Optimized for CI/CD pipelines
fraim --show-logs false \
      --output ./security-reports/ \
      run code --location . \
      --confidence 8 \
      --limit 500 \
      --max-concurrent-chunks 3

Large Codebase Analysis

# Settings for analyzing large repositories
fraim run code --location https://github.com/large/project \
      --confidence 7 \
      --chunk-size 1000 \
      --max-concurrent-chunks 8 \
      --max-concurrent-triagers 2

Specific File Analysis

# Focus on specific file types and directories
fraim --debug \
      run code --location . \
      --confidence 6 \
      --globs "src/**/*.py" "api/**/*.py"

Risk Analysis on Pull Request

# Analyze risks in a pull request
fraim run risk_flagger --location . \
      --diff \
      --pr-url https://github.com/company/repo/pull/123 \
      --approver security-team \
      --confidence 6

System Analysis with Context

# Understand system purpose and architecture
fraim run system_analysis --location . \
      --business-context "Financial services platform" \
      --focus-areas "authentication,data_processing,compliance"

Understanding Output

Fraim generates two types of reports:

SARIF Report (.sarif)

Industry-standard format for security analysis results
Machine-readable JSON format
Compatible with security platforms and CI/CD tools
Contains detailed vulnerability information, locations, and metadata

HTML Report (.html)

Human-readable report with rich formatting
Interactive elements for browsing findings
Code snippets with highlighted vulnerabilities
Summary statistics and charts

Troubleshooting

Common Issues

“No input specified” error:

# ❌ Missing input
fraim run code

# ✅ Correct usage
fraim run code --location .

“API key not found” error:

# Set your API key (for default model)
export ANTHROPIC_API_KEY="your_key_here"
fraim run code --location .

Out of memory errors:

# Reduce chunk size and concurrency
fraim run code --location . --chunk-size 200 --max-concurrent-chunks 2

No files found:

# Check file patterns
fraim --debug run code --location . --globs "*.py"

Risk flagger requires diff mode:

# ❌ Missing --diff flag
fraim run risk_flagger --location .

# ✅ Correct usage
fraim run risk_flagger --location . --diff

Performance Tips

Start small: Use --limit to test on a subset of files first
Optimize chunks: Adjust --chunk-size based on your system capabilities
Balance chunks: Smaller --chunk-size for accuracy, larger for speed
Control concurrency: Use --max-concurrent-chunks and --max-concurrent-triagers to balance speed vs resources
Filter confidence: Use higher --confidence to reduce processing time
Use diff mode: For incremental analysis, use --diff to analyze only changes
Monitor resources: Use system monitoring to optimize settings

Get Started

Workflows

Integrations

CLI

​Overview

​Basic Syntax

​Quick Start Examples

​Analyze a Git Repository

​Analyze Local Directory

​Workflows

​Command-Line Options

​Input Sources

​--location <URL>

​--location <DIRECTORY>

​File Filtering

​--globs <PATTERN_LIST>

​--limit <NUMBER>

​AI Model Configuration

​--model <MODEL_NAME>

​--temperature <NUMBER>

​Performance Configuration

​--chunk-size <NUMBER>

​--max-concurrent-chunks <NUMBER>

​--max-concurrent-triagers <NUMBER> (Code workflow only)

​Quality Control

​--confidence <NUMBER>

​Git Diff Analysis

​--diff

​--head <COMMIT>

​--base <COMMIT>

​Output Configuration

​--output <PATH>

​Global Options

​--debug

​--show-logs <BOOLEAN>

​--log-output <PATH>

​Observability

​--observability <BACKEND_LIST>

​Workflow-Specific Options

​Risk Flagger Workflow Options

--pr-url <URL>

--approver <USERNAME>

--custom-risk-list-action <append|replace>

--custom-risk-list-filepath <PATH>

--custom-risk-list-json <JSON>

--custom-false-positive-considerations <LIST>

​System Analysis Workflow Options

--business-context <TEXT>

--focus-areas <AREAS>

​Environment Variables

​Anthropic Claude

​OpenAI

​Google Gemini

​Langfuse Observability

​Advanced Usage Examples

​Comprehensive Analysis

​CI/CD Integration

​Large Codebase Analysis

​Specific File Analysis

​Risk Analysis on Pull Request

​System Analysis with Context

​Understanding Output

​SARIF Report (.sarif)

​HTML Report (.html)

​Troubleshooting

​Common Issues

​Performance Tips

Overview

Basic Syntax

Quick Start Examples

Analyze a Git Repository

Analyze Local Directory

Workflows

Command-Line Options

Input Sources

`--location <URL>`

`--location <DIRECTORY>`

File Filtering

`--globs <PATTERN_LIST>`

`--limit <NUMBER>`

AI Model Configuration

`--model <MODEL_NAME>`

`--temperature <NUMBER>`

Performance Configuration

`--chunk-size <NUMBER>`

`--max-concurrent-chunks <NUMBER>`

`--max-concurrent-triagers <NUMBER>` (Code workflow only)

Quality Control

`--confidence <NUMBER>`

Git Diff Analysis

`--diff`

`--head <COMMIT>`

`--base <COMMIT>`

Output Configuration

`--output <PATH>`

Global Options

`--debug`

`--show-logs <BOOLEAN>`

`--log-output <PATH>`

Observability

`--observability <BACKEND_LIST>`

Workflow-Specific Options

Risk Flagger Workflow Options

`--pr-url <URL>`

`--approver <USERNAME>`

`--custom-risk-list-action <append|replace>`

`--custom-risk-list-filepath <PATH>`

`--custom-risk-list-json <JSON>`

`--custom-false-positive-considerations <LIST>`

System Analysis Workflow Options

`--business-context <TEXT>`

`--focus-areas <AREAS>`

Environment Variables

Anthropic Claude

OpenAI

Google Gemini

Langfuse Observability

Advanced Usage Examples

Comprehensive Analysis

CI/CD Integration

Large Codebase Analysis

Specific File Analysis

Risk Analysis on Pull Request

System Analysis with Context

Understanding Output

SARIF Report (.sarif)

HTML Report (.html)

Troubleshooting

Common Issues

Performance Tips