Skip to content

Self-host: the mergebrief CLI ​

How to get the CLI (and the agents it drives) talking to your deployment. Assumes the compose stack (compose.md) and the GitHub App (github-app.md) are already up.

Install ​

The CLI needs Node 24, or 26 and later:

sh
npm i -g mergebrief
mergebrief --version

To run it without installing, use npx mergebrief in place of mergebrief. Agents and CI usually do. npx or a global install covers how the two differ on versions.

Don't run npx inside a checkout of code you don't trust, such as a pull request's head in CI. It prefers a mergebrief bin from the local project and reads the project's .npmrc, so that code can choose what runs. Install the CLI first, or run npx from another directory and name the repository with -R and the instance with --profile.

If the shell answers command not found: mergebrief, npm's global bin directory is not on PATH. On macOS or Linux, add this line to your shell's startup file and open a new shell:

sh
export PATH="$(npm prefix -g)/bin:$PATH"

If you installed with pnpm add -g mergebrief, run pnpm setup and open a new shell instead. Add --force if it reports that your shell's startup file already has a pnpm section, which an older pnpm leaves.

What the CLI needs from your deployment ​

The CLI is a thin client over the public HTTP API (/api/*) with an opaque Bearer token. Three things must be true:

  1. The API is reachable at the base URL you give auth login, the same origin the web app serves.
  2. /api/* accepts Authorization: Bearer mergebrief_... end to end. The server side already does; the catch is usually in front of it (next section).
  3. A token exists, created in the web app, per user, with the scope you chose for it.

IdP / SSO proxies: exempt /api/* ​

If your company has an identity provider such as Okta, we recommend putting the instance behind an identity-aware proxy (Cloudflare Access, oauth2-proxy, Authelia, Pomerium, …). Your provider's docs cover the setup. These are the paths to give it, with the /api/auth/* rule matched first:

PathAt the proxyUsed by
/api/auth/*Behind the IdPThe browser: sign-in and its GitHub callback, session, sign-out, API tokens
/api/webhooks/githubOpen, with a rate limitGitHub. Its signature is the only gate
Every other /api/*OpenThe CLI and agents. The API checks a session or token on each request
Everything elseBehind the IdPThe browser: pages and assets
  • CLI: it never calls /api/auth/*. If its requests do reach the IdP, they get a login redirect or an HTML page, and the CLI reports an "identity-provider proxy" error.
  • Health checks: the compose checks skip the proxy. Open /healthz and /readyz only for a monitor outside it.
  • An open tab: it calls /api/auth/* too, so it needs a reload once the IdP session expires.
  • Compression: leave it off at the proxy for pages and /api answers. The app compresses its own answers and sends some plain on purpose, and a proxy that compresses would compress exactly those (compose.md).
  • Access rules: the proxy adds to operators and allowed and replaces neither.
  • Leavers: disabling someone in the IdP leaves their API tokens working, because those skip the proxy. Also remove them from the instance config or from the GitHub account that lets them in, and they lose access at their next token rotation.

If your proxy can inject static headers and you keep it in the path anyway, per-profile headers in the CLI config are the escape hatch:

json
{
  "profiles": {
    "work": {
      "baseUrl": "https://mergebrief.internal.example",
      "token": "mergebrief_…",
      "headers": { "CF-Access-Client-Id": "…", "CF-Access-Client-Secret": "…" }
    }
  }
}

Creating a token (operator walkthrough) ​

  1. Sign in to the web app with GitHub, open /settings.

  2. Name the token (e.g. ci-reviewer), pick its scope, and choose an expiry (90 days default; "no expiry" is allowed; for self-host CI that trade-off is yours; the wrapped GitHub credential still dies after ~6 months idle either way). A token binds no organization or installation: it acts as you, on your GitHub sign-in, so it reaches the repositories you reach in the web app.

    The scope is required and fixed for the token's life; a narrower or wider one is a new token. Each level includes the one before it:

    ScopeIn the formAllows
    readRead onlyevery read command
    private-writeRead and review in MergeBriefreview state kept in MergeBrief: draft create and update, chunk-read, reclassify, outcome, generate
    external-writeRead, review, and post to GitHubanything that writes to GitHub: submit, reply, thread resolve and thread unresolve, ready, draft attach

    A command above its token's scope answers 403 scope-exceeded. Pick the least a token needs. No scope reaches draft reanchor, draft delete or risk dismiss|address|reopen: they need the signed-in browser session and answer 403 human-only to any token.

  3. Copy the token: it is shown once. Revoke and create another freely from the same page; last_used_at in the list tells you which tokens are live.

  4. On the machine that runs the CLI:

    sh
    echo "mergebrief_…" | mergebrief auth login --base-url https://mergebrief.your-org.example

mergebrief auth status --json is the end-to-end probe: it reports reachability, whether the token authenticates, and the server version in one shape (Versions lists the version fields).

Profiles (multiple deployments) ​

One profile per deployment. A token is not tied to an organization, so one profile covers every organization you reach on that deployment:

sh
echo "$WORK_TOKEN" | mergebrief auth login --base-url https://mb.work.example --profile work
echo "$OSS_TOKEN"  | mergebrief auth login --base-url https://mb.oss.example  --profile oss

Resolution order per invocation: --profile / MERGEBRIEF_PROFILE → an owners: match on the current repo's origin owner → the default profile (the first one you logged into, until you change it). MERGEBRIEF_TOKEN overrides the resolved profile's stored token, handy in CI where the token lives in a secret store, not on disk. A clone's origin must not choose where that token goes, so when its owner routes away from the default profile a command that sends a request refuses until --profile or MERGEBRIEF_PROFILE names the instance.

sh
mergebrief auth profiles                   # names, base URLs, owners, the default
mergebrief auth use work                   # make work the default
mergebrief --profile work auth owners acme # route acme/* clones to work

auth profiles never prints a token or a header value. When an instance can't be reached, the error line names your other profiles, and auth status prints them beside a failed probe.

Versions ​

mergebrief --version prints the CLI's version. A CLI built from source reports 0.0.0, and a server built from source reports dev. Either one is a dev build: it never checks for a newer version, never compares, and never warns. mergebrief@next is the most recent release candidate, not for production; a dist-tag never moves on its own, so next can be older than latest once the release it previewed is out. A candidate is not a release to the version check: a CLI or an instance running one gets no update line, no version warning and no version notice until it runs a stable version again.

What the CLI prints when versions differ ​

Three kinds of line, all on stderr, in human and --json mode alike. None changes the exit code, and none refuses a command.

CaseOn a successful runOn a failed run
A newer mergebrief exists on npm, any sizethe update line, once per answernothing extra
CLI and server differ by a major, either directiona warning on every runthe error line gains [server 1.4.0, cli 2.0.0, major gap]
CLI and server differ by minor or patchnothingthe error line gains [server 1.4.0, cli 1.6.0]
Either side is a dev buildnothingno suffix

The lines, for a server on 1.4.0:

text
A new version of mergebrief is available: 1.2.0 → 1.6.0. To update, run: npm i -g mergebrief@1.6.0
mergebrief 1.2.0 is behind this server (2.0.0): some commands may fail. To update, run: npm i -g mergebrief@2.0.0
This server (1.4.0) is behind mergebrief 2.0.0: some commands may not exist there. To match it, run: npx mergebrief@1.4.0
request failed (HTTP 404) [server 1.4.0, cli 1.6.0]

The first is the update line; the second and third are the major warning for a CLI behind the server and ahead of it; the last is a failed run's one error line with its suffix. Every version prints as plain major.minor.patch.

The update line and the CLI-behind warning suggest npx mergebrief@x.y.z when the CLI runs under npx (npm sets npm_command=exec), and npm i -g mergebrief@x.y.z otherwise. The server-behind warning always suggests npx mergebrief@<server version>, which runs a matching CLI without touching a global install. Run any suggested npx command from outside a checkout you don't trust, for the reason Install gives.

How the CLI knows ​

  • The server's version comes from the MergeBrief-Version header on the first response of the run, so the comparison costs no extra request. The API sets the header on every signed-in /api/* response, and never on a 401, on /healthz or on /readyz: an unauthenticated caller learns nothing the signed-in GET /api/version would not tell it.
  • A newer CLI comes from npm. The CLI asks https://registry.npmjs.org/mergebrief/latest beside the command it is running, and keeps the answer only if it arrived by the time the command finished, within 2 seconds; otherwise the request is dropped, so a slow registry never delays a command. The answer lands in update-check.json under $XDG_CACHE_HOME/mergebrief/ (or ~/.cache/mergebrief/), and the update line prints once, on a later run, never during the check. The CLI asks only when the cached answer is missing or more than a day old, and only an answer that arrived in time is written, so a dropped or failed check leaves the cache as it was and the next run asks again. The line prints after the next successful command, once per answer; a failed run keeps its one error line and leaves the update line for the run after. The request carries nothing about your instance, and a failed check is silent. A network that reaches your server but blocks registry.npmjs.org never sees the update line, and sees the dropped request on every run; MERGEBRIEF_NO_VERSION_WARNING stops it.

Turning the warnings off ​

MERGEBRIEF_NO_VERSION_WARNING, set to any value, silences the update line and the major warning, and the CLI then never asks npm. The failure suffix stays: it is part of the error message. Nothing is gated on CI or a TTY. An agent in CI hitting a major gap is the reader who most needs the warning, and the update line stays quiet there anyway, because a fresh container never has a cached check to print.

The instance's own updateCheck.enabled: false (operations.md) does not silence the CLI: the update line is the CLI asking npm from your machine, and MERGEBRIEF_NO_VERSION_WARNING is its opt-out.

auth status ​

mergebrief auth status prints the server's version, the CLI's version and the newest release the server knows of on its second line:

text
profile default → https://mb.example
token: configured · authenticated · server 1.4.0 · cli 1.2.0 · latest 1.6.0

It is the one place a CLI user sees that the server itself is behind. --json carries the version fields beside profile, baseUrl, tokenConfigured, server.reachable and server.authenticated:

FieldWhat it holds
cli.versionthis CLI's version
server.versionthe server's version, null when the server could not be reached or the token did not authenticate
server.latestthe newest release the server's update check has seen
server.releaseNotesUrlthat release's notes
server.checkedAtwhen the server last checked successfully
server.breakingtrue when a release between the server's version and latest is a breaking release
server.securitytrue when a release in that gap fixes a vulnerability

The five fields after server.version appear only when the server sent them: a server whose update check is off, has not succeeded yet, or predates the check yields server.version alone.

npx or a global install ​

npx mergebrief fetches the package on demand and usually runs the newest release; against an older server a major apart, the major warning names the version to pin, npx mergebrief@1.4.0. A global install (npm i -g mergebrief) stays on the version you installed until you update it, and the update line tells you about once a day, on the run after each daily check, while a newer one exists.

When the newest release is a major ahead of your server, the two lines point opposite ways across days: the update line offers 2.0.0, and once you take it the major warning asks you to match 1.4.0. They never print in the same run. Upgrading the server ends it.

Local generation and the primary ticket ​

The categorize and delta dev CLIs (tools/categorizer) resolve the PR's primary ticket from the working tree's .mergebrief/settings.yaml (trackers: list, see repo-config.md). Tracker reads use the same env as the worker (gh auth for GitHub Issues, NOTION_TOKEN for Notion, JIRA_EMAIL and JIRA_API_TOKEN for Jira, with the Jira site from the file --config names); --context <file> supplies the ticket text directly when none is available. Details in tools/categorizer/README.md.

Attaching an image to a draft ​

mergebrief draft attach <number> <file> pushes a PNG, JPEG, GIF or WebP file to the repository's mergebrief/attachments branch on the App's token and prints its URL (attachments.md). Add --draft <id> to also append the image to that held draft comment, on the revision you are on, or name one with --revision <n> or --base <sha> --head <sha>. It needs an external-write token, and the App installed on the repository.

Deleting that branch has no CLI command on purpose: it breaks images in comments already on GitHub, so the API takes the confirmation from a browser session only (403 human-only for a token). A repository admin does it from Home.

Agents ​

The agent guide ships as the mergebrief skill (skills/mergebrief in the repository). Install it into a coding agent with skills.sh:

bash
npx skills add idan91/mergebrief --skill mergebrief -a <your-agent>

The skill carries the review workflow, the authority policy, and the wire contract; the CLI's --help owns flags and payloads. mergebrief --agents now only prints where the guide moved.