CLI

Install the V12 command-line client, authenticate with a personal access token, and drive the audit lifecycle from your terminal or CI.

@v12sh/cli is the command-line client for the REST API. It quotes, starts, and watches runs, then reads and triages findings—without leaving the terminal.

Install

npm install -g @v12sh/cli
# or run it ad hoc
npx @v12sh/cli --help

Requires Node 20.19+; Bun works too.

Authenticate

Create a personal access token at Settings → Developer, then hand it to the CLI:

v12 auth login    # paste the token when prompted; validated before saving
v12 auth status   # where credentials come from and whether they work

The token is stored in ~/.config/v12/config.json. Two environment variables override it:

Variable	Effect
`V12_API_TOKEN`	Use this token instead of the stored one (CI-friendly)
`V12_API_URL`	Point the CLI at a different deployment

Run an audit

Quote first—estimate resolves the scope and price without creating anything:

v12 runs estimate --repo owner/name         # scope files + cost, no run created
v12 runs estimate --zip ./src.zip           # uploads, quotes, prints a --zip-uid for reuse

Then create the run:

v12 runs create --name "audit" --repo owner/name --branch main
v12 runs create --name "audit" --zip ./src.zip --paths contracts/
v12 runs create -y --name "audit" --zip-uid 87   # reuse the upload from a prior estimate

runs create prints the resolved scope and the quoted cost, then asks for confirmation. GitHub runs are pinned to the sha the quote was computed for. Track progress with:

v12 runs list
v12 runs watch 42                           # poll until completed/failed
v12 runs report 42 --markdown
v12 runs cancel 42
v12 runs share 42 --email teammate@example.com

Read and triage findings

v12 findings list 42 --severity critical --severity high
v12 findings get 42 7
v12 findings update 42 7 --validity acknowledged --reason "tracked in JIRA-123"
v12 findings fix 42 7
v12 findings poc 42 7
v12 findings comment 42 7 -m "false positive, see thread"

Review a diff

Pass --from-ref plus exactly one change source—--to-ref (GitHub only), --patch <file>, or a --patch-uid from an earlier estimate. Zip diffs use --patch/--patch-uid with no refs. Diff reviews can’t be combined with --branch/--sha.

v12 runs estimate --repo owner/name --from-ref main --to-ref feature
v12 runs create --name "pr review" --repo owner/name --from-ref main --to-ref feature
v12 runs create --name "patch review" --repo owner/name --from-ref main --patch ./fix.patch

Attach context

Scope notes, specs, and prior audits sharpen a run. Upload once, reuse per run:

v12 context upload ./scope.md --annotation "audit scope for the vault module"
v12 context note --text "focus on withdrawal paths"
cat notes.md | v12 context note --title "spec"   # text from stdin
v12 context list --repo owner/name
v12 runs create --name "audit" --repo owner/name --context-doc <document-uid>

Scripting and CI

--json returns machine-readable output from every command that carries data: me, repos, auth status, runs list/get/estimate/create/watch/report/share, and all findings and context subcommands. runs cancel, auth login, and auth logout only ever print prose.
-y/--yes, --json, or non-TTY stdin skips the confirmation prompt.
v12 runs watch exits 0 when the run completes and non-zero when it fails or is cancelled, so it works directly as a CI gate.

V12_API_TOKEN="$V12_TOKEN" v12 runs create -y --json \
  --name "ci audit" --repo owner/name --sha "$GITHUB_SHA" | jq -r .run.uid

Prefer a hosted integration? Autopilot reviews every pull request without any CLI wiring.