The Cerbie CLI

cerbie review runs a full Cerbie review of your branch before you open a pull request. Fix what it finds while the change is still local, then open the PR: if the code is the same as what you reviewed, Cerbie posts that review on the PR straight away instead of reviewing again.

The review runs on Cerbie’s servers with the same reviewers, policy and .cerbie/ configuration as pull request reviews. Your machine only packages the change.

Install and sign in

npm install -g cerbie       # or run it without installing: npx cerbie review
cerbie login                # opens github.com/login/device; approve the CerbieAI app

You need read access to the repository on GitHub, and Cerbie has to be enabled for it (any mode except off). The session lasts 90 days. cerbie logout ends it.

Review

From anywhere inside a clone whose origin is on GitHub:

cerbie review                 # this branch plus uncommitted changes, against the default branch
cerbie review --committed     # leave out the working tree
cerbie review --base release  # compare against another branch
cerbie review --json          # machine-readable result, e.g. for Claude Code or Codex to work through
cerbie review --no-wait       # submit, print the run URL and exit; `cerbie show <id>` picks it up later

Exit status	Meaning
0	Nothing blocking (approved, or non-blocking suggestions only)
1	Blocking findings: Cerbie would request changes on a PR
2	The review failed or couldn’t cover the whole change

The base is origin/<branch> as your clone knows it; Cerbie diffs from its merge base with your head, exactly like a pull request. Nothing is pushed: the CLI uploads a git bundle of the commits between the merge base and your head. Uncommitted changes (tracked and untracked files, respecting .gitignore) are captured in a temporary commit made from a copy of your index, so your repository, index and refs are left untouched.

Results appear in the terminal and in the dashboard under Reviews, marked local. Local reviews never post anything to GitHub.

Caching: review once, post instantly

Every review is cached against the code, not the commit:

• the merge base with the target branch,
• the head tree (the exact content), and
• a fingerprint of everything else that shapes findings: the target branch’s .cerbie/ files and guideline files (AGENTS.md, CLAUDE.md, …), organisation instructions, the linked Linear ticket as it was read, the model recipe and the prompts.

Because it’s the tree that counts, these all hit the cache: committing exactly the uncommitted changes you reviewed, amending a commit message, squashing, or rebasing interactively without changing content. Rebasing onto a newer main changes the merge base, so it’s a fresh review.

When a pull request is opened (or marked ready) and Cerbie hasn’t reviewed it before, it looks for a complete review of the same code. If it finds one, it writes a fresh summary for the PR, posts the cached findings and verdict with inline comments, and notes that the code was reviewed locally first. If a review of the same code is still running, for example cerbie review --no-wait && gh pr create, the PR waits for it rather than paying for the same review twice.

Cached reviews are never reused when the earlier review was incomplete, incremental or more than 14 days old, when the policy fingerprint differs, or for @cerbieai review and re-runs, which always review afresh. cerbie review --fresh skips the cache too.

Limits

Local reviews use the same LLM capacity as pull request reviews, so they’re rate limited to keep headroom for PRs. There are two budgets:

Budget	Limit	Default
Reviews (runs that review in full)	Per person per hour	5
	Per person per day	25
	All local reviews per hour	40
Submissions (every upload, cache hits included)	Running at once per person	2
	Uploads per person per hour	30

Reviews served from the cache don’t count against the review budget. A submission that looks like a cache hit is let in uncharged; if it turns out to need a full review (the code or policy differs), it’s charged before reviewing, and refused if the budget is spent. Admins can change the limits without a deploy (PUT /api/settings/cli-limits with perUserHour, perUserDay, globalHour, perUserConcurrent and perUserSubmissionsHour; setting any to 0 turns local reviews off). Changes are capped at 3,000 files and a 64 MB bundle.

For scripts and CI

CERBIE_TOKEN and CERBIE_SERVER override the stored login and server. Sessions are stored in ~/.config/cerbie/cli.json (mode 600).

Releasing

Bump version in packages/cli/package.json, merge to main, then run scripts/release-cli.sh from an up-to-date main. It pushes a cli-v<version> tag, and .github/workflows/release-cli.yml publishes that version to npm with trusted publishing (GitHub OIDC, no npm token). The first run also creates the package on npm and the trust configuration, which needs an npm account with 2FA.