Configuration files

Home / Configuration / 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-8
  openai:
    api_key: sk-...
    model: gpt-4o
    pricing:                                 # optional: override built-in $/1M rates (OQ-09)
      gpt-4o:
        input_per_1m: 2.50
        output_per_1m: 10.00                 # omitted/zero fields keep the built-in value
        cached_input_per_1m: 1.25
  deepseek: { api_key: sk-... }              # + mistral, cohere — see [Providers](Providers)
  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
  max_size_mb: 0                             # on-disk cap; 0 = unlimited; >0 evicts oldest entries past the cap
guard:
  secret_scan: true                          # false disables the credential scanner
  token_preflight: false                      # opt-in: confirm/abort when the prompt overflows the model's context window
cost:
  warn_threshold_usd: 0.50                   # prompt-or-abort if estimated cost > threshold; <=0 disables
command:
  default: ""                                # args for a bare `commitbrief`; empty = --staged (e.g. "--unstaged --cli gemini")
commit:
  type: plain                                # default --type for `commitbrief commit`
  generate: 1                                # default --generate (alternatives to offer)

Note

cache.max_size_mb returned as a real key in v1.3.0 (size-bounded eviction). It was removed in v0.9.1 as dead config; the v1.3.0 key is read on the Put path. 0 (the default) keeps the cache unlimited.

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 and the OpenAI-compatible providers.
providers.<name>.pricing.<model>.input_per_1m	float	(built-in)	Override the input rate ($/1M tokens) for one model (OQ-09). Zero/omitted → built-in snapshot. Affects cost preflight, verbose footer, cached cost.
providers.<name>.pricing.<model>.output_per_1m	float	(built-in)	Override the output rate ($/1M tokens).
providers.<name>.pricing.<model>.cached_input_per_1m	float	(built-in)	Override the cached-input rate ($/1M tokens).
output.lang	string	en	AI output language (any recognized language, e.g. en/tr/fr/de). The CLI interface localizes only for en/tr, else English. Chain --lang→repo→user→English; invalid/empty falls through. config set validates (ADR-0021).
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).
cache.max_size_mb	int	0	On-disk cache cap in MiB. Cannot be negative. 0 = unlimited. When >0, each write that pushes the cache past the cap evicts the oldest entries first (the just-written entry is never evicted). Inspect with cache stats / cache inspect.
guard.secret_scan	bool	true	false disables the pre-send credential scanner entirely.
guard.token_preflight	bool	false	Opt-in. When true, a review whose estimated prompt (chars/4 heuristic) exceeds the provider's context window prompts for confirmation on a TTY, or aborts non-interactively, before the paid call — instead of a raw provider 400. Off by default so a heuristic false positive never blocks an unguarded review (ADR-0003).
cost.warn_threshold_usd	float	0.50	Cost ceiling above which the preflight prompts (TTY) or aborts (non-TTY). 0 or negative disables.
command.default	string	""	Argument string applied to a bare commitbrief (no args) — e.g. --unstaged --cli gemini. Bypassed the moment any flag/subcommand is passed. Empty = built-in --staged. Whitespace-split; no shell quoting.
commit.type	string	plain	Default --type for commitbrief commit. One of plain, conventional, conventional+body, gitmoji, subject+body. Overridden by the --type flag.
commit.generate	int	1	Default --generate for commitbrief commit — how many message alternatives to offer (1–10). Overridden by the --generate flag.

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.

See also

• Environment variables — env overrides and precedence.
• Global flags — flags that override config.
• Config command — read and set config keys.
• Providers — per-provider settings reference.