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.
Files changed (3) hide show
  1. package/README.md +848 -2
  2. package/dist/mergebrief.js +24858 -0
  3. package/package.json +40 -4
package/README.md CHANGED
@@ -1,3 +1,849 @@
1
- # Temporary Holding Version
1
+ # mergebrief
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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 -->