Unfault CLI

A cognitive context engine for thoughtful engineers.

Unfault helps you understand what your code means and does — while you're writing it. It reveals the runtime impact of your changes, showing you which routes use a function, what safeguards are (or aren't) in place, and how your code fits into the bigger picture.

---

Why Unfault?

Software complexity grows invisibly. That function you just changed? It might be called by five different API routes. That missing timeout? It's three layers deep in a request path with no retry logic.

Unfault illuminates these connections. It builds a semantic graph of your codebase and gives you instant answers to questions like:

• "Where is this function used?" — See which routes, handlers, and background jobs depend on it
• "What safeguards exist in this path?" — Know if there's structured logging, retries, or error boundaries
• "What's the impact of changing this?" — Understand the blast radius before you commit

This isn't about warnings or alerts. It's about cognitive support — keeping the runtime context visible so you can stay in flow while making informed decisions.

Quick Start

# Install
cargo install unfault

# Authenticate
unfault login

# Understand your codebase
unfault review

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 and surface behavioral insights.

# Standard analysis (grouped by dimension)
unfault review

# Detailed insights with context
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:

Mode	Description
basic	Grouped by dimension, insight counts (default)
concise	Summary statistics only
full	Detailed insights with suggestions
json	Machine-readable output
sarif	SARIF 2.1.0 for IDE integration

unfault ask

Query your codebase using natural language.

# Ask about your codebase
unfault ask "What functions lack structured logging?"

# Scope to a specific workspace
unfault ask "Show me the critical paths" --workspace wks_abc123

# Use the configured LLM for a longer answer
unfault ask "Which routes have no retry logic?" --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 graph

Query the code graph for impact analysis, dependencies, and relationships.

# Build/refresh the code graph
unfault graph refresh

# What's affected if I change this file?
unfault graph impact auth/middleware.py

# Find files that use a specific library
unfault graph library requests

# Find external dependencies of a file
unfault graph deps main.py

# Find the most connected files in the codebase
unfault graph critical --limit 10

# Get graph statistics
unfault graph stats

Understanding the Graph:

The code graph captures semantic relationships — imports, function calls, route handlers, middleware chains. When you ask "what's affected?", you're not just looking at file imports; you're seeing the full call graph that traces how a change propagates through your system.

unfault lsp

Start the Language Server Protocol server for IDE integration.

# Start LSP server (used by VS Code extension)
unfault lsp

# With verbose logging for debugging
unfault lsp --verbose

The LSP server provides:

• Real-time insights as you type
• Hover information showing function impact and context
• Quick fixes with contextual suggestions

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

IDE Integration

The primary way to use Unfault is through your IDE. The VS Code extension connects to the CLI's LSP server, providing:

• Inline context — Hover over a function to see where it's used and what safeguards exist
• File importance — Status bar shows how central a file is to your codebase
• Dependency awareness — Know which files will be affected by your changes

Install the extension: Unfault for VS Code

CI/CD Integration

While Unfault shines in the IDE, it's also valuable in CI pipelines for tracking codebase health:

# GitHub Actions
- name: Analyze Codebase
  run: unfault review --output sarif > results.sarif

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

Exit Codes

Code	Meaning	Action
0	Success	✅ Proceed
1	General error	🔍 Check logs
2	Configuration error	Run unfault login
3	Authentication failed	Re-authenticate
4	Network error	Check connectivity
5	Insights detected	📊 Review insights
6	Invalid input	Check arguments
7	Service unavailable	Retry later
8	Session error	Retry analysis
10	Subscription required	Upgrade plan

Supported Languages & Frameworks

Language	Frameworks
Python	FastAPI, Flask, Django, httpx, requests
Go	net/http, gin, echo
Rust	reqwest, hyper, actix-web
TypeScript	Express, fetch, axios

Unfault automatically detects your stack and builds the appropriate semantic graph.

Configuration

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

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

Environment Variables

Variable	Description
UNFAULT_BASE_URL	Override API endpoint
OPENAI_API_KEY	OpenAI API key (for ask command)
ANTHROPIC_API_KEY	Anthropic API key (for ask command)

What Unfault Reveals

Missing Safeguards

# Unfault shows: "This function has no timeout.
# Called by: /api/users endpoint, /api/orders endpoint
# No retry logic in call chain."
response = httpx.get("https://api.example.com/data")

Error Handling Context

// Unfault shows: "Unchecked error.
// This function is called by: ProcessOrder handler
// Call chain has no structured logging."
result, _ := riskyOperation()

Query Patterns

# Unfault shows: "N+1 query pattern detected.
# This loop is inside: get_user_dashboard route
# 47 users in average request = 47 extra queries"
for user in users:
    orders = db.query(Order).filter(Order.user_id == user.id).all()

Philosophy

Unfault is designed around three principles:

1. Context, not warnings — Information appears when you need it, not as a wall of alerts
2. Flow preservation — Insights are quiet and inline; they don't interrupt your work
3. Runtime awareness — Understand how your code behaves, not just how it's structured

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.

---