CLI Commands

This document provides a complete reference for the Unfault CLI. Each command is listed with its options, defaults, and examples.

Commands

Command	Purpose
`review`	Analyze code for production-readiness
`ask`	Query project health using natural language
`graph`	Explore code dependencies and impact
`config`	Manage CLI settings
`login`	Authenticate with Unfault
`status`	Check authentication and connectivity
`addon`	Install and manage optional addons
`lsp`	Start the language server for IDE integration

`review`

Analyze code and get recommendations.

unfault review [OPTIONS]

Options

Option	Description	Default
`--output <FORMAT>`	Output format: `basic`, `concise`, `full`, `json`, `sarif`	`basic`
`--file <PATH>`	Restrict analysis to specific files (can be repeated)	All detected files
`--uncommitted`	Review only uncommitted files (staged, unstaged, untracked)	Disabled
`-v, --verbose`	Enable verbose output (dumps raw API responses)	Disabled
`--profile <PROFILE>`	Override the detected profile (e.g., `python_fastapi_backend`)	Auto-detected
`-d, --dimension <DIM>`	Dimensions to analyze (can be repeated). Options: `stability`, `correctness`, `performance`, `scalability`	All from profile
`--dry-run`	Show fixes without applying them	Disabled
`--include-tests`	Include test files in analysis	Disabled
`--discover-observability`	Discover and link SLOs from cloud platforms (GCP, Datadog, Dynatrace)	Disabled

File Discovery and Ignores

Unfault scans your workspace and only sends the relevant source files for analysis.

To match what teams usually consider “part of the codebase”, Unfault respects common ignore conventions:

.gitignore (including global gitignore and .git/info/exclude)
.ignore
.dockerignore

It also skips a few common dependency/build directories even if they are not ignored (for example node_modules, target, dist, build, .venv).

If you need something excluded, prefer adding it to your ignore files so Unfault and your other tools stay in sync.

Output Formats

Format	Use Case
`basic`	Default. Shows header, summary, and guidance on next steps.
`concise`	Brief statistics only. Good for dashboards.
`full`	Detailed findings with file locations and suggested fixes.
`json`	Machine-readable. Use for CI/CD parsing or custom tooling.
`sarif`	GitHub Code Scanning and IDE integration.

Examples

# Standard review
unfault review

# Focus on stability issues only
unfault review --dimension stability

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

# JSON for CI parsing
unfault review --output json

# Include test files
unfault review --include-tests

# Discover and link SLOs
unfault review --discover-observability

`ask`

Ask questions about project health using natural language. Uses RAG (retrieval-augmented generation) to find relevant context from past reviews.

unfault ask [OPTIONS] <QUERY>

Arguments

Argument	Description
`<QUERY>`	Natural language question about your project

Options

Option	Description	Default
`-w, --workspace <ID>`	Scope query to a specific workspace ID	Auto-detected
`-p, --path <PATH>`	Workspace path for auto-detection	Current directory
`--max-sessions <N>`	Maximum session contexts to retrieve (1-20)	5
`--max-findings <N>`	Maximum finding contexts to retrieve (1-50)	10
`--threshold <T>`	Minimum similarity threshold (0.0-1.0)	0.5
`--json`	Output as JSON	Disabled
`--llm`	Use configured LLM for synthesized answer	Disabled
`-v, --verbose`	Enable verbose output	Disabled

Examples

# Basic question
unfault ask "What are my main stability concerns?"

# Get LLM-synthesized answer
unfault ask "How do we handle database timeouts?" --llm

# Scope to specific path
unfault ask "Performance issues" --path src/api

# More context, stricter matching
unfault ask "Error handling patterns" --max-findings 20 --threshold 0.7

`graph`

Query the code graph for dependencies, impact analysis, and critical files.

unfault graph <SUBCOMMAND>

Subcommands

Subcommand	Purpose
`impact`	What breaks if I change this file?
`function-impact`	What breaks if I change this function?
`library`	Which files use a specific library?
`deps`	What does this file depend on?
`critical`	Which files are most critical?
`stats`	Code graph statistics
`dump`	Dump graph for debugging

`graph impact`

Analyze what depends on a file. Useful before refactoring.

unfault graph impact [OPTIONS] <FILE>

Option	Description	Default
`<FILE>`	File path to analyze	Required
`-w, --workspace <PATH>`	Workspace path	Current directory
`--max-depth <N>`	Transitive analysis depth (1-10)	5
`--json`	Output as JSON	Disabled
`-v, --verbose`	Verbose output	Disabled

unfault graph impact src/api/auth.py
unfault graph impact --max-depth 3 src/core/models.py

`graph function-impact`

Analyze what depends on a specific function.

unfault graph function-impact [OPTIONS] <FUNCTION>

Option	Description	Default
`<FUNCTION>`	Function in format `file:function`	Required
`-w, --workspace <PATH>`	Workspace path	Current directory
`--max-depth <N>`	Transitive analysis depth (1-10)	5
`--json`	Output as JSON	Disabled

unfault graph function-impact src/api/auth.py:validate_token

`graph library`

Find files that use a specific library.

unfault graph library [OPTIONS] <LIBRARY>

Option	Description	Default
`<LIBRARY>`	Library name (e.g., `requests`, `fastapi`)	Required
`-w, --workspace <PATH>`	Workspace path	Current directory
`--json`	Output as JSON	Disabled

unfault graph library requests
unfault graph library sqlalchemy --json

`graph deps`

Find external dependencies of a file.

unfault graph deps [OPTIONS] <FILE>

Option	Description	Default
`<FILE>`	File path to analyze	Required
`-w, --workspace <PATH>`	Workspace path	Current directory
`--json`	Output as JSON	Disabled

unfault graph deps src/api/routes.py

`graph critical`

Find the most critical files in the codebase (high connectivity, many dependents).

unfault graph critical [OPTIONS]

Option	Description	Default
`-n, --limit <N>`	Number of files to return (1-50)	10
`--sort-by <METRIC>`	Sort metric (see below)	`in-degree`
`-w, --workspace <PATH>`	Workspace path	Current directory
`--json`	Output as JSON	Disabled

Sort metrics:

Metric	Meaning
`in-degree`	Files most imported by others
`out-degree`	Files that import the most
`total-degree`	Total connectivity
`library-usage`	External libraries used
`importance-score`	Weighted importance

unfault graph critical
unfault graph critical --limit 20 --sort-by total-degree

`graph stats`

Get code graph statistics.

unfault graph stats [OPTIONS]

Option	Description	Default
`-w, --workspace <PATH>`	Workspace path	Current directory
`--json`	Output as JSON	Disabled

`graph dump`

Dump the local code graph for debugging.

unfault graph dump [OPTIONS]

Option	Description	Default
`-w, --workspace <PATH>`	Workspace path	Current directory
`--calls-only`	Output only call edges	Disabled
`--file <FILE>`	Dump only specific file	All files

`config`

Manage CLI configuration.

unfault config <SUBCOMMAND>

Subcommands

Subcommand	Purpose
`show`	Display current configuration
`llm`	Manage LLM configuration

`config show`

Display current configuration.

unfault config show

`config llm`

Configure an LLM provider for AI-powered features like unfault ask --llm.

unfault config llm <PROVIDER>

OpenAI

unfault config llm openai [OPTIONS]

Option	Description	Default
`-m, --model <MODEL>`	Model name	`gpt-4`
`-k, --api-key <KEY>`	API key (prefers `OPENAI_API_KEY` env var)	From env

unfault config llm openai --model gpt-4o

Anthropic

unfault config llm anthropic [OPTIONS]

Option	Description	Default
`-m, --model <MODEL>`	Model name	`claude-3-5-sonnet-latest`
`-k, --api-key <KEY>`	API key (prefers `ANTHROPIC_API_KEY` env var)	From env

unfault config llm anthropic --model claude-sonnet-4-5

Ollama

unfault config llm ollama [OPTIONS]

Option	Description	Default
`-e, --endpoint <URL>`	Ollama API endpoint	`http://localhost:11434`
`-m, --model <MODEL>`	Model name	`llama3.2`

unfault config llm ollama --model mistral

Custom (OpenAI-compatible)

unfault config llm custom --endpoint <URL> --model <MODEL> [OPTIONS]

Option	Description	Default
`-e, --endpoint <URL>`	API endpoint	Required
`-m, --model <MODEL>`	Model name	Required
`-k, --api-key <KEY>`	API key	None

unfault config llm custom --endpoint https://api.together.xyz/v1 --model meta-llama/Llama-3-70b-chat-hf

Other LLM commands

# Show current LLM configuration
unfault config llm show

# Remove LLM configuration
unfault config llm remove

`login`

Authenticate with Unfault using device flow. Opens a browser for secure authentication.

unfault login

No options. Follow the prompts to complete authentication.

`status`

Check authentication and service connectivity.

unfault status

Shows:

Authentication status
API connectivity
Workspace detection
LLM configuration (if any)
Addon status (for example whether fault is installed)

`addon`

Manage optional addons.

unfault addon <SUBCOMMAND>

`addon install`

Install an addon.

unfault addon install [--force] <NAME>

`fault`

Installs the fault CLI binary to ~/.local/bin/fault (downloaded from GitHub releases and SHA256 verified).

unfault addon install fault

`lsp`

Start the Language Server Protocol server for IDE integration.

unfault lsp [OPTIONS]

Option	Description	Default
`-v, --verbose`	Enable verbose logging to stderr	Disabled

Exit Codes

The CLI uses exit codes to communicate results:

Code	Meaning	Action
0	Success, no findings	Proceed
1	General error	Check error message
2	Configuration error	Check config, run `unfault status`
3	Authentication failed	Run `unfault login`
4	Network error	Check connectivity
5	Findings detected	Review findings
6	Invalid input	Check arguments
7	Service unavailable	Retry later
8	Session error	Retry analysis
10	Subscription required	Upgrade plan

Environment Variables

Common variables:

Variable	Description
`UNFAULT_API_KEY`	API key for authentication (CI/CD)
`UNFAULT_BASE_URL`	Override API endpoint (enterprise)
`OPENAI_API_KEY`	OpenAI API key for `ask --llm`
`ANTHROPIC_API_KEY`	Anthropic API key for `ask --llm`

For SLO discovery and the complete list, see Configuration: Environment Variables.

Configuration File

The CLI stores configuration in:

Platform	Location
Linux	`~/.config/unfault/config.json`
macOS	`~/.config/unfault/config.json`
Windows	`%USERPROFILE%\.config\unfault\config.json`