// docs · v1.0

Configuration

Two-tier YAML config, environment variables, the config subcommand, and every key CommitBrief reads at runtime.

CommitBrief uses a two-tier YAML configuration with field-level merge — config.Default() skeleton → user config → repo-local config → environment variables → CLI flags. Each layer overrides the previous per-field, not whole-file.

Files

Tier	Path	Notes
User-level	`~/.commitbrief/config.yml`	Defaults that apply everywhere. Override path with `COMMITBRIEF_CONFIG`.
Repo-local	`<repo>/.commitbrief/config.yml`	Per-repo overrides. Gitignored — `.commitbrief/` is auto-added to repo `.gitignore` on first write.

Either file may be absent; a built-in skeleton fills the gap so a fresh commitbrief setup works without preexisting files.

The schema

version: 1                                # config schema version
provider: anthropic                       # active provider
providers:
  anthropic:
    api_key: sk-ant-...                   # secret; mode 0600 on disk
    model: claude-opus-4-7
  openai:
    api_key: sk-...
    model: gpt-4o
  gemini:
    api_key: AIza...
    model: gemini-2.5-pro
  ollama:
    base_url: http://localhost:11434
    model: qwen2.5-coder:14b
  claude-cli:
    model: ""                             # ignored — host CLI manages selection
  gemini-cli:
    model: ""
output:
  lang: en                                # supported: en | tr
  color: auto                             # auto | always | never
cache:
  enabled: true                           # false skips reads + writes entirely
  ttl_days: 7                             # entry expiry; 0 → DefaultTTL (7 days)
guard:
  secret_scan: true                       # false disables the credential scanner
cost:
  warn_threshold_usd: 0.50                # prompt-or-abort above this; <=0 disables

Per-field reference

Dotted path	Type	Default	Notes
`provider`	string	`anthropic`	Active provider. Must match a registered provider name.
`providers.<name>.api_key`	string	`""`	Provider API key. Not used by `ollama`, `claude-cli`, `gemini-cli`.
`providers.<name>.model`	string	`""`	Provider-specific model. Empty → provider’s `DefaultModel()`.
`providers.ollama.base_url`	string	`http://localhost:11434`	Ollama daemon endpoint.
`output.lang`	string	`en`	Locale. Supported: `en`, `tr`. Unsupported codes coerce to `en`.
`output.color`	string	`auto`	`auto` / `always` / `never`. `--color` flag overrides.
`cache.enabled`	bool	`true`	`false` skips both reads and writes.
`cache.ttl_days`	int	`7`	Days until expiry. `0` → 7 days. Cannot be negative.
`guard.secret_scan`	bool	`true`	`false` disables the credential scanner.
`cost.warn_threshold_usd`	float	`0.50`	Cost ceiling. `0` or negative disables.

Environment variables

CommitBrief reads these at startup; they override config file values but lose to CLI flags.

Variable	Effect
`ANTHROPIC_API_KEY`	Sets `providers.anthropic.api_key`.
`OPENAI_API_KEY`	Sets `providers.openai.api_key`.
`GEMINI_API_KEY`	Sets `providers.gemini.api_key`.
`OLLAMA_HOST`	Sets `providers.ollama.base_url`.
`COMMITBRIEF_CONFIG`	Override the user-level config path (absolute).
`LANG` / `LC_ALL`	Fallback locale when `output.lang` is unset.
`NO_COLOR`	Force color OFF regardless of `output.color` / `--color`.
`COMMITBRIEF_NO_COLOR`	CommitBrief-specific equivalent of `NO_COLOR`.

Editing config

Three ways:

1. Interactive — `commitbrief setup`

Rewrites the active provider’s block (non-destructive for others). --local writes to the repo-local file. See First-time setup.

2. Programmatic — `commitbrief config`

commitbrief config show                 # YAML dump, API keys masked
commitbrief config get cache.ttl_days   # read one field
commitbrief config set provider openai  # write one field
commitbrief config set providers.openai.model gpt-4o-mini

Type coercion + validation: booleans accept true/false/yes/no/1/0/on/off (case-insensitive); integers are bounds-checked (no negatives for cache settings); output.color is enum-validated against auto/always/never; provider is validated against the registered factory list. version is rejected — it’s managed by migrations.

3. Hand-edit

Edit the YAML files directly. Hand-edits are loaded atomically on the next CLI invocation; no daemon to restart. File mode is 0600; the parent directory is 0700.

Inspecting the merged config

commitbrief config show

Dumps the resolved config as YAML with API keys masked. Useful for “is this what I think it is?” sanity checks.

commitbrief providers list

Shows every configured + registered provider, marks the active one, displays the model and a masked API-key fingerprint (or the base URL for Ollama).

Dry-run

To see how a real review would resolve all of the above — diff fetch + filter + rules + prompt + cache-key compute — without making a provider call:

commitbrief dry-run --staged --verbose

Reports per-layer filter counts, the merged rules source, the resolved language, the estimated tokens + cost, and the cache key that would be looked up.

Permissions

~/.commitbrief/config.yml is written 0600. The directory is 0700.
<repo>/.commitbrief/config.yml is written 0600; the .commitbrief/ directory is 0700. The repo’s .gitignore is updated to include .commitbrief/ if not already present.

API keys are masked when printed by commitbrief config show and commitbrief providers list; they never appear in logs.