// docs · v1.x

Flags

Every flag CommitBrief accepts, grouped by command and generated from the binary's own surface inventory — global flags first, then each command's local flags.

Updated September 23, 2026

CommitBrief’s flags split into two scopes. Global flags are declared on the root command and inherited by every subcommand, so every subcommand accepts them — --json, --quiet, --provider, and the path/commit filters all parse on commitbrief, commitbrief diff, and commitbrief remote pr alike. Accepting a flag isn’t the same as honoring it, though: in its default posting mode, remote pr rejects --json/--markdown/--output/--copy/--compact — those five are exempted under --no-post, since that mode renders locally instead of posting to GitHub. The commit filters (--author, --committer, --start-date, --end-date, --text) are rejected in every mode, --no-post included, because remote pr’s diff always comes from gh pr diff, never a local commit walk — see remote pr’s behavior notes for the exact list. Command flags exist only on the command they’re listed under below — commit’s --type has no meaning to map, and --branches has no meaning outside map.

The table below groups every non-hidden flag under the command it belongs to. The root group, commitbrief, holds both: in that table, --staged and --unstaged are local to the default review invocation itself; everything else in that group is global. Local flags don’t carry over to commit, guard, or any other subcommand. This page doesn’t repeat that split per row; when a flag’s behavior depends on which scope it’s in, the command’s own page says so.

commitbrief

Name	Type	Default	Usage
`--allow-secrets`	bool	`false`	bypass the pre-send secret scanner (use with care)
`--author`	stringSlice	`[]`	review only commits authored by these people (repeatable; matches name or email, case-insensitive). Switches the scope to a commit walk
`--cli`	string	—	use a locally-installed CLI tool (claude\|gemini\|codex) as the review backend; shorthand for --provider <name>-cli
`--color`	string	`auto`	color output: auto, always, never
`--committer`	stringSlice	`[]`	review only commits committed by these people (repeatable; matches name or email, case-insensitive)
`--compact`	bool	`false`	one-line per finding (dense review output)
`--copy`	bool	`false`	copy findings (severity, path, title, description) to the system clipboard via OSC 52 + native tool
`--dir`	stringSlice	`[]`	review only files under these directories or matching dir globs (e.g. `internal/**`; repeatable, one pattern per flag); combines with the active scope flag
`--end-date`	string	—	review only commits on or before this date (YYYY-MM-DD, inclusive)
`--exclude-dir`	stringSlice	`[]`	skip files under these directories or matching dir globs (repeatable, one pattern per flag); applied after --dir so an exclusion wins
`--exclude-file`	stringSlice	`[]`	skip these files or globs (repeatable, one pattern per flag); same matching rules as --file, applied after it so an exclusion wins
`--fail-on`	string	—	exit 1 if any finding meets/exceeds severity (critical\|high\|medium\|low\|info\|any\|none)
`--file`	stringSlice	`[]`	review only these files or globs (e.g. `.go`, `internal//.ts`; repeatable, one pattern per flag — patterns can't be comma-joined); combines with the active scope flag
`--ignore-unknown-config`	bool	`false`	continue when config.yml holds a key the schema doesn't define, instead of failing; every ignored key is still named in a warning on stderr (the setting has no effect — fix the key)
`--json`	bool	`false`	emit machine-readable JSON output
`--lang`	string	—	AI output language (e.g. tr, fr); the CLI interface localizes for en/tr only, output for any recognized language. Resolution: --lang → repo config → user config → English
`--markdown`	bool	`false`	emit plain markdown (no ANSI)
`--max-commits`	int	`0`	cap how many matching commits enter the review (0 = 200); only meaningful with another commit filter
`--merges`	bool	`false`	include merge commits in a commit-filtered review (excluded by default); only meaningful with another commit filter
`--min-severity`	string	—	hide findings below this severity in the rendered output (critical\|high\|medium\|low\|info); --json and --fail-on still see the full set
`--model`	string	—	override configured model
`--no-architecture`	bool	`false`	skip architecture-aware review (do not read architecture.json into the prompt) for this run (ADR-0030)
`--no-baseline`	bool	`false`	ignore the signal-control baseline for this run (show everything, even baselined findings)
`--no-cache`	bool	`false`	bypass cache (read and write)
`--no-cost-check`	bool	`false`	skip the pre-send cost estimate prompt
`--no-flaky`	bool	`false`	skip the deterministic flaky-test detector (ADR-0022)
`--output`	string	—	write output to file instead of stdout
`--provider`	string	—	override configured provider
`--quiet`	bool	`false`	suppress info messages on stderr
`--sandbox-rerun`	int	`0`	confirm flagged flaky tests by re-running each in isolation N times (ADR-0022); mixed pass+fail = confirmed flaky, all-fail = real failure, all-pass = transient. 0 = off; bare --sandbox-rerun uses N=5. Requires a bound rerun executor
`--show-prompt`	bool	`false`	print the exact system + user prompt that would be sent, then exit (no provider call, no cost)
`--start-date`	string	—	review only commits on or after this date (YYYY-MM-DD, inclusive)
`--suggest-commit`	bool	`false`	after the review, suggest a Conventional Commit message for the staged diff (requires --staged; prints to stdout; not with --json/--markdown/--output)
`--text`	string	—	review only commits whose message contains this text, plus commits unique to a branch whose name contains it (case-insensitive)
`--timeout`	string	—	bound the whole run to this `duration` — 90s, 10m, 1h30m, or a bare number of seconds (600). Covers diff, provider call, render, and time spent at a confirmation prompt. Also RAISES the provider's own cap (claude/gemini/codex-cli 5m, ollama 5m, Anthropic SDK 10m), which a deadline alone cannot do. Unset or 0 keeps those built-ins. Resolution: --timeout → review.timeout → built-in
`--update-baseline`	bool	`false`	rewrite .commitbrief/baseline.json from the current findings (accepts them all) instead of filtering this run; user-private, gitignored (ADR-0027)
`--verbose`	bool	`false`	show token/cost/latency footer
`--with-context`	bool	`false`	let the CLI provider read project files beyond the diff to ground the review (CLI providers only; the host CLI's agent reads your repo — see --help)
`--yes`	bool	`false`	auto-confirm prompts (pre-send guard, init overwrite)
`--staged`	bool	`false`	review staged changes (default)
`--unstaged`	bool	`false`	review unstaged changes

commitbrief cache inspect

Name	Type	Default	Usage
`--show-content`	bool	`false`	also print the cached review body (omitted by default)

commitbrief cache prune

Name	Type	Default	Usage
`--keep-last`	int	`500`	keep only the N newest entries (per the provider/model filter); 0 means keep nothing
`--model`	string	—	only consider entries written for this model (matched against the model recorded in each entry)
`--older-than`	string	`7d`	delete entries older than this age. Units: d (day), w (week), m (month, 30d), y (year, 365d)
`--provider`	string	—	only consider entries written for this provider (e.g. anthropic, openai, gemini, ollama)

commitbrief commit

Name	Type	Default	Usage
`--generate`	int	`0`	offer N alternative messages to choose from (default 1, or commit.generate config)
`--type`	string	—	commit message format: plain\|conventional\|conventional+body\|gitmoji\|subject+body (default "plain", or commit.type config)

commitbrief compress

Name	Type	Default	Usage
`--dry-run`	bool	`false`	show the result summary; do not write or back up anything
`--level`	string	`balanced`	compression level: light \| balanced \| aggressive
`--out`	string	—	write result to this path instead of replacing COMMITBRIEF.md

commitbrief config set

Name	Type	Default	Usage
`--local`	bool	`false`	write to repo .commitbrief/config.yml instead of user-level

commitbrief doctor

Name	Type	Default	Usage
`--quiet`	bool	`false`	only print warning and failed checks

commitbrief dry-run

Name	Type	Default	Usage
`--staged`	bool	`false`	review staged changes (default)
`--unstaged`	bool	`false`	review unstaged changes

commitbrief guard

Name	Type	Default	Usage
`--diff`	stringSlice	`[]`	run-mode: review an arbitrary `git diff` range (e.g. main...HEAD); repeatable
`--from-json`	string	—	evaluate a prior schema-v1 review JSON (a file path, or - for stdin) instead of running a review
`--policy`	string	`.commitbrief/policy.yml`	path to the policy file
`--unstaged`	bool	`false`	run-mode: review the unstaged working tree instead of the staged index

commitbrief init

Name	Type	Default	Usage
`--force`	bool	`false`	overwrite existing COMMITBRIEF.md / OUTPUT.md (alias of --yes for init)

commitbrief install-hook

Name	Type	Default	Usage
`--hook`	string	`pre-commit`	git hook name (pre-commit \| commit-msg \| pre-push)
`--uninstall`	bool	`false`	remove a previously installed hook (only one this command wrote)

commitbrief leaks

Name	Type	Default	Usage
`--no-history`	bool	`false`	skip the commit-history half
`--no-worktree`	bool	`false`	skip the working-tree half
`--patterns`	bool	`false`	list the effective pattern set (built-ins + configured) and exit

commitbrief map

Name	Type	Default	Usage
`--all`	bool	`false`	walk every branch, not just the given range (commit graph only)
`--branches`	bool	`false`	show a branch topology summary instead of the commit graph

commitbrief providers use

Name	Type	Default	Usage
`--local`	bool	`false`	write to repo .commitbrief/config.yml instead of user-level

commitbrief remote pr

Name	Type	Default	Usage
`--no-post`	bool	`false`	review the PR diff and print locally (no GitHub writes); enables --json/--markdown/--output/--copy/--cli like a local review
`--repo`	string	—	target repository owner/repo (overrides git context)
`--request-changes-on`	string	—	opt in to a request-changes verdict at/above this severity (critical\|high\|medium\|low); omitted, the verdict is never request-changes (comment / approve only)

commitbrief setup

Name	Type	Default	Usage
`--alias`	string	—	install a shell alias for commitbrief (default cbr); skips the provider wizard. Use --alias for an interactive prompt or --alias=<name> to set it directly
`--local`	bool	`false`	save to repo .commitbrief/config.yml instead of user-level

commitbrief summary

Name	Type	Default	Usage
`--staged`	bool	`false`	review staged changes (default)
`--unstaged`	bool	`false`	review unstaged changes

commitbrief upgrade

Name	Type	Default	Usage
`--check`	bool	`false`	only report whether a newer version exists; install nothing

Two build-only flags are excluded: --gen-surface regenerates this site’s own surface data, and --gen-man generates the CLI’s man pages (man/*.1) — neither is part of the flags a normal invocation uses.