Unfault CLI

A calm reviewer for thoughtful engineers.

Unfault analyzes your code for clarity, boundaries, and behavior—highlighting places where decisions matter, before reality does. You write the code. Unfault helps you build it right.

Why Unfault?

Production issues don't announce themselves. That missing timeout? The unhandled edge case? The retry logic that isn't there? They surface at 3 AM, pages deep into an incident.

Unfault catches these patterns early—during development, not during outages. It's a linter for production-readiness, focused on:

• Stability — HTTP timeouts, circuit breakers, retry patterns
• Correctness — Error handling, boundary conditions, type safety
• Performance — N+1 queries, missing indexes, blocking calls
• Scalability — Resource limits, connection pooling, caching patterns

Quick Start

# Install
cargo install unfault

# Authenticate
unfault login

# Analyze your code
unfault review

That's it. Unfault scans your codebase, detects frameworks and languages, and reports findings in seconds.

Installation

From Releases (Recommended)

Download the latest binary from Releases and add it to your PATH.

From crates.io

cargo install unfault

From Source

git clone https://github.com/unfault/cli
cd cli
cargo build --release

Commands

unfault login

Authenticate using secure device flow—no API keys in your terminal history.

unfault login
# Visit https://app.unfault.dev/authorize and enter the displayed code

unfault review

Analyze your codebase for production-readiness issues.

# Basic output (grouped by severity)
unfault review

# Full details with suggested fixes
unfault review --output full

# JSON for integration with other tools
unfault review --output json

# Focus on specific dimensions
unfault review --dimension stability --dimension performance

Output Modes:

unfault ask

Query your project's health using natural language (requires prior review sessions).

# Ask about your codebase
unfault ask "What are my main stability concerns?"

# Scope to a specific workspace
unfault ask "Show recent issues" --workspace wks_abc123

# Get raw context without AI synthesis
unfault ask "Performance problems" --no-llm

Configure an LLM for AI-powered answers:

# OpenAI
unfault config llm openai --model gpt-4

# Anthropic
unfault config llm anthropic --model claude-3-5-sonnet-latest

# Local Ollama
unfault config llm ollama --model llama3.2

unfault status

Check authentication and connectivity.

unfault status

unfault config

Manage CLI configuration.

# Show current config
unfault config show

# Configure LLM provider
unfault config llm openai --model gpt-4o

# View LLM settings
unfault config llm show

# Remove LLM configuration
unfault config llm remove

CI/CD Integration

Unfault is designed for CI pipelines. Use exit codes to gate deployments:

# GitHub Actions with Code Scanning (SARIF)
- name: Run Unfault Analysis
  run: unfault review --output sarif > results.sarif

- name: Upload SARIF to GitHub
  uses: github/codeql-action/upload-sarif@v2
  with:
    sarif_file: results.sarif

# GitHub Actions (simple)
- name: Production Readiness Check
  run: unfault review
  continue-on-error: false

# GitLab CI
production_check:
  script:
    - unfault review --output json > unfault-report.json
  artifacts:
    reports:
      codequality: unfault-report.json
  allow_failure: false

Exit Codes

CI Example: Fail on findings

unfault review
if [ $? -eq 5 ]; then
  echo "Production readiness issues found. Blocking deployment."
  exit 1
fi

Supported Languages & Frameworks

Unfault automatically detects your stack and applies relevant rules.

Configuration

Configuration is stored in ~/.config/unfault/config.json:

{
  "api_key": "uf_live_...",
  "base_url": "https://api.unfault.dev",
  "llm": {
    "provider": "openai",
    "model": "gpt-4",
    "api_key": "sk-..."
  }
}

Environment Variables

What Unfault Finds

Stability Issues

# ❌ Missing timeout
response = httpx.get("https://api.example.com/data")

# ✅ Suggested fix
response = httpx.get("https://api.example.com/data", timeout=30.0)

Error Handling Gaps

// ❌ Ignored error
result, _ := riskyOperation()

// ✅ Suggested fix
result, err := riskyOperation()
if err != nil {
    return fmt.Errorf("risky operation failed: %w", err)
}

Performance Concerns

# ❌ N+1 query pattern
for user in users:
    orders = db.query(Order).filter(Order.user_id == user.id).all()

# ✅ Suggested fix
orders = db.query(Order).filter(Order.user_id.in_([u.id for u in users])).all()

Philosophy

Unfault is opinionated but not dogmatic. It focuses on patterns that matter in production:

• Fast feedback — Analysis completes in seconds, not minutes
• Actionable fixes — Every finding includes a suggested patch
• Low noise — Rules are tuned to minimize false positives
• Developer-first — Designed for the terminal, not dashboards

Troubleshooting

"Not logged in"

unfault login

"No source files found"

Ensure you're running unfault review from a directory containing supported source files (.py, .go, .rs, .ts, .js).

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

# Run tests
cargo test

# Build release
cargo build --release

License

MIT License. See LICENSE for details.