ironbee review reviews your branch against the repository’s default branch, the way a pull request (on GitLab, a merge request) of it would be reviewed, without opening one. The review runs on IronBee: the CLI sends what the remote doesn’t have yet, the reviewer reads the change, and the findings come back to your terminal. A second review of the branch follows the first, and reads only what changed since.
Before you start
- The repository is bound to a project of your team: a github.com repository connected through the IronBee GitHub App, a gitlab.com project whose group is connected in the console, or a bitbucket.org repository whose workspace is connected in the console. Otherwise the API refuses the review with
NOT_FOUND: no project of the team is bound to the repository. - Code review is turned on for the repository. It is on by default; see Code review settings. Otherwise the API refuses it with
CODE_REVIEW_DISABLED. - IronBee can reach the repository the review targets: the GitHub App is installed for it, its GitLab group is connected, or its Bitbucket workspace is connected. Otherwise the API refuses it with
GITHUB_INSTALLATION_MISSINGon GitHub, orVCS_NOT_CONNECTEDon GitLab or Bitbucket, where the CLI adds that the group, or the workspace, needs connecting in the IronBee console. Either way, the CLI lists your checkout’s github.com, gitlab.com and bitbucket.org remotes so you can pick another with--remote. - You’re signed in with
ironbee login, or a credential comes from the environment. See Where the review goes, and as whom. - Your team has credits left this month.
- git 2.25 or later, and the full history: in a shallow clone, run
git fetch --unshallowfirst.
What gets reviewed
The review covers your branch against the remote’s default branch, as you last fetched it: the remote’sHEAD, else its main, else its master. Run git fetch first if the default branch has moved. If the remote’s HEAD isn’t recorded (a remote added with git remote add, for example) and the default branch is neither main nor master, run git remote set-head <remote> -a or pass --base.
- Commits already pushed: the reviewer fetches them itself.
- What the remote doesn’t have yet: your unpushed commits, flattened into one, and your staged changes. The CLI sends them as one patch over a commit the remote has.
When the branch has no change against the default branch and nothing local is sent, the command says
nothing to review and exits 0.
What leaves your machine
By default, only whatgit push would send, plus your staged changes:
To send unstaged edits or untracked files on every run, turn the two switches on in your repository’s personal file or in the global config. A file inside the checkout can’t set them:
--include-unstaged or --include-untracked instead. The flag turns the switch on for that run only, and the configured value stays as it is.
Exclude paths
review.exclude lists paths that never leave your machine:
*matches within one path segment, and**across segments.- A trailing
/names a folder and everything below it, as in.gitignore:secrets/is the same assecrets/**. - Every other character is literal.
* in its last segment that matches a folder of a changed file, such as secrets for secrets/key.pem, refuses the run: write secrets/ instead. A pattern whose last segment has a * and matches a folder only gets a warning, since its files are still sent. The run also refuses:
- a
review.excludethat isn’t a list, or areviewvalue that isn’t an object - more than 100 patterns in total, across all layers
- a pattern longer than 500 characters, or with more than 10
** - a pattern that starts with
/or has a..segment
config.json, config.local.json, and every tracked nested .ironbee/config.json. A nested file’s patterns match under its own folder. A file renamed from an excluded path, or with the same content as one, is left out with it.
For one run, --exclude <glob> keeps more paths home, on top of every configured pattern:
- It’s repeatable, and a value can hold a comma list:
--exclude 'fixtures/**,**/*.snap'. - It uses the
review.excludegrammar, matched from the repository root, with the same refusal rules. Its patterns count toward the 100. - Quote the glob so your shell doesn’t expand it. A glob the shell expanded anyway arrives as extra arguments, and the command refuses them rather than send part of what you meant.
Check before you send
Before anything is sent, the command prints what it sends and where it goes:size line counts every changed file and line. Its reviewable lines are what the review is priced by: they leave out lock, generated, vendored, minified and binary files, data files under a test or fixture folder, and files the change deletes. A follow-up is priced by the lines changed since instead.
The block can also carry:
- a
seriesline: the review a follow-up continues, its round and the lines changed since, such asfollow-up of <job-id> (round 2) · 12 changed lines in 3 files since, of 236 in the change, or why the run is a first review - a
gateline, when you pass--gate flagas a switch’s source, when--include-unstagedor--include-untrackedturned it on
- matched by
review.excludeor by--exclude, or renamed from or identical to a path one of them matched - matched by your ignore rules
- IronBee’s own files
- a link pointing outside the repository
.ironbee/config.json files whose exclusions joined, the folders a starred pattern matched while their files are sent, and not sent lines that count the files with unstaged changes and the untracked files the switches would send.
--dry-run stops there. It prints the block, the files in the patch and the price, and starts no review. When there’s nothing to review, or nothing changed since the last review, it asks for no price, and the JSON then has no estimate. To get the price it sends only the repository, the size and the settings, plus, on a follow-up, the previous review’s id and the lines changed since. With --json, it prints the same as one JSON document, whose estimate holds credits, sizeClass, depth, reviewableLines and left. sizeClass is the API’s code, so XXXL there reads 3XL in the text form. When the price can’t be looked up, estimate is null, estimateError holds its code and message, and the command still exits 0.
The JSON’s followUp is the review the run would follow, with its previousJobId, the round, and the lines and files changed since, or null for a first review. On a follow-up, estimate.reviewableLines and estimate.sizeClass are those of the lines priced, and estimate.read says what the price is on: delta for the lines changed since, whole for the whole change again, or nothing. When nothing changed since the last review, the block says that no review would be created and nothing spent, and the JSON carries unchangedSince.
Size limits
The run is refused before anything is sent when the change has:- more than 1,000 files, or more than 100,000 changed lines. These count every changed file, deleted files included, although deleted files add nothing to the price
- a patch of more than 1,000 paths, more than 16 MiB gzipped, or more than 64 MiB uncompressed
- a binary file over 16 MiB, or binary files over 64 MiB in all
review.exclude to bring it down. A large patch is uploaded through the collector first, and a small one travels with the request. When the API URL is set explicitly (--api-url, IRONBEE_API_URL or api.url) and the collector URL isn’t, a patch too large to travel with the request is refused. Give the collector’s URL too: --collector-url, or collector.url in the personal file or the global config. No environment variable sets it.
Symlinks in IronBee’s folders
The run is refused when a.ironbee folder at any level, or anything inside one, is a symbolic link, whether it’s tracked, untracked or ignored. Such a link could move IronBee’s files outside the paths the review leaves out. Replace it with a real folder or file.
Where the review goes, and as whom
The endpoints, the credential and the two switches decide where your code goes, and as which team.ironbee review reads them only from these sources, first winning:
- the flags
--api-urland--collector-url, and for this run’s switches,--include-unstagedand--include-untracked - the environment, as for
ironbee verify:IRONBEE_ACCESS_TOKEN,IRONBEE_API_KEY,IRONBEE_API_URL, and theIRONBEE_SERVICE_*variables - the repository’s personal file
- the global config,
~/.ironbee/config.json
config.json, config.local.json or a nested .ironbee/ file. A value it finds there is ignored with a warning. That way a repository you cloned can’t send your code to another endpoint, or under another team’s credential.
- A personal file that exists but can’t be used refuses the run, rather than falling back to the global config. That’s the case when it was written for another repository, or when it, or a folder above it under
~/.ironbee, isn’t owned by you or is world-writable. - A global config that isn’t owned by you or is world-writable loses these keys. The warning prints the
chmodcommand that fixes it.
Review settings
These are the console’s code review settings, under other names:
--focus:securityis Security, andeditorialis Docs, names and tests.--checks:lint,style,defensive,tests,cleanupandpitfallsare the Extra checks Linter rules, Style and typos, Input checks and error handling, Missing tests, Duplication and dead code and Language and framework gotchas.--no-knowledgeturns off Rules and memories from the repository. See Rules and memories.
config.local.json, then config.json, then the global config. A setting set nowhere isn’t sent, so the repository’s setting, the account’s or the default applies. A flag with a value outside its list is an error, and the run exits 1. A config value outside its list is warned about and not sent.
Follow-up reviews
A second review of the same branch on the same machine follows the first, the way a push to a pull request does. The reviewer reads only what changed since, carries the earlier findings to the new code, and says which ones were fixed. The round is priced by the lines changed since the review it follows. When the earlier round left files unread, or most of the change is new since, the platform reads and prices the whole change again, and the result saysread whole.
A run looks at the newest review that succeeded in this worktree, for the same branch, remote and base. A newer review that failed or was cancelled is skipped. A newer one that’s still running, or whose state the CLI can’t read, means no follow-up this time. When you review the base’s own branch, such as main against origin/main, only a review over the same pushed commit counts, so the first run after a push is a first review. The run follows that review when it:
- sent the same set of changes: the same unstaged and untracked switches, whether a flag or the config set them, and the same
--excludepatterns - kept the history a follow-up continues from, with its apply point still on the remote. After a rebase and a force-push, the apply point is often gone
- has never had a follow-up fail for want of it. After such a failure, the CLI doesn’t follow that review again
- is at most six days old
series line of the pre-send block says why not, and the run is a first review, even when an older review would qualify. A detached HEAD has no series of reviews, so name the review with --previous. Neither has a branch created again since the review, moved with git branch -f, git checkout -B or git switch -C, or renamed or copied onto its name. A plain git reset doesn’t end the series. Reviews stored by a CLI before 0.51 never start a series, so your first review after upgrading is a first review.
When nothing changed. When the files are the same over the same pushed commit, asked with the same settings, no review is created, unless you pass
--fresh. The command shows the previous result again, and --json marks it with unchangedSince: <job-id>. Other review settings, such as --depth, --focus or review.settings, make a first review instead. Another --gate alone makes a follow-up that reads nothing, and marks every finding again under the new gate. The rules above still apply, apart from the same set of changes. Such a round is free, unless the platform has to read the whole change again.
When the platform can’t take a follow-up, or the earlier review’s tree is gone from your repository, the run falls back to a first review and says why in one line. With --previous, a missing tree refuses the run instead. When git can’t measure the lines changed since, because it was killed, timed out or its output overflowed, the run stops instead, and says to pass --fresh or to drop --previous. A round that read nothing new isn’t charged. The uploaded patch is kept seven days, so a review can be followed for six.
With --json, every result carries round and read: read is first on a first review, else delta, whole or nothing. A follow-up’s result also carries previousJobId. The result’s round is a string: the round number, then a short commit, such as 2-a1b2c3d. The dry run’s followUp.round is the plain number.
Findings and what blocks
Each finding carries anid and a state:
A finding carried from an earlier round comes without a suggested fix or a diagram. The counts,
--fail-on and the exit code count only new and open findings. The text form lists fixed and dropped ones after the rest. SARIF leaves them out, and carries each other finding’s state in its result’s properties.
Each finding also carries blocking: whether it blocks under the review’s gate. The gate is the repository’s merge gate, its Block merging when setting, unless you pass --gate for the run:
A finding listed because it’s below the repository’s comment threshold never blocks, whatever the gate.
The result names its gate as
result.gate: blockAt is the severity or never, and source is request for --gate or repository for the merge gate. With --dry-run --json, the document carries gate when you passed --gate. --fail-on stays its own severity, whatever the gate.
Output
The text form starts with a header: the repository, the branch, the commit range, the depth with the review’s credits, and the counts by severity. On a follow-up, it adds the review it follows, the round and what it read, such as
follow-up of <job-id> · round 2 · read delta (12 lines). When the result names its gate, a line such as gate medium (the repository's merge gate) follows.
Then come the summary and the findings, grouped by file. Each finding reads severity path:line claim, followed by its explanation, the reviewed code around the line, the suggested fix as a diff, and a diagram’s source. On a follow-up, each line starts with the finding’s state, and a finding carried from an earlier round adds its newest reading on a reading: line. Findings the reviewer only lists come next, one line each, and one that blocks ends with (blocking). The fixed and dropped findings come last, under their own headings. The final line counts the findings, the blocking ones among them when the result names its gate, and the fixed and dropped ones when there are any.
The summary and the findings’ texts are Markdown. They’re rendered on a colour terminal and printed as written for a log. --json and --format sarif keep them raw. Set NO_COLOR to drop every colour.
When the command itself fails:
--jsonprints an error envelope:{ "error": { "code": "…", "message": "…" } }.codeis the API’s error code,REFUSEDwhen the CLI refused the run, orERRORotherwise. A credits refusal adds the numbers aserror.credits, see When credits run out.--format sarifprints a SARIF document withexecutionSuccessful: falseand the error as acli_errornotification.
Progress
Progress goes to stderr in every form, so stdout carries the document alone:- On a terminal: a live block with the repository, the branch, a progress bar, the
preparing → reviewing → checking → writingsteps and the elapsed time. It collapses into one line when the review ends. - In CI or a pipe: one line per status or phase, such as
review queuedorreviewing 45% (12/27), then a final line such as✓ review done in 02:41 · <counts>.
Ctrl-C cancels a running review.
The Review area
On a terminal,ironbee review opens the review in the Review area of the TUI when it succeeds. ironbee tui review opens the area with the stored reviews, this worktree’s first.
When the result names its gate, the header shows it, who set it and the blocking count, such as gate low (this run) · 2 blocking. On a follow-up, it also shows the review it follows, the round and what it read. The left pane lists the findings, grouped by file. A finding that blocks says (blocking). On a follow-up, each row starts with its state, and the fixed and dropped findings show their path, with no context or fix. The right pane shows the selected finding:
- the reviewed code around the line, with the line marked and syntax colour
- the explanation, and for a finding carried from an earlier round, its newest reading under Reading
- the diagram’s Mermaid source
- the suggested fix as a word-level diff
a writes the fix to the working tree and stages nothing. It works on this worktree’s reviews only, and a fix you already applied isn’t offered again. It refuses when:
- the finding is
fixedordropped, so there’s nothing to apply - the file changed since the review, or the reviewed version is gone or can’t be read
- the reviewer marked the fix’s indentation as differing from the file’s. Copy the fix with
c, or open the file withe - the fix’s lines fall outside the reviewed file
- the finding is on a symlink
- the text holds hidden control characters
Read a review again
ironbee review is short for ironbee review run, which takes every flag above. The other subcommands read a review back:
showandstatustake the output flags above (--format,--plain,--json,--min-severity,--fail-on), plus-C,--remoteand--api-url.canceltakes-C,--remoteand--api-url.showrenders the stored copy of a finished review, else asks the API.statusexits3while the review is still going. It also works outside a checkout, with a credential from the flags, the environment or the global config.
Follow a review
status --watch follows a review to its end, with the progress of a run, then renders it as status does:
--max-wait <seconds>bounds the watch. When it passes first, the command prints one line, or the job’s body with--json, and exits3. Without it, the watch has no limit. It needs--watch.- A watch never cancels the review.
Ctrl-Cends only the watch. --queue-wait <seconds>ends the watch when the review hasn’t started within it (default900), and exits3. The review stays queued.- When a review created from this checkout ends, the watch completes the stored copy of it.
~/.ironbee/projects/<token>/reviews/, keeping the newest 20 per worktree. Linked worktrees of one repository share the folder. See Runtime files.
Exit codes
From a coding agent
With verification on, in enforce or assist mode,ironbee install adds the /ironbee-review command to Claude Code and Cursor, and the $ironbee-review skill to Codex. Monitoring-only mode doesn’t install it. The agent runs ironbee review on your working tree as it is, staged, unstaged and untracked changes included, and reports the result. On request, it fixes what blocks and reviews again.
The first word is the mode:
report, the default, fix or price. The rest come in any order:
- a severity word,
low,medium,highorcritical: what blocks for this run. It reaches every review of the run as--gate, the price’s dry run included looporrounds:<n>: review again after each fix pass. Outsidefixmode they’re ignored, and the reply says soexclude:<glob,...>: paths kept out of every roundfresh: a first review, even when a follow-up of an earlier one is possible or nothing changed
rounds: value outside 1 to 20, stops the command: the reply names it and the grammar, and nothing runs.
The agent fixes only the findings IronBee marked blocking. It reads each one in the current file first, and treats a suggested fix as a hint, never applying it blindly. The loop’s cap is rounds:<n>, else review.fix.maxRounds: an integer from 1 to 20, 5 by default.
/ironbee-review fix rounds:1 reviews them.
A review spends your team’s credits, so the agent never starts one on its own: the command runs only when you type it. On Codex, the agent asks once to run ironbee review and ironbee credits outside the sandbox, since the review writes a temporary index under .git and needs the network.
What’s next?
Credits
What a review costs, and how to see what your team has left.
Configuration
The
review.* keys and the personal file.