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
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
-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

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

Note

The ask command requires at least one prior unfault review to have indexed context.

---

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)

---

lsp

Start the Language Server Protocol server for IDE integration.

unfault lsp [OPTIONS]

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

Note

The LSP server is typically started by your editor, not invoked directly. See the VS Code Extension guide.

---

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