v12 CLI

Command-line client for the v12 public REST API — start security audits, watch runs, and triage 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 v12.sh under Settings → Developer, then:

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 |

Usage

v12 me                                      # account, org, credit balance, scopes
v12 repos --search engine                   # list repositories

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

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

# Diff reviews — quote and audit a change instead of the full target:
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
v12 runs create --name "zip diff" --zip-uid 87 --patch-uid <uuid>   # reuse a quoted patch
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 [email protected]

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"

runs create shows the resolved scope (every file the audit will cover) and the quoted cost, then asks for confirmation before creating the run. GitHub creates are pinned to the sha the quote was computed for.

Scripting

runs create is interactive: it shows the resolved scope (every file the audit will cover) and the quoted cost, then asks for confirmation before creating the run. GitHub creates are pinned to the sha the quote was computed for, and a --patch quoted during confirmation is created via its stored patchUid so the run reviews the byte-identical patch. Use -y/--yes, --json, or non-TTY stdin to create directly without prompting.

Diff reviews take --from-ref plus one change source: --to-ref (GitHub only), --patch <file>, or --patch-uid <uuid> from a prior estimate. Zip diff reviews use --patch or --patch-uid without refs. Diff reviews cannot be combined with --branch/--sha.

• Every command accepts --json for machine-readable output.
• With -y/--yes, --json, or non-TTY stdin, runs create skips the confirmation prompt.
• v12 runs watch exits 0 when the run completes and non-zero when it fails or is cancelled — usable directly as a CI gate.