Configuration

Unfault can be configured at the user level and per-workspace.

User Configuration

The configuration file location depends on your operating system:

Platform	Location
Linux	~/.config/unfault/config.json or $XDG_CONFIG_HOME/unfault/config.json
macOS	~/.config/unfault/config.json or $XDG_CONFIG_HOME/unfault/config.json
Windows	%USERPROFILE%\.config\unfault\config.json

Note

All platforms use the same .config directory pattern for consistency, rather than platform-specific locations like ~/Library/Application Support (macOS) or %APPDATA% (Windows).

Example configuration:

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

Authentication

After running unfault login, your API key is stored automatically.

For CI/CD environments, set the API key via environment variable:

export UNFAULT_API_KEY="sk_live_..."

LLM Configuration

For the unfault ask command, configure an LLM provider:

OpenAI

unfault config llm openai --model gpt-5.1

Anthropic

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

Ollama

unfault config llm ollama --model llama3.2

Workspace Configuration

Unfault reads configuration from your project’s manifest file, avoiding the need for a dedicated config file. The configuration location depends on your language:

Python (pyproject.toml)

[tool.unfault]
# Override auto-detected profile
profile = "python_fastapi_backend"

# Limit analysis to specific dimensions
dimensions = ["stability", "correctness", "performance"]

[tool.unfault.rules]
# Rules to exclude (supports glob patterns)
exclude = [
    "python.missing_structured_logging",  # We use custom logging
    "python.http.*",                       # All HTTP rules
]

# Additional rules to include
include = ["python.security.*"]

# Severity overrides
[tool.unfault.rules.severity]
"python.bare_except" = "low"

Rust (Cargo.toml)

[package.metadata.unfault]
profile = "rust_axum_service"
dimensions = ["stability", "correctness"]

[package.metadata.unfault.rules]
exclude = ["rust.println_in_lib"]

[package.metadata.unfault.rules.severity]
"rust.unsafe_unwrap" = "critical"

JavaScript/TypeScript (package.json)

{
  "name": "my-app",
  "unfault": {
    "profile": "typescript_express_backend",
    "dimensions": ["stability", "security"],
    "rules": {
      "exclude": ["typescript.console_in_production"],
      "include": ["typescript.security.*"],
      "severity": {
        "typescript.empty_catch": "critical"
      }
    }
  }
}

Standalone (.unfault.toml)

# For Go projects, multi-language repos, or any project
# where you prefer a dedicated config file

# Override auto-detected profile (optional)
profile = "go_gin_service"

# Limit analysis to specific dimensions (optional)
# Available: stability, correctness, performance, scalability, security, maintainability
dimensions = ["stability", "performance"]

[rules]
# Rules to exclude - supports exact IDs and glob patterns
exclude = [
    "go.missing_structured_logging",
    "go.http.*",  # All HTTP-related rules
]

# Additional rules to include beyond profile defaults
include = ["go.security.*"]

# Severity overrides: low, medium, high, critical
[rules.severity]
"go.unchecked_error" = "critical"
"go.defer_in_loop" = "low"

Tip

Use .unfault.toml when your project doesn’t have a pyproject.toml, Cargo.toml, or package.json, or when you prefer to keep Unfault configuration separate from your package manifest.

Configuration Priority

When multiple configuration sources exist:

1. Manifest files are checked first - pyproject.toml, Cargo.toml, then package.json
2. .unfault.toml is the fallback - Used when no manifest contains unfault configuration
3. No merging - Only one source is used per project (the first one found with unfault config)

Rule Patterns

Patterns for exclude and include use glob syntax:

Pattern	Matches	Does Not Match
python.http.missing_timeout	Exact match only	Any other rule
python.http.*	python.http.missing_timeout, python.http.missing_retry	python.http.client.timeout
*.missing_timeout	python.missing_timeout, go.missing_timeout	python.http.missing_timeout
python.**	All rules starting with python.	Rules from other languages

Disabling Rules

To disable a rule project-wide, add it to the exclude list in your config.

You can also disable rules inline in your code:

Go

// unfault:disable http_client_missing_timeout
client := http.Client{}

Python

# unfault:disable-next-line n_plus_one_query
for user in users:
    orders = get_orders(user.id)

Environment Variables

Unfault

Variable	Description
UNFAULT_API_KEY	API key for authentication. Use this in CI/CD instead of unfault login.
UNFAULT_BASE_URL	Override API endpoint. For enterprise deployments or local development.

LLM Providers

Used by unfault ask --llm for AI-synthesized answers:

Variable	Description
OPENAI_API_KEY	OpenAI API key. Required when using unfault config llm openai.
ANTHROPIC_API_KEY	Anthropic API key. Required when using unfault config llm anthropic.

SLO Discovery (GCP)

Used by unfault review --discover-observability to find Google Cloud SLOs:

Variable	Description
GOOGLE_APPLICATION_CREDENTIALS	Path to service account JSON file. Takes precedence over ADC.
GOOGLE_CLOUD_PROJECT	GCP project ID. Overrides auto-detection from credentials.
GCP_PROJECT	Alternative to GOOGLE_CLOUD_PROJECT.
GCLOUD_PROJECT	Alternative to GOOGLE_CLOUD_PROJECT.

Tip

For local development, run gcloud auth application-default login instead of setting credentials manually. Unfault reads Application Default Credentials from ~/.config/gcloud/application_default_credentials.json.

SLO Discovery (Datadog)

Used by unfault review --discover-observability to find Datadog SLOs:

Variable	Description
DD_API_KEY	Datadog API key. Required for Datadog integration.
DD_APP_KEY	Datadog application key. Required for Datadog integration.
DD_SITE	Datadog site (e.g., datadoghq.eu for EU). Defaults to datadoghq.com.

SLO Discovery (Dynatrace)

Used by unfault review --discover-observability to find Dynatrace SLOs:

Variable	Description
DT_API_TOKEN	Dynatrace API token with SLO read permissions.
DT_ENVIRONMENT_URL	Dynatrace environment URL (e.g., https://abc12345.live.dynatrace.com).

Configuration Paths

Variable	Description
XDG_CONFIG_HOME	Override config directory. Defaults to ~/.config.
HOME	User home directory (Linux/macOS). Used to locate ~/.config/unfault/.
USERPROFILE	User home directory (Windows). Used to locate .config\unfault\.

Configuration Precedence

Settings are applied in this order (later overrides earlier):

1. Default values
2. User config (see User Configuration for platform-specific paths)
3. Workspace config (pyproject.toml, Cargo.toml, package.json, or .unfault.toml)
4. Environment variables
5. Command-line flags