Global flags

Home / Configuration / Global flags

Global flags

Every flag below is PersistentFlags() on the root command, so it works on the bare review (commitbrief --staged) and on every subcommand that does not override it (commitbrief dry-run --json, commitbrief diff HEAD --copy, …).

The --staged / --unstaged scope flags are also re-bound on dry-run — they are scope-specific, not strictly global. Most subcommands ignore them.

Output

Flag	Short	Type	Default	Notes
--json	—	bool	false	Emit machine-readable JSON output (schema v1). Suppresses the cards renderer.
--markdown	—	bool	false	Emit plain markdown (no ANSI).
--output <path>	-o	string	(stdout)	Write output to file instead of stdout. Honored by both the structured renderers and the plain-text emit path used by CLI-tool-backed providers (UC-07).
--copy	—	bool	false	Copy findings (severity, path, title, description) to the system clipboard via OSC 52 + native tool (wl-copy / xclip / xsel). Best-effort; failures are silent.
--compact	—	bool	false	One-line-per-finding dense output.
--verbose	-v	bool	false	Show token / cost / latency footer below the findings.
--quiet	-q	bool	false	Suppress info messages on stderr (progress, "using built-in rules", etc.).
--color <mode>	—	string	auto	auto / always / never. Auto detects TTY. NO_COLOR / COMMITBRIEF_NO_COLOR env vars override always.
--lang <code>	—	string	(config / en)	AI output language (any recognized language, e.g. tr/fr/de). The CLI interface localizes only for en/tr, else English. Chain: --lang → repo output.lang → user output.lang → English; invalid/empty falls through (ADR-0021).

Filtering

Flag	Short	Type	Default	Notes
--file <path|glob>	-f	string slice	(none)	Review only these files (repeatable). A plain path matches exactly; a value with */?/[ is a gitignore-style glob (e.g. *.go, internal/**/*.ts).
--dir <path|glob>	-d	string slice	(none)	Review only files under these directories (repeatable). A plain path is a <dir>/ prefix; a glob value (e.g. app/**) is matched gitignore-style.
--exclude-file <path|glob>	—	string slice	(none)	Skip these files (repeatable). Identical matching rules to --file, applied after it.
--exclude-dir <path|glob>	—	string slice	(none)	Skip files under these directories (repeatable). Applied after --dir.

All four combine with the active scope flag and apply after the ignore layers. Globs are slash-anchored when the pattern contains a slash, else match the basename at any depth; repeat the flag rather than comma-joining patterns. An invalid glob errors before any provider call. The denylist runs last, so an exclusion always wins: --dir internal --exclude-dir internal/cli. See Filtering.

Commit selection

These pick a set of commits instead of a diff, so they replace --staged / --unstaged rather than combining with them (neither scope has commits yet). Not accepted by commit or remote pr.

Flag	Type	Default	Notes
--author <person>	string slice	(none)	Commits authored by this person — case-insensitive substring of the name or the email (repeatable; multiple values are OR'd).
--committer <person>	string slice	(none)	Same, on the committer identity. Differs from the author after a rebase or cherry-pick.
--start-date <YYYY-MM-DD>	string	(none)	Author date on or after this day, inclusive. Strict format — not git's approxidate.
--end-date <YYYY-MM-DD>	string	(none)	Author date on or before this day, inclusive (expanded to 23:59:59 local, unlike git's bare --until).
--text <string>	string	(none)	Commit message contains this text, or the commit is unique to a branch whose name contains it. Case-insensitive.
--max-commits <N>	int	0 (⇒ 200)	Cap the selection. Truncation is always reported, even under --quiet.
--merges	bool	false	Keep merge commits, which are excluded by default.

Different kinds are AND'd, multiple values of one kind are OR'd. With no positional range the walk covers HEAD; a subcommand's range bounds it (commitbrief diff main..develop --author alice). --merges and --max-commits are modifiers — using either without a selecting filter is an error. The reviewed diff is the concatenation of the matching commits' patches. Full detail in Filtering.

Provider / model

Flag	Type	Default	Notes
--provider <name>	string	(from config)	Override configured provider for this invocation. Mutually exclusive with --cli.
--model <name>	string	(from config)	Override configured model for this invocation.
--cli <claude|gemini|codex>	string	(none)	Shorthand for --provider claude-cli / gemini-cli / codex-cli. Mutually exclusive with --provider, --json, --markdown (UC-07).
--with-context	bool	false	CLI providers only. Let the host CLI read project files beyond the diff (read-only, in the repo root) to ground the review (ADR-0017). Errors with an API provider. Prints a security caution each run — the agent may read files outside the diff (incl. untracked secrets) and the pre-send secret scan covers the diff only. See Provider: CLI tools.

Cache + guards

Flag	Type	Default	Notes
--no-cache	bool	false	Bypass cache (read AND write). Forces a fresh provider call.
--allow-secrets	bool	false	Bypass the pre-send secret scanner. Use with care.
--no-cost-check	bool	false	Skip the pre-send cost estimate prompt.
--no-flaky	bool	false	Skip the deterministic flaky-test detector pre-pass (ADR-0022). Overrides review.flaky. Inert for CLI-tool-backed providers. See Review.
--sandbox-rerun[=N]	int	0 (off)	Opt-in sandbox-rerun confirmation of flagged flaky tests (ADR-0022/ADR-0033): re-run each in isolation N times and classify by the pass/fail mix (mixed → confirmed flaky, all-fail → real failure, all-pass → transient/info). Bare --sandbox-rerun ⇒ N=5; overrides review.sandbox_rerun. Double opt-in: this flag/config only takes effect together with a non-empty review.sandbox_command (hand-edit only — config set rejects it); either alone is a no-op. Never runs on commitbrief mcp/guard. Test-name resolution is Go-only. See Review.
--no-architecture	bool	false	Skip architecture-aware review (ADR-0030): do not read architecture.json into the prompt for this run. Overrides review.architecture. See Architecture-aware review.
--show-prompt	bool	false	Print the exact system + user prompt that would be sent to the model, then exit. No provider call, no cache lookup, no cost. Reflects every prompt-shaping flag (scope, --with-context, --cli / --provider, --lang) and honours --output. A transparency inspector for "what exactly leaves my machine?" — fuller than dry-run, which shows only metadata.
--yes (-y)	bool	false	Auto-confirm prompts (pre-send .commitbrief/ guard, init overwrite, cache clear). Since v0.9.1, --yes does not bypass the secret scanner or cost preflight — use the dedicated flags above.

CI gating

Flag	Type	Default	Notes
--fail-on <sev>	string	"" (off)	Exit 1 if any finding meets/exceeds severity. Values: critical, high, medium, low, info, any, none. See Exit codes.
--min-severity <sev>	string	"" (off)	Display-only filter: hide findings below this severity in the rendered output (Cards, Markdown, --copy). Values: critical, high, medium, low, info, none. --json stays complete (machine contract) and --fail-on always evaluates the full set, so CI gating is never weakened. An invalid value errors.

Signal control (ADR-0027)

A baseline and inline suppression cut repeat noise. Unlike --min-severity (display-only), these are true removals: a removed finding no longer counts toward --fail-on, no longer appears in --json findings[], and is hidden from the render. Removed counts are reported, never silent — additive optional meta.baselined / meta.suppressed fields in --json (schema stays v1) and a one-line N baselined · M suppressed stderr footer.

Flag	Type	Default	Notes
--update-baseline	bool	false	Rewrite .commitbrief/baseline.json from the current findings (accept them all) instead of filtering this run. The file is user-private + gitignored (per-developer; never committed; CI/the senior gate apply no baseline). Mutually exclusive with --no-baseline.
--no-baseline	bool	false	Ignore the signal-control baseline for this run (show everything, even baselined findings). Overrides review.baseline. Mutually exclusive with --update-baseline.

The fingerprint stored in the baseline is sha256(File + Severity + normalize(Title)) — resilient to line drift (a finding that moves up/down the file stays baselined) and independent of the LLM-volatile description/snippet. Toggle the whole baseline off persistently with review.baseline: false.

Inline suppression needs no flag: add a commitbrief-ignore: <reason> (or commitbrief-ignore[<severity>]: <reason>) comment on the offending line, or the line directly above it. A scoped marker silences only that severity; unscoped silences any. The comment prefix is irrelevant (//, #, --, /* */). The marker is read from the added diff lines, so it lives in committed source and a reviewer sees it. See Review. | --suggest-commit | — | bool | false | After the review, make a second free-form call and print a single Conventional Commit message for the staged diff to stdout. Read-only — suggests, never writes git. Requires the staged scope (--staged or the default run); rejected with --unstaged, the diff subcommand, and --json / --markdown / --output. Works with any provider. See Review. |

Hidden flags

Flag	Type	Default	Notes
--gen-man <dir>	string	(none)	Generate man pages into <dir> and exit. Used by make manpage; hidden from --help.

Mutually exclusive groups

Enforced by cobra; passing both flags is an error before any work begins.

• --provider × --cli
• --cli × --json
• --cli × --markdown
• --staged × --unstaged
• --update-baseline × --no-baseline
• (compress) --dry-run × --out

Checked at run time rather than by cobra:

• --staged / --unstaged × any commit filter (--author, --committer, --start-date, --end-date, --text) — a commit walk has no index or working tree to read.
• --merges / --max-commits without a commit filter — a modifier with nothing to modify.

Version

commitbrief --version

Prints commitbrief vX.Y.Z (commit <sha>, built <iso-ts>) and nothing else — the splash logo is suppressed for --version so the output is a single machine-parseable line (safe to pipe into a script). The commit and date are ldflags-injected at release time; go install fills the version from runtime/debug.BuildInfo but leaves commit/date as none / unknown.

Help

commitbrief --help
commitbrief <subcommand> --help

Standard cobra-rendered help. commitbrief list is the richer, human-curated reference.

See also

• Filtering — how --file / --dir narrow scope.
• Output formats — --json, --markdown, cards.
• Exit codes — --fail-on and CI gating.
• Configuration files — config that flags override.