Recipes

Triage the inbox, start a run within a price limit, review a change, and push code to a repository V12 hosts, with the CLI, REST or an MCP assistant.

The REST examples read an API key from V12_API_TOKEN and the workspace slug from V12_ORG. The API quickstart shows how to get both.

Triage the inbox

v12 findings list --status open --severity critical,high
v12 findings status fixed F-12 F-15
v12 findings assign me F-12
v12 findings comment F-12 --body "The fix is in #482."

Inside a Git clone, findings list shows the inbox of the origin repository. Pass --repo owner/name for another repository, or --org for every repository.

On every surface:

  • Each request makes one kind of change: a status, a severity, or an assignee.
  • A status change takes no reason. To say why, comment on the finding.
  • Findings already in the requested state are left unchanged and listed in skipped, so a repeated change is safe.
  • open, fixed and false-positive are recorded at a position: the head of the default branch, unless you pass repository and at (--repo and --at in the CLI). investigating and wont-fix apply everywhere. See Status.
  • A finding that exists only off the default branch, such as one a change review reported, answers not_found until you pass repository and at: use the repository and position.at that the run's findings report. For investigating, wont-fix, severity and assignee they only locate the finding, and the change still applies everywhere. A comment takes the same two fields.

Start a run within a price limit

An estimate's priceCents is the most the run can cost, and your maximum is checked against it. Its minPriceCents is the least a change review costs when it completes, and null for a fixed price, which is charged when the run starts. A change review reserves priceCents when it starts and, when it completes, is charged its metered model usage, between minPriceCents and priceCents; one that fails or is cancelled costs nothing. A run's reservedCents is the amount reserved while such a review is queued or running, and null otherwise. Its costCents is what it was charged, 0 until such a review completes.

The repository must be in the workspace, or the estimate answers 404 repository_not_added. Add it with v12 repos add acme/api, POST /repositories or the MCP tool add_repository, then estimate again. Adding a repository is free and doesn't start a run.

A full review reads only the folders (ending in /) and files its scope names, relative to the repository root. There is no default, so every variant below names src/.

v12 runs start --repo acme/api --at branch:main --scope src/ --max-price 25 --watch

The command prints the price, asks you to confirm, then starts the run with the quote and a maximum of $25. --max-price is in dollars; --max-price-cents takes cents. Without either, the quoted price is the maximum. --watch follows the run, then lists its findings.

In CI, add --yes, or the command stops with exit code 2.

Errors to expect (see the error reference):

  • price_exceeds_max: the price is above your maximum. details has priceCents and maxPriceCents.
  • invalid_request with an issue at scope or scope.<n>: the scope is missing, or that path names no file V12 reviews at the position.
  • quote_stale: the quote expired, or what it priced changed. Estimate again.
  • insufficient_credits: the workspace needs more credit; see Add credit.
  • spend_cap_reached: the workspace hit its monthly limit.

The CLI exits with code 5 on each.

Review a change

A change review reads only what a pull request or a branch's new commits changed, so it takes no scope. It needs the same price limit and added repository as a full review; see Start a run within a price limit.

# A branch's commits since it left the default branch.
v12 runs start --repo acme/api --branch feature/limits --max-price 10

# The default branch's last commit: since its parent. The CLI resolves --since in this checkout.
v12 runs start --repo v12/payments-api --branch main --since HEAD~1 --max-price 10

# A pull request, on a GitHub repository.
v12 runs start --repo acme/api --pr 482 --max-price 10
  • change.branch reviews the branch's commits since it left the default branch.
  • To review the default branch itself, pass since: the full 40-character SHA of the last commit already reviewed, which the branch must build on. Without it, V12 answers 409 change_refused with identical, and its message asks for since. The CLI's --since also takes an abbreviated SHA or a revision such as HEAD~1, and resolves it in the checkout.
  • change.pr works only on GitHub repositories. On a hosted repository it gets 400 invalid_request at change.pr.
  • Don't send at, scope or repositories with change; each gets 400 invalid_request.

Errors to expect, besides those of a full review. Each message says what to send instead:

  • change_refused, with details.reason:
    • thin: no changed file is reviewable source;
    • identical: no file differs between the base and the branch, for example a commit followed by its revert, or the default branch without since;
    • large: more than 3,000 changed files, removed ones included;
    • detached: since is not a commit the branch builds on, or, without since, the branch shares no history with the default branch.
  • position_unavailable, with details.reason:
    • unknown-branch: the repository has no such branch, and details.ref is its name without refs/heads/; finding reads answer it too. When details.ref is its default branch (a hosted repository that got another branch first), push the default branch first;
    • unknown-pull-request: the GitHub repository has no pull request with that number.

Push code to a hosted repository

V12 can host a Git repository for code that isn't on GitHub; see Hosted repositories. Only Admins can create one or push to it, with a token that has repos:write.

# 1. Create an empty repository. It is addressed as v12/<name> from then on.
v12 repos create payments-api

# 2. Push this checkout's commit. Without --branch: the default branch while the repository has none, else the current branch.
v12 repos push v12/payments-api

v12 repos push needs Git 2.31 or later. It gets a push URL for one branch and pushes --ref (default HEAD) to it. Without --branch, it pushes to the repository's default branch while the repository has none, since reviews read from it, and otherwise to the current branch (when --ref is HEAD). It hands the URL to Git through Git's environment, so the URL never appears in a command line, a Git hook's arguments, a credential store or the output. Push again after each commit; every push gets a new URL.

On this page