mergebrief 0.0.0-stage → 0.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +848 -2
- package/dist/mergebrief.js +24858 -0
- package/package.json +40 -4
package/README.md
CHANGED
|
@@ -1,3 +1,849 @@
|
|
|
1
|
-
#
|
|
1
|
+
# mergebrief
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
The MergeBrief CLI — the Brief review loop for humans and AI agents, over
|
|
4
|
+
your deployment's HTTP API. One binary-shaped npm package; the web app stays
|
|
5
|
+
the interactive surface.
|
|
6
|
+
|
|
7
|
+
Private in v1 (this monorepo dogfoods it via `pnpm --dir apps/cli
|
|
8
|
+
link-dev`); published to npm at OSS launch. Humans: `npm i -g mergebrief`.
|
|
9
|
+
Agents/CI: `npx mergebrief` — always-latest is safe, the output contract is
|
|
10
|
+
additive-only (see below). Pinning is supported but never required for
|
|
11
|
+
compatibility.
|
|
12
|
+
|
|
13
|
+
## Quickstart
|
|
14
|
+
|
|
15
|
+
1. **Mint a token** in the web app: sign in, open `/settings`, name the
|
|
16
|
+
token, pick the organization it is bound to, and choose an expiry.
|
|
17
|
+
The token is shown **exactly once** — treat it like a password. The CLI
|
|
18
|
+
stores it **in plaintext** in a `chmod 600` file under
|
|
19
|
+
`~/.config/mergebrief/`; anyone with the token can act as you in that
|
|
20
|
+
organization.
|
|
21
|
+
2. **Log in** (paste, or pipe the token on stdin):
|
|
22
|
+
|
|
23
|
+
```sh
|
|
24
|
+
mergebrief auth login --base-url https://mergebrief.your-org.example
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
3. **Check the wiring** — config level and server level in one shape:
|
|
28
|
+
|
|
29
|
+
```sh
|
|
30
|
+
mergebrief auth status --json
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
```json
|
|
34
|
+
{"profile":"default","baseUrl":"https://mergebrief.your-org.example","tokenConfigured":true,"cli":{"version":"1.2.0"},"server":{"reachable":true,"authenticated":true,"version":"1.4.0","latest":"1.6.0","releaseNotesUrl":"https://github.com/Idan91/code-review/releases/tag/v1.6.0","checkedAt":"2026-10-03T10:00:00.000Z","breaking":false,"security":false}}
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
4. **First read** — your Inbox, every installation you reach (no repo
|
|
38
|
+
targeting needed):
|
|
39
|
+
|
|
40
|
+
```sh
|
|
41
|
+
mergebrief pr --json
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
PR-addressed commands (`pr <n>`, `groups <n>`, `diff <n>`, …) pick the
|
|
45
|
+
repo from the clone's `origin` remote; `-R owner/name` overrides.
|
|
46
|
+
|
|
47
|
+
Driving an agent? Install the `mergebrief` skill
|
|
48
|
+
([skills/mergebrief](../../skills/mergebrief/SKILL.md)) — the review
|
|
49
|
+
workflow, the authority policy, and the wire contract:
|
|
50
|
+
|
|
51
|
+
```sh
|
|
52
|
+
npx skills add <owner>/<repo> --skill mergebrief -a <your-agent>
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
## The output contract (what scripts may rely on)
|
|
56
|
+
|
|
57
|
+
- **exit 0 ⇒ stdout is documented JSON** (or the raw unified diff, for
|
|
58
|
+
`diff`). **exit ≠ 0 ⇒ stdout is empty** and stderr carries exactly one
|
|
59
|
+
line — for server responses it relays the error text + HTTP status;
|
|
60
|
+
client-side usage and network/proxy failures explain themselves without
|
|
61
|
+
one.
|
|
62
|
+
- **Passthrough by default:** most commands emit the server response
|
|
63
|
+
verbatim — one canonical shape across web, API, and CLI. Exactly three
|
|
64
|
+
shapes are CLI-synthesized: the `delta` union, `auth status`, and
|
|
65
|
+
`capabilities`.
|
|
66
|
+
- **Additive-only, even pre-1.0:** fields are never removed, renamed, or
|
|
67
|
+
retyped within a major; new fields may appear any release — read
|
|
68
|
+
tolerantly. Breaking changes ship expand/contract with a deprecation
|
|
69
|
+
window in the changelog.
|
|
70
|
+
- `--json` is an explicit flag. TTY rendering is non-contractual.
|
|
71
|
+
|
|
72
|
+
### Exit codes (additive-only, never renumbered)
|
|
73
|
+
|
|
74
|
+
| Code | Meaning |
|
|
75
|
+
|---|---|
|
|
76
|
+
| 0 | Success — including modeled unavailability (`delta`'s `available:false` arm) |
|
|
77
|
+
| 1 | Generic/unexpected: network, 5xx, version skew |
|
|
78
|
+
| 2 | Usage error caught client-side (bad flags, `--group` with a custom span, malformed submit JSON shape) |
|
|
79
|
+
| 3 | Auth (401) — re-mint the token |
|
|
80
|
+
| 4 | Not found (repo/PR/group/span; incl. an unmodeled delta 404) |
|
|
81
|
+
| 5 | Server rejected the payload (4xx validation) — fix and retry; agent submit loops self-correct on this code |
|
|
82
|
+
| 6 | Incompatible: a `--require`d operation is not runnable on this server+CLI pair — do not drive it |
|
|
83
|
+
|
|
84
|
+
## Commands
|
|
85
|
+
|
|
86
|
+
### `repos`
|
|
87
|
+
|
|
88
|
+
The repositories your token can see (the installation ∩ your-access
|
|
89
|
+
intersection), cached per profile at `~/.cache/mergebrief/<profile>/` with
|
|
90
|
+
**no TTL** — the cache directory is always safe to delete. Renames self-heal
|
|
91
|
+
when a PR-addressed command resolves the new `owner/name` (one automatic
|
|
92
|
+
refresh on a slug miss); the `repos` listing itself needs `--refresh` to
|
|
93
|
+
show a rename.
|
|
94
|
+
|
|
95
|
+
```json
|
|
96
|
+
{"repos":[{"repoId":"812345","fullName":"acme/widgets"}]}
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
### `pr [n]`
|
|
100
|
+
|
|
101
|
+
No argument: the first page of your Inbox, verbatim (`{"items":[...],
|
|
102
|
+
"page":1,"pageSize":25,"total":n,...}`), every installation you reach plus
|
|
103
|
+
the pull requests you pasted. With a number: the
|
|
104
|
+
PR's metadata. Critical fields: **`baseSha`/`headSha`** — the brief span
|
|
105
|
+
your `submit` must name (never auto-fetched); `briefAvailable` — generation is
|
|
106
|
+
webhook-driven, poll with backoff, nothing client-side triggers it;
|
|
107
|
+
`comparisons.lastReview` — what `delta` resolves.
|
|
108
|
+
|
|
109
|
+
```json
|
|
110
|
+
{"repoId":"812345","repoSlug":"acme/widgets","prNumber":7,"title":"Extract tenant boundary","state":"open","baseSha":"93f1…","headSha":"4c0a…","briefAvailable":true,"generation":{"status":"succeeded","phase":null,"attempts":1,"error":null,"updatedAt":"2026-07-09T12:00:00.000Z"},"comparisons":{},"updatedAt":"2026-07-09T12:00:00.000Z"}
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
### `groups <n>`
|
|
114
|
+
|
|
115
|
+
The Brief artifact body, verbatim: `changeGroups` (each with an `id` —
|
|
116
|
+
`diff --group` takes it), `chunks` (per-file line ranges joining groups to
|
|
117
|
+
the diff), risk-surface attributes.
|
|
118
|
+
|
|
119
|
+
### `diff <n>`
|
|
120
|
+
|
|
121
|
+
The raw unified diff of the PR's brief span (or `--base <sha> --head <sha>`
|
|
122
|
+
together). The raw output **is** the machine format — `--json` is rejected
|
|
123
|
+
(exit 2). On a TTY it pipes through `$PAGER`.
|
|
124
|
+
|
|
125
|
+
`--group <id>` filters to one change group's **whole hunks** (the output is
|
|
126
|
+
itself a valid diff — `git apply --check` clean). Brief-span only: combining
|
|
127
|
+
with `--base/--head` is exit 2. If the brief's files disagree with the live
|
|
128
|
+
diff the command fails loud (exit 1) rather than silently under-showing.
|
|
129
|
+
|
|
130
|
+
### `delta <n>`
|
|
131
|
+
|
|
132
|
+
What changed since **your** last review. One of the CLI-synthesized
|
|
133
|
+
shapes — a discriminated union, both arms exit 0:
|
|
134
|
+
|
|
135
|
+
```json
|
|
136
|
+
{"available":true,"baselineSha":"77aa…","headSha":"4c0a…","artifact":{"summary":"…","changedGroups":[],"chunks":[]}}
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
```json
|
|
140
|
+
{"available":false,"reason":"pending"}
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
`reason` ∈ `no-checkpoint` · `pending` · `baseline-unavailable` ·
|
|
144
|
+
`delta-not-generated`. `--baseline/--head` (together) skip checkpoint
|
|
145
|
+
resolution; an artifact missing for an explicit span is exit 4.
|
|
146
|
+
|
|
147
|
+
### `session <n> --base <sha> --head <sha>`
|
|
148
|
+
|
|
149
|
+
Your review session on the brief span you name, verbatim. The span is
|
|
150
|
+
required and never auto-fetched (exit 2 without it) — the same
|
|
151
|
+
`baseSha`/`headSha` pair `pr <n>` reports.
|
|
152
|
+
|
|
153
|
+
### `marks <n> --baseline <sha> --head <sha>`
|
|
154
|
+
|
|
155
|
+
Comparison marks (coordinates only) for a `baseline..head` span, verbatim.
|
|
156
|
+
Both flags required (exit 2).
|
|
157
|
+
|
|
158
|
+
### `narrative <n> --prev-head <sha> --head <sha>`
|
|
159
|
+
|
|
160
|
+
The revision narrative for a `prevHead..head` hop, verbatim. Both flags
|
|
161
|
+
required (exit 2).
|
|
162
|
+
|
|
163
|
+
### `context <n> --base <sha> --head <sha>`
|
|
164
|
+
|
|
165
|
+
The brief's repo-config snapshot (`{"repoConfig":…}`), verbatim. Same span
|
|
166
|
+
rule as `session`.
|
|
167
|
+
|
|
168
|
+
### `draft create|update|reanchor|delete <n> [draftId]`
|
|
169
|
+
|
|
170
|
+
Draft inline comments in your session — they post at `submit`. Every draft
|
|
171
|
+
command names the brief span (`--base/--head`, exit 2 without them).
|
|
172
|
+
Payload via `-F <file>` / `-F -` (stdin), or the convenience flags —
|
|
173
|
+
mutually exclusive (exit 2):
|
|
174
|
+
|
|
175
|
+
- `create <n> --file <path> --start <line> --end <line> --body <text>`
|
|
176
|
+
(`--side old|new`, default `new`, `old` only for deleted lines).
|
|
177
|
+
`--file` without `--start`/`--end` is a File comment. Mixing `--file`
|
|
178
|
+
with only one of `--start`/`--end` is exit 2. `--file` without a span
|
|
179
|
+
cannot take `--side` or `--start-side` (exit 2). Receipt: `{"draftId":"41"}`.
|
|
180
|
+
- `update <n> <draftId> --body <text>` — edit a held draft's body.
|
|
181
|
+
- `reanchor <n> <draftId> --file --start --end [--side]` — move a held
|
|
182
|
+
draft's anchor. `--file` without a span converts it to a File comment.
|
|
183
|
+
`--file` without a span cannot take `--side` or `--start-side` (exit 2).
|
|
184
|
+
Server-gated to signed-in reviewers (a token gets the relayed 403 → exit 5).
|
|
185
|
+
- `delete <n> <draftId>` — no payload. Same signed-in-reviewer gate.
|
|
186
|
+
|
|
187
|
+
### `chunk-read <n> <chunkId>`
|
|
188
|
+
|
|
189
|
+
Mark a brief chunk read (`--unread` clears; the flags are mutually
|
|
190
|
+
exclusive). Span required. Receipt: `{"chunkId":"chunk-1","read":true}`.
|
|
191
|
+
|
|
192
|
+
### `risk dismiss|address|reopen <n> -F <file>`
|
|
193
|
+
|
|
194
|
+
Disposition the brief's risk flags. `-F` is **required** — the payload's
|
|
195
|
+
`flags` array names each flag by anchor (`filePath`, `attribute`,
|
|
196
|
+
`regionStart`, `regionEnd`), copied through from `session --json`.
|
|
197
|
+
`dismiss` adds `--reason <text>` as a convenience, mutually exclusive with
|
|
198
|
+
a `reason` in the payload (exit 2). Span required. Server-gated to
|
|
199
|
+
signed-in reviewers (a token gets the relayed 403 → exit 5).
|
|
200
|
+
|
|
201
|
+
### `reclassify <n> <groupId> --category <category>`
|
|
202
|
+
|
|
203
|
+
Override a change group's category in your session. Span required.
|
|
204
|
+
Receipt: `{"changeGroupId":"grp-1","category":"bugfix"}`.
|
|
205
|
+
|
|
206
|
+
### `outcome <n> <comment|approve|request-changes>`
|
|
207
|
+
|
|
208
|
+
Set your session's review intent — `submit` is what publishes. Span
|
|
209
|
+
required. Receipt: `{"outcome":"approve"}`.
|
|
210
|
+
|
|
211
|
+
### `thread resolve|unresolve <n> <commentId>`
|
|
212
|
+
|
|
213
|
+
Flip the review thread rooted at a comment, on GitHub, as you. No span.
|
|
214
|
+
Receipt: `{"resolved":true,"alreadyInTargetState":false}`.
|
|
215
|
+
|
|
216
|
+
### `ready <n>`
|
|
217
|
+
|
|
218
|
+
Mark a draft PR ready for review (GitHub enforces who may). No span.
|
|
219
|
+
Receipt: `{"draft":false}`.
|
|
220
|
+
|
|
221
|
+
### `generate <url>`
|
|
222
|
+
|
|
223
|
+
Generate a brief for a PR URL on demand — no confirm prompt (your own
|
|
224
|
+
key, mirroring the web URL box). Receipt: `{"briefId":"octo-hello-7_1_4c0a…"}`.
|
|
225
|
+
|
|
226
|
+
### `collaborators`
|
|
227
|
+
|
|
228
|
+
The target repo's collaborator roster, verbatim (`-R`/origin addressing).
|
|
229
|
+
Requires push access — a read-only viewer gets the 404 posture.
|
|
230
|
+
|
|
231
|
+
### `conversation <n>`
|
|
232
|
+
|
|
233
|
+
The PR's review conversation, verbatim (threads, reviews, PR comments).
|
|
234
|
+
|
|
235
|
+
### `reply <commentId> --pr <n>`
|
|
236
|
+
|
|
237
|
+
Reply in your own voice: `--body <text>` or `--body-file -` (stdin).
|
|
238
|
+
Receipt verbatim: `{"commentId":990011}`.
|
|
239
|
+
|
|
240
|
+
### `submit <n>`
|
|
241
|
+
|
|
242
|
+
Submit a review of the brief span you name; the comments are the drafts
|
|
243
|
+
the server holds for it (drafting them has no CLI command yet, so a
|
|
244
|
+
CLI-only submit posts a body-only review today). Payload via `-F <file>` /
|
|
245
|
+
`-F -` (stdin), or the
|
|
246
|
+
convenience flags (`--outcome comment|approve|request-changes`, `--body`)
|
|
247
|
+
— the two forms are mutually exclusive. **`--base` and `--head` are
|
|
248
|
+
required and never auto-fetched** (exit 2 without them): carry the span
|
|
249
|
+
through from `pr <n>`. Receipt verbatim:
|
|
250
|
+
|
|
251
|
+
```json
|
|
252
|
+
{"reviewId":990012,"commentsDegraded":false,"commentsFolded":0,"commentsTotal":2}
|
|
253
|
+
```
|
|
254
|
+
|
|
255
|
+
`commentsFolded` counts the comments GitHub refused to anchor out of
|
|
256
|
+
`commentsTotal`; those were folded into the review body, the rest landed
|
|
257
|
+
as threads — the review **did** post (a stderr warning fires in both
|
|
258
|
+
output modes when the count is above zero; do not re-submit).
|
|
259
|
+
`commentsDegraded` mirrors `commentsFolded > 0` for one release. GitHub
|
|
260
|
+
rejects `approve`/`request-changes` on your own PR (`comment` passes) —
|
|
261
|
+
that relays as a server error; don't retry-loop it.
|
|
262
|
+
|
|
263
|
+
### `capabilities`
|
|
264
|
+
|
|
265
|
+
The server's operation catalog joined with this binary's committed command
|
|
266
|
+
map — the third CLI-synthesized shape. Each server operation gains a `cli`
|
|
267
|
+
arm: `{command}` (runnable here), `{gap}` (no command yet), `{webOnly}`
|
|
268
|
+
(browser-only by design), or `{unknownToCli: true}` (the server is newer).
|
|
269
|
+
The shape also carries `cliVersion`, both catalog fingerprints, and
|
|
270
|
+
`fingerprintMatch`; a mismatch alone is one stderr warning, never a gate.
|
|
271
|
+
|
|
272
|
+
`--require <ids...>` turns the report into a fail-closed preflight: every
|
|
273
|
+
named operation must be registered on the server AND mapped to a command in
|
|
274
|
+
this binary, or the command exits 6 with one stderr line naming each
|
|
275
|
+
failure. Agents run this before driving a workflow.
|
|
276
|
+
|
|
277
|
+
### `auth login` / `auth status`
|
|
278
|
+
|
|
279
|
+
`auth login` reads the token from stdin (paste prompt on a TTY), stores it
|
|
280
|
+
per profile, and verifies it immediately — its output is the `auth status`
|
|
281
|
+
shape. `auth status` is three-level: config (profile, base URL, token
|
|
282
|
+
present), the CLI's own version, and server (reachable, authenticated,
|
|
283
|
+
**server version** — the API changelog is keyed to it — plus the newest
|
|
284
|
+
release the server knows of, when its update check has an answer). Dead
|
|
285
|
+
token and unreachable server are data (exit 0), so scripts can diagnose
|
|
286
|
+
without special-casing failures.
|
|
287
|
+
|
|
288
|
+
## Profiles
|
|
289
|
+
|
|
290
|
+
`~/.config/mergebrief/config.json` (0600) holds named profiles — base URL,
|
|
291
|
+
token, optional `owners: ["acme"]` mapping and extra static `headers` (the
|
|
292
|
+
IdP escape hatch). Resolution order: `--profile` / `MERGEBRIEF_PROFILE` →
|
|
293
|
+
`owners:` match on the git-remote owner → the default profile.
|
|
294
|
+
`MERGEBRIEF_TOKEN` overrides the resolved profile's stored token.
|
|
295
|
+
|
|
296
|
+
Deploy-side setup (IdP `/api/*` exemption, minting walkthrough):
|
|
297
|
+
[`docs/self-host/cli.md`](../../docs/self-host/cli.md).
|
|
298
|
+
|
|
299
|
+
## Flag appendix (generated)
|
|
300
|
+
|
|
301
|
+
Regenerate with `pnpm --dir apps/cli docs:appendix`; CI fails on
|
|
302
|
+
staleness.
|
|
303
|
+
|
|
304
|
+
<!-- BEGIN GENERATED FLAG APPENDIX (pnpm docs:appendix) -->
|
|
305
|
+
|
|
306
|
+
### `mergebrief`
|
|
307
|
+
|
|
308
|
+
```
|
|
309
|
+
Usage: mergebrief [options] [command]
|
|
310
|
+
|
|
311
|
+
MergeBrief — PR briefs for humans and agents, over your deployment's API
|
|
312
|
+
|
|
313
|
+
Options:
|
|
314
|
+
-V, --version output the version number
|
|
315
|
+
--json machine output: the documented JSON contract (default: false)
|
|
316
|
+
--agents deprecated: prints where the agent guide moved (default: false)
|
|
317
|
+
--profile <name> config profile (default: owners match, then the default profile)
|
|
318
|
+
-R, --repo <owner/name> target repository (default: the origin remote)
|
|
319
|
+
-h, --help display help for command
|
|
320
|
+
|
|
321
|
+
Commands:
|
|
322
|
+
auth authentication against your deployment
|
|
323
|
+
repos [options] repositories visible to the profile's token (cached; see --refresh)
|
|
324
|
+
pr [number] your PRs (no argument), or one PR's metadata
|
|
325
|
+
groups <number> the PR's brief — change groups over the current span
|
|
326
|
+
conversation <number> the PR's review conversation
|
|
327
|
+
diff [options] <number> the PR's unified diff (its raw text IS the machine format)
|
|
328
|
+
reply [options] <commentId> reply to a review comment (the viewer's own voice)
|
|
329
|
+
submit [options] <number> submit a review of the brief span you name (its saved drafts go with it)
|
|
330
|
+
session [options] <number> your review session on the brief span you name
|
|
331
|
+
marks [options] <number> comparison marks (coordinates only) for a baseline..head span
|
|
332
|
+
narrative [options] <number> the revision narrative for a prevHead..head hop
|
|
333
|
+
context [options] <number> the brief's repo-config snapshot for the span you name
|
|
334
|
+
draft draft review comments in your session (posted at submit)
|
|
335
|
+
chunk-read [options] <number> <chunkId> mark a brief chunk read (--unread clears the mark)
|
|
336
|
+
risk disposition the brief's risk flags in your session
|
|
337
|
+
reclassify [options] <number> <groupId> override a change group's category in your session
|
|
338
|
+
outcome [options] <number> <outcome> set your session's review intent (publishing is `submit`)
|
|
339
|
+
thread review-thread state on GitHub (the viewer's own act)
|
|
340
|
+
ready <number> mark a draft PR ready for review (GitHub-enforced authorship)
|
|
341
|
+
generate <url> generate a brief for a PR URL (no confirm; your own key)
|
|
342
|
+
collaborators the target repo's collaborator roster (push access required)
|
|
343
|
+
capabilities [options] what this server+CLI pair can run; --require makes it a fail-closed check
|
|
344
|
+
delta [options] <number> what changed since your last review (union: available | not)
|
|
345
|
+
help [command] display help for command
|
|
346
|
+
```
|
|
347
|
+
|
|
348
|
+
### `mergebrief auth login`
|
|
349
|
+
|
|
350
|
+
```
|
|
351
|
+
Usage: mergebrief auth login [options]
|
|
352
|
+
|
|
353
|
+
store a token for a profile (paste it, or pipe it on stdin)
|
|
354
|
+
|
|
355
|
+
Options:
|
|
356
|
+
--base-url <url> deployment origin, e.g. https://mergebrief.example.com
|
|
357
|
+
-h, --help display help for command
|
|
358
|
+
```
|
|
359
|
+
|
|
360
|
+
### `mergebrief auth status`
|
|
361
|
+
|
|
362
|
+
```
|
|
363
|
+
Usage: mergebrief auth status [options]
|
|
364
|
+
|
|
365
|
+
config + server status for the resolved profile
|
|
366
|
+
|
|
367
|
+
Options:
|
|
368
|
+
-h, --help display help for command
|
|
369
|
+
```
|
|
370
|
+
|
|
371
|
+
### `mergebrief repos`
|
|
372
|
+
|
|
373
|
+
```
|
|
374
|
+
Usage: mergebrief repos [options]
|
|
375
|
+
|
|
376
|
+
repositories visible to the profile's token (cached; see --refresh)
|
|
377
|
+
|
|
378
|
+
Options:
|
|
379
|
+
--refresh bypass the disk cache (default: false)
|
|
380
|
+
-h, --help display help for command
|
|
381
|
+
```
|
|
382
|
+
|
|
383
|
+
### `mergebrief pr`
|
|
384
|
+
|
|
385
|
+
```
|
|
386
|
+
Usage: mergebrief pr [options] [number]
|
|
387
|
+
|
|
388
|
+
your PRs (no argument), or one PR's metadata
|
|
389
|
+
|
|
390
|
+
Arguments:
|
|
391
|
+
number PR number in the target repository
|
|
392
|
+
|
|
393
|
+
Options:
|
|
394
|
+
-h, --help display help for command
|
|
395
|
+
```
|
|
396
|
+
|
|
397
|
+
### `mergebrief groups`
|
|
398
|
+
|
|
399
|
+
```
|
|
400
|
+
Usage: mergebrief groups [options] <number>
|
|
401
|
+
|
|
402
|
+
the PR's brief — change groups over the current span
|
|
403
|
+
|
|
404
|
+
Arguments:
|
|
405
|
+
number PR number
|
|
406
|
+
|
|
407
|
+
Options:
|
|
408
|
+
-h, --help display help for command
|
|
409
|
+
```
|
|
410
|
+
|
|
411
|
+
### `mergebrief conversation`
|
|
412
|
+
|
|
413
|
+
```
|
|
414
|
+
Usage: mergebrief conversation [options] <number>
|
|
415
|
+
|
|
416
|
+
the PR's review conversation
|
|
417
|
+
|
|
418
|
+
Arguments:
|
|
419
|
+
number PR number
|
|
420
|
+
|
|
421
|
+
Options:
|
|
422
|
+
-h, --help display help for command
|
|
423
|
+
```
|
|
424
|
+
|
|
425
|
+
### `mergebrief diff`
|
|
426
|
+
|
|
427
|
+
```
|
|
428
|
+
Usage: mergebrief diff [options] <number>
|
|
429
|
+
|
|
430
|
+
the PR's unified diff (its raw text IS the machine format)
|
|
431
|
+
|
|
432
|
+
Arguments:
|
|
433
|
+
number PR number
|
|
434
|
+
|
|
435
|
+
Options:
|
|
436
|
+
--base <sha> span base (with --head)
|
|
437
|
+
--head <sha> span head (with --base)
|
|
438
|
+
--group <id> filter to one change group's whole hunks (brief span only)
|
|
439
|
+
-h, --help display help for command
|
|
440
|
+
```
|
|
441
|
+
|
|
442
|
+
### `mergebrief delta`
|
|
443
|
+
|
|
444
|
+
```
|
|
445
|
+
Usage: mergebrief delta [options] <number>
|
|
446
|
+
|
|
447
|
+
what changed since your last review (union: available | not)
|
|
448
|
+
|
|
449
|
+
Arguments:
|
|
450
|
+
number PR number
|
|
451
|
+
|
|
452
|
+
Options:
|
|
453
|
+
--baseline <sha> override the checkpoint baseline (with --head)
|
|
454
|
+
--head <sha> override the head (with --baseline)
|
|
455
|
+
-h, --help display help for command
|
|
456
|
+
```
|
|
457
|
+
|
|
458
|
+
### `mergebrief session`
|
|
459
|
+
|
|
460
|
+
```
|
|
461
|
+
Usage: mergebrief session [options] <number>
|
|
462
|
+
|
|
463
|
+
your review session on the brief span you name
|
|
464
|
+
|
|
465
|
+
Arguments:
|
|
466
|
+
number PR number
|
|
467
|
+
|
|
468
|
+
Options:
|
|
469
|
+
--base <sha> span base of the brief (required)
|
|
470
|
+
--head <sha> span head of the brief (required)
|
|
471
|
+
-h, --help display help for command
|
|
472
|
+
```
|
|
473
|
+
|
|
474
|
+
### `mergebrief marks`
|
|
475
|
+
|
|
476
|
+
```
|
|
477
|
+
Usage: mergebrief marks [options] <number>
|
|
478
|
+
|
|
479
|
+
comparison marks (coordinates only) for a baseline..head span
|
|
480
|
+
|
|
481
|
+
Arguments:
|
|
482
|
+
number PR number
|
|
483
|
+
|
|
484
|
+
Options:
|
|
485
|
+
--baseline <sha> comparison baseline (required)
|
|
486
|
+
--head <sha> comparison head (required)
|
|
487
|
+
-h, --help display help for command
|
|
488
|
+
```
|
|
489
|
+
|
|
490
|
+
### `mergebrief narrative`
|
|
491
|
+
|
|
492
|
+
```
|
|
493
|
+
Usage: mergebrief narrative [options] <number>
|
|
494
|
+
|
|
495
|
+
the revision narrative for a prevHead..head hop
|
|
496
|
+
|
|
497
|
+
Arguments:
|
|
498
|
+
number PR number
|
|
499
|
+
|
|
500
|
+
Options:
|
|
501
|
+
--prev-head <sha> prior briefed head (required)
|
|
502
|
+
--head <sha> revision head (required)
|
|
503
|
+
-h, --help display help for command
|
|
504
|
+
```
|
|
505
|
+
|
|
506
|
+
### `mergebrief context`
|
|
507
|
+
|
|
508
|
+
```
|
|
509
|
+
Usage: mergebrief context [options] <number>
|
|
510
|
+
|
|
511
|
+
the brief's repo-config snapshot for the span you name
|
|
512
|
+
|
|
513
|
+
Arguments:
|
|
514
|
+
number PR number
|
|
515
|
+
|
|
516
|
+
Options:
|
|
517
|
+
--base <sha> span base of the brief (required)
|
|
518
|
+
--head <sha> span head of the brief (required)
|
|
519
|
+
-h, --help display help for command
|
|
520
|
+
```
|
|
521
|
+
|
|
522
|
+
### `mergebrief draft create`
|
|
523
|
+
|
|
524
|
+
```
|
|
525
|
+
Usage: mergebrief draft create [options] <number>
|
|
526
|
+
|
|
527
|
+
draft a new inline comment on the brief span you name
|
|
528
|
+
|
|
529
|
+
Arguments:
|
|
530
|
+
number PR number
|
|
531
|
+
|
|
532
|
+
Options:
|
|
533
|
+
-F, --payload <path> full JSON payload from a file, or "-" for stdin
|
|
534
|
+
--file <path> anchor file path (flag form)
|
|
535
|
+
--side <side> old | new (flag form; default: new)
|
|
536
|
+
--start-side <side> old | new — side of --start when the range crosses sides
|
|
537
|
+
(flag form)
|
|
538
|
+
--start <line> anchor start line (flag form)
|
|
539
|
+
--end <line> anchor end line (flag form)
|
|
540
|
+
--body <text> comment body (flag form)
|
|
541
|
+
--base <sha> span base of the brief (required)
|
|
542
|
+
--head <sha> span head of the brief (required)
|
|
543
|
+
-h, --help display help for command
|
|
544
|
+
```
|
|
545
|
+
|
|
546
|
+
### `mergebrief draft update`
|
|
547
|
+
|
|
548
|
+
```
|
|
549
|
+
Usage: mergebrief draft update [options] <number> <draftId>
|
|
550
|
+
|
|
551
|
+
edit a held draft's body
|
|
552
|
+
|
|
553
|
+
Arguments:
|
|
554
|
+
number PR number
|
|
555
|
+
draftId the draft id (see `session <n>`)
|
|
556
|
+
|
|
557
|
+
Options:
|
|
558
|
+
-F, --payload <path> full JSON payload from a file, or "-" for stdin
|
|
559
|
+
--body <text> new comment body (flag form)
|
|
560
|
+
--base <sha> span base of the brief (required)
|
|
561
|
+
--head <sha> span head of the brief (required)
|
|
562
|
+
-h, --help display help for command
|
|
563
|
+
```
|
|
564
|
+
|
|
565
|
+
### `mergebrief draft reanchor`
|
|
566
|
+
|
|
567
|
+
```
|
|
568
|
+
Usage: mergebrief draft reanchor [options] <number> <draftId>
|
|
569
|
+
|
|
570
|
+
move a held draft's anchor (settles a carried orphan)
|
|
571
|
+
|
|
572
|
+
Arguments:
|
|
573
|
+
number PR number
|
|
574
|
+
draftId the draft id (see `session <n>`)
|
|
575
|
+
|
|
576
|
+
Options:
|
|
577
|
+
-F, --payload <path> full JSON payload from a file, or "-" for stdin
|
|
578
|
+
--file <path> anchor file path (flag form)
|
|
579
|
+
--side <side> old | new (flag form; default: new)
|
|
580
|
+
--start-side <side> old | new — side of --start when the range crosses sides
|
|
581
|
+
(flag form)
|
|
582
|
+
--start <line> anchor start line (flag form)
|
|
583
|
+
--end <line> anchor end line (flag form)
|
|
584
|
+
--base <sha> span base of the brief (required)
|
|
585
|
+
--head <sha> span head of the brief (required)
|
|
586
|
+
-h, --help display help for command
|
|
587
|
+
```
|
|
588
|
+
|
|
589
|
+
### `mergebrief draft delete`
|
|
590
|
+
|
|
591
|
+
```
|
|
592
|
+
Usage: mergebrief draft delete [options] <number> <draftId>
|
|
593
|
+
|
|
594
|
+
delete a held draft
|
|
595
|
+
|
|
596
|
+
Arguments:
|
|
597
|
+
number PR number
|
|
598
|
+
draftId the draft id (see `session <n>`)
|
|
599
|
+
|
|
600
|
+
Options:
|
|
601
|
+
--base <sha> span base of the brief (required)
|
|
602
|
+
--head <sha> span head of the brief (required)
|
|
603
|
+
-h, --help display help for command
|
|
604
|
+
```
|
|
605
|
+
|
|
606
|
+
### `mergebrief draft attach`
|
|
607
|
+
|
|
608
|
+
```
|
|
609
|
+
Usage: mergebrief draft attach [options] <number> <file>
|
|
610
|
+
|
|
611
|
+
upload an image to the repository's attachments branch; prints {url}
|
|
612
|
+
|
|
613
|
+
Arguments:
|
|
614
|
+
number PR number
|
|
615
|
+
file a png, jpg, gif or webp file
|
|
616
|
+
|
|
617
|
+
Options:
|
|
618
|
+
--draft <draftId> also append the image to this held draft (needs --base and
|
|
619
|
+
--head)
|
|
620
|
+
--base <sha> span base of the brief (with --draft)
|
|
621
|
+
--head <sha> span head of the brief (with --draft)
|
|
622
|
+
-h, --help display help for command
|
|
623
|
+
```
|
|
624
|
+
|
|
625
|
+
### `mergebrief chunk-read`
|
|
626
|
+
|
|
627
|
+
```
|
|
628
|
+
Usage: mergebrief chunk-read [options] <number> <chunkId>
|
|
629
|
+
|
|
630
|
+
mark a brief chunk read (--unread clears the mark)
|
|
631
|
+
|
|
632
|
+
Arguments:
|
|
633
|
+
number PR number
|
|
634
|
+
chunkId the chunk id as the brief spells it
|
|
635
|
+
|
|
636
|
+
Options:
|
|
637
|
+
--read mark read (the default)
|
|
638
|
+
--unread clear the read mark
|
|
639
|
+
--base <sha> span base of the brief (required)
|
|
640
|
+
--head <sha> span head of the brief (required)
|
|
641
|
+
-h, --help display help for command
|
|
642
|
+
```
|
|
643
|
+
|
|
644
|
+
### `mergebrief risk dismiss`
|
|
645
|
+
|
|
646
|
+
```
|
|
647
|
+
Usage: mergebrief risk dismiss [options] <number>
|
|
648
|
+
|
|
649
|
+
dismiss risk flags (the payload's flags array names them)
|
|
650
|
+
|
|
651
|
+
Arguments:
|
|
652
|
+
number PR number
|
|
653
|
+
|
|
654
|
+
Options:
|
|
655
|
+
-F, --payload <path> JSON payload from a file, or "-" for stdin (required)
|
|
656
|
+
--reason <text> dismissal reason (unless the payload carries one)
|
|
657
|
+
--base <sha> span base of the brief (required)
|
|
658
|
+
--head <sha> span head of the brief (required)
|
|
659
|
+
-h, --help display help for command
|
|
660
|
+
```
|
|
661
|
+
|
|
662
|
+
### `mergebrief risk address`
|
|
663
|
+
|
|
664
|
+
```
|
|
665
|
+
Usage: mergebrief risk address [options] <number>
|
|
666
|
+
|
|
667
|
+
mark risk flags addressed (each flag carries its evidence)
|
|
668
|
+
|
|
669
|
+
Arguments:
|
|
670
|
+
number PR number
|
|
671
|
+
|
|
672
|
+
Options:
|
|
673
|
+
-F, --payload <path> JSON payload from a file, or "-" for stdin (required)
|
|
674
|
+
--base <sha> span base of the brief (required)
|
|
675
|
+
--head <sha> span head of the brief (required)
|
|
676
|
+
-h, --help display help for command
|
|
677
|
+
```
|
|
678
|
+
|
|
679
|
+
### `mergebrief risk reopen`
|
|
680
|
+
|
|
681
|
+
```
|
|
682
|
+
Usage: mergebrief risk reopen [options] <number>
|
|
683
|
+
|
|
684
|
+
undo dispositions on risk flags
|
|
685
|
+
|
|
686
|
+
Arguments:
|
|
687
|
+
number PR number
|
|
688
|
+
|
|
689
|
+
Options:
|
|
690
|
+
-F, --payload <path> JSON payload from a file, or "-" for stdin (required)
|
|
691
|
+
--base <sha> span base of the brief (required)
|
|
692
|
+
--head <sha> span head of the brief (required)
|
|
693
|
+
-h, --help display help for command
|
|
694
|
+
```
|
|
695
|
+
|
|
696
|
+
### `mergebrief reclassify`
|
|
697
|
+
|
|
698
|
+
```
|
|
699
|
+
Usage: mergebrief reclassify [options] <number> <groupId>
|
|
700
|
+
|
|
701
|
+
override a change group's category in your session
|
|
702
|
+
|
|
703
|
+
Arguments:
|
|
704
|
+
number PR number
|
|
705
|
+
groupId the change group id (see `groups <n>`)
|
|
706
|
+
|
|
707
|
+
Options:
|
|
708
|
+
--category <category> the category to record
|
|
709
|
+
--base <sha> span base of the brief (required)
|
|
710
|
+
--head <sha> span head of the brief (required)
|
|
711
|
+
-h, --help display help for command
|
|
712
|
+
```
|
|
713
|
+
|
|
714
|
+
### `mergebrief outcome`
|
|
715
|
+
|
|
716
|
+
```
|
|
717
|
+
Usage: mergebrief outcome [options] <number> <outcome>
|
|
718
|
+
|
|
719
|
+
set your session's review intent (publishing is `submit`)
|
|
720
|
+
|
|
721
|
+
Arguments:
|
|
722
|
+
number PR number
|
|
723
|
+
outcome comment | approve | request-changes
|
|
724
|
+
|
|
725
|
+
Options:
|
|
726
|
+
--base <sha> span base of the brief (required)
|
|
727
|
+
--head <sha> span head of the brief (required)
|
|
728
|
+
-h, --help display help for command
|
|
729
|
+
```
|
|
730
|
+
|
|
731
|
+
### `mergebrief thread resolve`
|
|
732
|
+
|
|
733
|
+
```
|
|
734
|
+
Usage: mergebrief thread resolve [options] <number> <commentId>
|
|
735
|
+
|
|
736
|
+
resolve the thread rooted at a review comment
|
|
737
|
+
|
|
738
|
+
Arguments:
|
|
739
|
+
number PR number
|
|
740
|
+
commentId the thread's root review comment id
|
|
741
|
+
|
|
742
|
+
Options:
|
|
743
|
+
-h, --help display help for command
|
|
744
|
+
```
|
|
745
|
+
|
|
746
|
+
### `mergebrief thread unresolve`
|
|
747
|
+
|
|
748
|
+
```
|
|
749
|
+
Usage: mergebrief thread unresolve [options] <number> <commentId>
|
|
750
|
+
|
|
751
|
+
reopen the thread rooted at a review comment
|
|
752
|
+
|
|
753
|
+
Arguments:
|
|
754
|
+
number PR number
|
|
755
|
+
commentId the thread's root review comment id
|
|
756
|
+
|
|
757
|
+
Options:
|
|
758
|
+
-h, --help display help for command
|
|
759
|
+
```
|
|
760
|
+
|
|
761
|
+
### `mergebrief ready`
|
|
762
|
+
|
|
763
|
+
```
|
|
764
|
+
Usage: mergebrief ready [options] <number>
|
|
765
|
+
|
|
766
|
+
mark a draft PR ready for review (GitHub-enforced authorship)
|
|
767
|
+
|
|
768
|
+
Arguments:
|
|
769
|
+
number PR number
|
|
770
|
+
|
|
771
|
+
Options:
|
|
772
|
+
-h, --help display help for command
|
|
773
|
+
```
|
|
774
|
+
|
|
775
|
+
### `mergebrief generate`
|
|
776
|
+
|
|
777
|
+
```
|
|
778
|
+
Usage: mergebrief generate [options] <url>
|
|
779
|
+
|
|
780
|
+
generate a brief for a PR URL (no confirm; your own key)
|
|
781
|
+
|
|
782
|
+
Arguments:
|
|
783
|
+
url the PR's GitHub URL
|
|
784
|
+
|
|
785
|
+
Options:
|
|
786
|
+
-h, --help display help for command
|
|
787
|
+
```
|
|
788
|
+
|
|
789
|
+
### `mergebrief collaborators`
|
|
790
|
+
|
|
791
|
+
```
|
|
792
|
+
Usage: mergebrief collaborators [options]
|
|
793
|
+
|
|
794
|
+
the target repo's collaborator roster (push access required)
|
|
795
|
+
|
|
796
|
+
Options:
|
|
797
|
+
-h, --help display help for command
|
|
798
|
+
```
|
|
799
|
+
|
|
800
|
+
### `mergebrief capabilities`
|
|
801
|
+
|
|
802
|
+
```
|
|
803
|
+
Usage: mergebrief capabilities [options]
|
|
804
|
+
|
|
805
|
+
what this server+CLI pair can run; --require makes it a fail-closed check
|
|
806
|
+
|
|
807
|
+
Options:
|
|
808
|
+
--require <ids...> operation ids that must be runnable here (any failure →
|
|
809
|
+
exit 6)
|
|
810
|
+
-h, --help display help for command
|
|
811
|
+
```
|
|
812
|
+
|
|
813
|
+
### `mergebrief reply`
|
|
814
|
+
|
|
815
|
+
```
|
|
816
|
+
Usage: mergebrief reply [options] <commentId>
|
|
817
|
+
|
|
818
|
+
reply to a review comment (the viewer's own voice)
|
|
819
|
+
|
|
820
|
+
Arguments:
|
|
821
|
+
commentId the review comment id (see `conversation <n>`)
|
|
822
|
+
|
|
823
|
+
Options:
|
|
824
|
+
--pr <number> the PR the comment belongs to
|
|
825
|
+
--body <text> reply text
|
|
826
|
+
--body-file <path> reply text from a file, or "-" for stdin
|
|
827
|
+
-h, --help display help for command
|
|
828
|
+
```
|
|
829
|
+
|
|
830
|
+
### `mergebrief submit`
|
|
831
|
+
|
|
832
|
+
```
|
|
833
|
+
Usage: mergebrief submit [options] <number>
|
|
834
|
+
|
|
835
|
+
submit a review of the brief span you name (its saved drafts go with it)
|
|
836
|
+
|
|
837
|
+
Arguments:
|
|
838
|
+
number PR number
|
|
839
|
+
|
|
840
|
+
Options:
|
|
841
|
+
-F, --file <path> full JSON payload from a file, or "-" for stdin
|
|
842
|
+
--outcome <outcome> comment | approve | request-changes (flag form)
|
|
843
|
+
--body <text> review body (flag form)
|
|
844
|
+
--base <sha> span base of the brief you reviewed
|
|
845
|
+
--head <sha> span head of the brief you reviewed
|
|
846
|
+
-h, --help display help for command
|
|
847
|
+
```
|
|
848
|
+
|
|
849
|
+
<!-- END GENERATED FLAG APPENDIX -->
|