Configuration files

Configuration files

CommitBrief uses a two-tier YAML configuration with field-level merge.

Files

Tier	Path	Notes
User-level	~/.commitbrief/config.yml	Defaults that apply everywhere.
Repo-local	<repo-root>/.commitbrief/config.yml	Per-repo overrides. Gitignored — auto-added on first write.

Either file may be absent; commitbrief.Default() fills in a reasonable skeleton when both are missing.

The user-level path can be overridden via the COMMITBRIEF_CONFIG environment variable — see Environment variables.

Merge order (lowest → highest priority)

1. config.Default() skeleton (built into the binary).
2. User-level YAML (~/.commitbrief/config.yml).
3. Repo-local YAML (<repo>/.commitbrief/config.yml).
4. Environment variables (see Environment variables).
5. CLI flag overrides (--provider, --model, --lang).

Higher entries override lower ones on a field-by-field basis, not whole-file replacement. So a repo-local providers.openai.model: gpt-4o-mini overrides only that field, not the user-level Anthropic key.

YAML schema

version: 1                                   # schema version (currently 1)
provider: anthropic                          # active provider name
providers:                                   # per-provider settings
  anthropic:
    api_key: sk-ant-...                      # secret; never logged
    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         # no api_key for Ollama
    model: qwen2.5-coder:14b
  claude-cli:                                # uses local `claude` binary
    model: ""                                # ignored; CLI manages its own
  gemini-cli:                                # uses local `gemini` binary
    model: ""
output:
  lang: en                                   # supported: en | tr; unsupported codes coerce to en
  stream: true                               # currently unused but reserved
  color: auto                                # auto | always | never (overridden by --color)
cache:
  enabled: true                              # false skips cache lookups + writes entirely
  ttl_days: 7                                # entry expiry; 0 falls back to DefaultTTL = 7 days
guard:
  secret_scan: true                          # false disables the credential scanner
cost:
  warn_threshold_usd: 0.50                   # prompt-or-abort if estimated cost > threshold; <=0 disables

cache.max_size_mb was removed in v0.9.1; setting it now errors as unknown field "max_size_mb" in cache (allowed: enabled, ttl_days).

Per-field reference

Dotted path	Type	Default	Notes
version	int	1	Schema version. Currently always 1; bumped on a breaking schema change.
provider	string	anthropic	Active provider. Must match a registered provider name.
providers.<name>.api_key	string	(empty)	Provider API key. Not used by ollama, claude-cli, gemini-cli.
providers.<name>.model	string	(empty)	Provider-specific model. Empty → use provider's DefaultModel().
providers.<name>.base_url	string	(empty for most; http://localhost:11434 for ollama via defaults)	Override the API endpoint. Used by ollama.
output.lang	string	en	Locale code. Supported: en, tr. Unsupported codes are silently coerced to en (since v0.9.2).
output.stream	bool	true	Currently reserved; not used at runtime.
output.color	string	auto	auto / always / never. The --color flag overrides this.
cache.enabled	bool	true	false skips both cache reads and writes for the entire run.
cache.ttl_days	int	7	Entry expiry in days. Cannot be negative. 0 → cache.DefaultTTL (7 days).
guard.secret_scan	bool	true	false disables the pre-send credential scanner entirely.
cost.warn_threshold_usd	float	0.50	Cost ceiling above which the preflight prompts (TTY) or aborts (non-TTY). 0 or negative disables.

Editing the files

Three options:

1. Interactive: commitbrief setup (rewrites the provider/model block for one provider; non-destructive for others).
2. Programmatic: commitbrief config set <key> <value> — see Config command.
3. Hand-edit the YAML files directly. Hand-edits are loaded atomically on the next CLI invocation; no daemon to restart.

File modes and permissions

• ~/.commitbrief/config.yml is written 0600 (owner read/write). 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.