# Run your first review

> Three commands from a fresh CommitBrief install to your first structured code review on staged changes.

CommitBrief docs · v1.x · Getting Started

Canonical URL: https://commitbrief.com/docs/1.x/first-review

---

Three steps from a fresh install to your first review.

## 1. Configure a provider

```sh
commitbrief setup
```

The interactive wizard asks 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`).
- **Model** — picked from the provider's static list. For Ollama,
  the wizard queries `<base_url>/api/tags` and lists models you
  have pulled locally.
- **Connection test** — a fast ping against the chosen provider
  with the credentials you entered. A failure aborts the wizard.

On success, the configuration is written to
`~/.commitbrief/config.yml` (mode `0600`). Pass `--local` to write
the repo-local `<repo>/.commitbrief/config.yml` instead — useful
when one repo needs different credentials. The repo-local path is
added to `.gitignore` automatically.

See [Providers](/docs/1.x/providers) for which one to pick.

## 2. (Optional) Scaffold project rules

```sh
commitbrief init
```

Writes two files in the current repo:

- `COMMITBRIEF.md` at the repo root — team-shared review rules,
  perspectives, project context. Sent to the LLM as the system
  prompt. **Commit this** to git.
- `.commitbrief/OUTPUT.md` — per-user Go `text/template` controlling
  how findings are formatted locally (used by `--markdown` /
  `--output <file>.md`). Gitignored by default.

Both files fall back to embedded defaults at runtime, so skipping
this step is fine for a first try. See
[Review rules](/docs/1.x/review-rules) for the file formats.

## 3. Review changes

Stage some changes, then:

```sh
commitbrief --staged
```

Equivalent forms for other scopes:

```sh
commitbrief                          # = --staged (default)
commitbrief --unstaged               # working-tree changes
commitbrief diff HEAD                # working tree vs HEAD
commitbrief diff HEAD~3 HEAD         # the last three commits
commitbrief diff main feature        # one branch vs another
commitbrief diff main...feature      # three-dot range (PR style)
```

Narrow any scope with repeatable path filters:

```sh
commitbrief --staged --file src/main.go --file src/util.go
commitbrief --unstaged --dir database/seeder
commitbrief diff HEAD~3 HEAD --dir docs
```

See [Review scopes](/docs/1.x/review-scopes) for the full
breakdown.

## What you see

A typical review prints in this order:

1. The splash logo (stderr, TTY only).
2. Per-stage progress: searching → diff stats → preparing → thinking.
3. Severity-coded panel per finding (lipgloss header / status /
   footer).
4. An optional verbose footer with provider / model / tokens /
   cost / latency when `--verbose` (`-v`) is set.

Use `--json` for machine output, `--markdown` for plain markdown
(no ANSI), `--output <file>` to redirect, or `--copy` to push
the findings to the system clipboard via OSC 52. See
[Output formats](/docs/1.x/output-formats).

## Verify the pipeline

```sh
commitbrief doctor
```

Runs eight checks against the resolved environment: git on PATH,
config schema, COMMITBRIEF.md source, OUTPUT.md template,
configured provider, active provider has credentials, cache
directory writable, repo `.gitignore` includes `.commitbrief/`.
Exits non-zero on any fail — safe to wire into CI as a config
gate. See [Troubleshooting](/docs/1.x/troubleshooting) for what
each row means.

## Next steps

- **[Install a git hook](/docs/1.x/git-hooks)** to run a review
  on every commit or push.
- **[Customise review rules](/docs/1.x/review-rules)** with
  project-specific context in `COMMITBRIEF.md`.
- **[Pick a different provider](/docs/1.x/providers)** —
  `commitbrief providers use openai` switches without re-entering
  keys.
- **[Inspect the pipeline](/docs/1.x/configuration#dry-run)** with
  `commitbrief dry-run` — same path, no provider call.