`brama review`¶

Ask a Brama gateway to review one change. The model gets the caller's instructions and request, may read and search the files of one directory, and ends by submitting a typed verdict: approve or request_changes with the review text. The verdict is the exit status, so a pull-request gate is the command itself.

Invocation¶

brama review --gateway <URL> --model <ALIAS> --instructions <FILE> --request <FILE> --root <DIR> --max-turns <N> [--output <FILE>] [--json] < bearer

Input	Required/default	Meaning
`--gateway <URL>`	required	Base URL of the gateway, for example `https://brama.wisent.com`. The review is asked of its `POST /v1/chat/completions`.
`--model <ALIAS>`	required	The alias the review is asked of; it must be a route that accepts tools.
`--instructions <FILE>`	required	The reviewer's instructions, sent as the system message. The repository owns them.
`--request <FILE>`	required	What is reviewed: the change's description, the files it touches, its diff.
`--root <DIR>`	required	The only directory the model can read or search. Every path is resolved, symlinks included, and refused when it lands outside.
`--max-turns <N>`	required	Most model turns before the review fails as unfinished.
standard input	required	The gateway bearer, for example `skarbiec get <item> --field token \| brama review …`. It is never taken from argv or the environment.
`--output <FILE>`	optional	Also write the review text to this file, for posting it (for example `gh pr review --comment --body-file`).
`--json`	optional; off	Print `{"verdict", "review", "turns"}` instead of the review text.

The model's tools¶

Tool	What it answers
`read_file {path, start_line?, end_line?}`	Numbered lines of one file under the root; the whole file without a range.
`search {query, case_sensitive?}`	`path:line:text` for every line of every file under the root (`.git` skipped, symlinks not followed) holding the literal string.
`submit_verdict {verdict, review}`	Ends the review. `verdict` is `approve` or `request_changes`; the review text must be non-empty.

A tool call that breaks its contract gets tool refused: <reason> back and the model may correct it. A turn with no tool call is answered with a request to submit the verdict. The verdict is never read out of prose.

Exit status¶

Status	Meaning
0	The model approved.
3	The model requested changes. The review text was printed (and written to `--output`).
1	No review: see the refusals below. Nothing was approved.

Refusals¶

Each prints review failed: <reason> on standard error and exits 1.

Reason	Meaning
`standard input carried no gateway bearer; …` or `the gateway bearer could not be read from standard input: <error>`	Nothing usable was piped in.
`<FILE> is empty` or `<FILE>: <io error>`	The instructions or request could not be read, or hold nothing.
`review root <DIR>: <io error>`	The root does not exist or is not a directory.
`<URL> answered <status>: <body>`	The gateway refused the completion; its own status and body follow.
`<URL> could not be reached: <error>`	No connection to the gateway.
`submit_verdict carries no valid verdict` / `no review text`	The model submitted outside the schema; it is not read as either verdict.
`the model did not submit a verdict within N turns`	`--max-turns` ran out.

Example: a Supabase schema gate¶

$ gh pr view "$PR_NUMBER" --json body --jq .body > review/request.md
$ git diff --unified=40 "$BASE_SHA...$HEAD_SHA" -- supabase/migrations >> review/request.md
$ skarbiec get <item> --field token | brama review --gateway https://brama.wisent.com --model wisent-backend/evaluation \
    --instructions release/schema-review.md --request review/request.md \
    --root supabase/migrations --max-turns 10 --output review/review.md
$ gh pr review "$PR_NUMBER" --comment --body-file review/review.md