First time setup

Home / Getting started / First-time setup

First-time setup

TL;DR

commitbrief setup          # provider + key + model wizard
commitbrief doctor         # verify everything wired up
commitbrief --staged       # first review (after staging changes)

Detailed flow

1. Pick a provider

Run commitbrief setup. It prompts for:

• Provider — Anthropic, OpenAI, Gemini, or Ollama.
• API key — for Anthropic / OpenAI / Gemini. Ollama needs no key, but asks for a base URL (default http://localhost:11434). If the selected provider already has a key in the target config, the prompt lets you leave it blank to keep the existing key — so re-running setup just to switch provider/model never forces a key re-entry. (To change only the active provider or model without the wizard at all, use commitbrief providers use <name> and commitbrief config set providers.<name>.model <model>.)
• Model — picked from the provider's static list (see each Provider page). For Ollama, the wizard queries OLLAMA_HOST/api/tags to list models you have pulled locally; if discovery fails it falls back to a free-text entry.
• Connection test — a fast ping against the chosen provider with the credentials you entered. A failure aborts the wizard.

2. Where the config is written

By default the wizard writes to ~/.commitbrief/config.yml (user-level). Pass --local to write <repo>/.commitbrief/config.yml instead — repo-local config overrides user-level on a field-by-field basis. The repo-local path is added to .gitignore automatically the first time it is used, so API keys never accidentally get committed.

3. Verify the pipeline

commitbrief doctor

Runs eight checks (git on PATH, config valid, COMMITBRIEF.md source, OUTPUT.md template, at-least-one provider configured, active provider has credentials, cache directory writable, repo .gitignore includes .commitbrief/) plus a per-provider connection ping. Exits non-zero if any check fails. Detail at Doctor command.

4. (Optional) Provide an API key without typing it

The wizard reads from these environment variables if set; the displayed prompt is masked but you can also bypass the wizard entirely by writing the config directly:

commitbrief config set provider anthropic
commitbrief config set providers.anthropic.api_key sk-ant-…
commitbrief config set providers.anthropic.model claude-opus-4-8

See Config command for the dotted-path syntax.

5. (Optional) Test a different provider without switching

commitbrief providers test gemini

Pings the named provider with whatever credentials are in your config. Reports latency and exits non-zero on failure. Does not modify state. Detail at Providers command.

6. (Optional) Switch the active provider

commitbrief providers use openai

Updates config.provider to the new value. Does not touch any API keys. Detail at Providers command.

Common first-time issues

• git not found on PATH — install git first; CommitBrief shells out to it for several diff paths.
• active provider 'X' has no credentials — config.provider points at a provider whose api_key (or base_url, for Ollama) is empty. Either run commitbrief setup again, or commitbrief providers use <name> to switch to one you have set up.
• API key for provider … is not set — same root cause, surfaces later in the pipeline if doctor was skipped.
• .commitbrief/ not listed; run 'commitbrief setup --local' to add it — repo .gitignore is missing the entry. Either run commitbrief setup --local once, or add the line manually.

See also

• Setup command — the provider wizard in depth.
• Doctor command — pipeline verification checks.
• Quick start — condensed three-step path.
• Providers command — test and switch providers.