Reference: pr-brief

Commands

Command	What it does	Main flags
`pr-brief init`	Sets a repo up: writes .pr-brief.json, and optionally the PR template and the CI check (a GitHub workflow, or an Azure Pipelines file). `--rewrite` adds a job that lets the Claude Code GitHub Action write the description (GitHub only; you choose `--auth`). Never overwrites. With `--config inline` the style and theme go in the CI file and no .pr-brief.json is written.	`--pr-template --workflow --host github\|azure-devops --config file\|inline --rewrite --auth federation\|bedrock\|vertex\|api-key --style S --theme T --dir D`
`pr-brief shape`	Reads the git diff and prints the flows to draw, the references, and the files ranked by risk, as JSON.	`--base REF --head REF --working-tree --title T --dir D`
`pr-brief diagram`	Draws one flow as a complete Mermaid diagram in a theme.	`--flow FILE\|- --report FILE --flow-number N --theme T --raw`
`pr-brief gate`	Checks a description with fixed rules and no AI. Exit 0 passes, 1 means findings, 2 means a usage or config error. `--ci` reads a GitHub pull request event; in an Azure pipeline use `--stdin`. See the gate.	`--hook --ci --file F --stdin --host github\|azure-devops --style S --json`
`pr-brief lint`	Runs the ASD-STE100 lint on prose. A Go port of ste-lint.py.	`--file F --json`
`pr-brief config`	Reads and writes the settings.	`show [--json] [--ci]` `get KEY` `set KEY VALUE --scope user\|repo` `init` `validate`
`pr-brief links`	Makes each file in the Read-these-first table a link, so a reviewer opens it from the description. With `--pr N` the link goes to the file’s diff in the PR, which always shows the latest commit. Without it, the link goes to the file on the branch. It never links to a commit. Prints the new description.	`--body F --pr N --branch B --remote URL`
`pr-brief theme`	Lists, shows and validates themes.	`list` `show [NAME\|FILE] [--json]` `validate FILE`
`pr-brief body`	Rewrites an existing description safely.	`improve` `past` `restore` `uncomment`
`pr-brief version`	Prints the version.

Run any command with -h for its flags. The binary is bin/pr-brief in the plugin; it picks the right build for your machine.

Settings and precedence

Key	Values	Default
`style`	`ste+iceberg` `ste` `iceberg`	`ste+iceberg`
`improve.previous`	`drop` `comment`	`drop`
`diagram.theme`	a built-in name, or a path to a `.json` theme file	`github-dark`

Order	Source	Notes
1	A flag	`--style` on one run. CI ignores flags.
2	The repo file `.pr-brief.json`	At the git top-level. Committed, so the whole team shares it. CI reads it from the base commit.
3	Your user file `~/.config/pr-brief/config.json`	Or `$XDG_CONFIG_HOME/pr-brief/config.json`. CI ignores it.
4	The default	`ste+iceberg`, `drop`, `github-dark`

Everything else is a fixed convention.

Where things live

What	Where
Repo settings	`.pr-brief.json` at the repo root
Your settings	`~/.config/pr-brief/config.json`
Saved descriptions	`~/.local/state/pr-brief/<host>/<owner>/<repo>/<pr>/<timestamp>-NN.md`. One is written before every `body improve`, whatever the setting. `pr-brief body restore` prints one.
Theme files	Anywhere for you; inside the repo for a repo config

Markers

<!-- pr-brief:begin v1 style=ste+iceberg theme=github-dark -->
## Brief
...
<!-- pr-brief:end -->

<!-- pr-brief:previous v1 saved=2026-10-05T14:02Z
the earlier human description, every "--" written as "-&#45;"
pr-brief:previous:end -->

> pr-brief skipped: <reason>                  # skip one PR
<!-- pr-brief:no-diagram: <reason> -->          # a small or config-only PR

The begin marker names the style and the theme. When a config names them, the config wins, so a marker cannot weaken the gate. A theme is a built-in name or custom:<8 hex>.

JSON Schemas

Schema	For
pr-brief.schema.json	The settings file. Unknown keys are errors.
pr-brief-theme.schema.json	A custom theme file.
pr-brief-flow.schema.json	The input of `pr-brief diagram`: node-link shaped, with `inputs`, `nodes`, `outputs` and `edges`. `pr-brief shape` emits this shape.

A test keeps each schema in step with the Go types.