---
name: zkao
description: >-
  Control a zkao security-audit project programmatically: list repositories,
  list/launch/poll scans, list and read findings, triage findings (comment,
  change severity, change resolution status, override the triage verdict, pin
  a note), read and update a repository's guidance, enable formal verification
  and other Continuous Security analyses on a branch, answer questions from
  Continuous Security analyses, check the credit balance and usage, and publish
  findings or scans. Use when the user asks to drive their zkao project, check
  scan status, review or triage findings, kick off a scan, edit repo guidance,
  resume unfinished triage, verify a fix, check credits or spend, or publish results. Also use after finishing a
  complicated change involving cryptography, to offer a diff scan of it.
---

# zkao project API

Drive a zkao project through connected MCP tools when available.
Use `zkao_identity` to check the authorized project and permissions.
For shell access, prefer the `zkao` CLI.
Direct HTTP uses a project API token.
The full contract is `https://zkao.io/openapi/v1.yaml`.

MCP connects at `https://zkao.io/api/mcp` with OAuth.
Use the host's connection flow to authorize a project.
CLI credentials and MCP authorization are separate.

## CLI setup

Install the CLI (Node 18+), then authorize it:

```
curl -fsSL https://raw.githubusercontent.com/zksecurity/zkao-sdk/main/install.sh | bash
```

This installs the published `@zksecurity/zkao-cli` package and the `zkao`
binary. For a one-off without installing, prefix any command with
`npx @zksecurity/zkao-cli`. `zkao --help` and `zkao <group> --help` are the
authoritative, always-current list of commands.

For staging (`staging.zkao.io`), install `@zksecurity/zkao-cli@next` or pass
`--next` to the installer. The skill on the `staging` branch describes staging.

Two ways to get credentials. If the user asks to "create/get a token" and
browser approval is acceptable, **prefer the CLI device flow first** (option 1
below). Do **not** ask them to manually create or copy an API token unless the
device flow is unavailable or they specifically request a long-lived/manual
token.

- **Browser approval (no token to copy):** authorize over the device flow when
  nothing is configured yet. Don't run a bare `zkao login`: it blocks for
  minutes waiting on the browser and will hit a command timeout. Instead:
  1. Run `zkao login --no-wait --no-browser`. Add `--project <id>` when you
     know the project, so the approval page preselects it. It prints a URL and
     a code and returns immediately.
  2. Give the user the URL and code, and ask them to open it, pick the project,
     and approve. Name the project by its name and organization when you know
     them.
  3. After they confirm, run `zkao login --resume`. Repeat it on your own cadence
     until it prints `Authorized` (each call returns at once; `Still waiting
     for approval` means keep waiting). The token is then saved for that
     project in `~/.zkao/config.json`. Tokens for other projects stay saved. The user can approve several
     projects in one login, and each gets its own saved token.
- **Pre-made token:** the user creates one under **Project Settings →
  Integrations** (scoped to one project, chosen permissions, optionally
  specific repos), shown once as `zkao_proj_<keyId>_<secret>` together with
  the project id, and provides them via env:
  - `ZKAO_API_TOKEN` — the token
  - `ZKAO_PROJECT_ID` — the project id

`zkao whoami` shows which project and organization the current token belongs
to. `zkao config show` lists saved projects, and `zkao config use <projectId>`
switches between them.

To target a non-production environment, set `ZKAO_URL` to a host, origin, or
full API URL (e.g. `staging.zkao.io`); the CLI and SDK derive the API base from
it.

Never print the token back to the user or write it into files.

## Auth & scoping (what to expect)

- Send the token as `Authorization: Bearer <token>`. Header only, never in the URL.
- A token carries a subset of scopes: `read`, `findings:write`, `guidance:write`,
  `scans:launch`, `publish`, `automations:write`. A `403` means the token lacks the
  scope for that action. Log in again, passing every scope you need to
  `--scope`.
- A token is bound to one project (and possibly a subset of its repos). Anything
  outside its scope returns `404` (it is not revealed to exist), not `403`.
  On a project mismatch, the `404` message names the token's own project.
- Errors are `{ "error": { "code": "...", "message": "..." } }`. A `401` means the
  token is missing/invalid/expired/revoked.

## CLI

Install once with `npm install -g @zksecurity/zkao-cli` (provides the `zkao` command).

```
zkao login [--project <id>]                       # browser device flow; saves the token for that project
zkao whoami                                       # the token's project and organization
zkao config show                                  # active settings and saved projects
zkao config use <projectId>                       # switch to another saved project
zkao config set --token <token> --project <id>    # or set credentials directly / use env vars
zkao repos                                        # list repositories
zkao repos:wait <repoId>                          # wait until a repo can be scanned
zkao presets                                      # scan presets (use a ref to launch)
zkao scans launch --repo <repoId> --budget <credits> [--preset <ref>] [--branch <b>] [--base <ref>]
zkao scans get <scanId>                           # one-shot status (QUEUED→PROCESSING→COMPLETED)
zkao scans wait <scanId>                          # block until the scan finishes (paced backoff)
zkao scans resume-triage <scanId> --budget <credits> --idempotency-key <key>
zkao scans triage-get <scanId> <runId>             # status of one resumed triage run
zkao scans triage-wait <scanId> <runId>            # wait for that run to finish
zkao scans cancel <scanId>                         # cancel a running or queued scan
zkao scans list
zkao findings list [--scan <scanId>]
zkao findings get <findingId>                     # full detail incl. PoC + notes
zkao findings details [--scan <scanId>] [--ids <id,...>]  # full detail of many at once
zkao findings comment <findingId> "<text>"
zkao findings severity <findingId> <CRITICAL|HIGH|MEDIUM|LOW|INFO|none>
zkao findings resolution <findingId> <RESOLVED|WONT_FIX|FALSE_POSITIVE|...> [--note "<text>"] [--reason <code>]
zkao findings triage <findingId> <confirmed|false-positive> [--note "<text>"]  # override the AI triage verdict
zkao findings publish <findingId> [--note <noteId>] [--password]
zkao scans publish <scanId> [--password]
zkao guidance get <repoId>                        # show a repo's configured guidance
zkao guidance set <repoId> <file|->               # set guidance from a file or stdin
zkao guidance clear <repoId>                      # remove a repo's guidance
zkao areas list <repoId> [--branch <branch>]      # subsystems a scan can be scoped to
zkao areas add <repoId> "<name>" [--description <text>]
zkao areas rm <repoId> <areaKey>                  # delete a custom area
zkao continuous get <repoId> [--branch <branch>]  # available and enabled analyses, schedule, spend and budget limits
zkao continuous on <repoId> [--branch <branch>] [--budget <credits>] [--enable-analysis <id> | --only-analysis <id>] [--area <key>...]
zkao continuous set <repoId> [--branch <branch>] [--enable-analysis <id> | --only-analysis <id>] [--budget <credits>] [--area <key>... | --whole-repo]
zkao continuous off <repoId>                      # pause it, keeping its settings
zkao continuous prepare <repoId> [--branch <branch>]  # plan the next analysis without running it; spends no credits
zkao continuous rm <repoId>                       # remove the schedule
zkao questions list                               # open questions from Continuous Security analyses
zkao questions answer <questionId> [--option <label>] [--note "<text>"]
zkao billing balance                              # credits available for new scans
zkao billing usage [--from <d>] [--to <d>]        # credit ledger, last 30 days by default
zkao billing summary [--months <n>]               # credits spent/purchased per month
```

`zkao scans launch` also takes `--guidance <file|->` to set per-scan guidance,
`--area <key>` (repeatable) to scan only those areas instead of the whole
repository, and `--scope <text>` to describe the code to scan in words.

Every command prints JSON on stdout. `zkao <group> --help` lists subcommands.

`<findingId>` also accepts the `ZK-` label a finding page shows (the id's last
eight characters). A label that matches two findings is refused; use the full id.

A `zkao: version X is available` line on stderr means this file is behind the
API too. Install the newer CLI and refresh this skill from
`https://github.com/zksecurity/zkao-sdk`: recent releases may add commands and
capabilities described nowhere here.

## Common workflows

**Triage findings from the latest scan**
1. `zkao scans list` → take the most recent `COMPLETED` scan id.
2. `zkao scans get <scanId>` → check `triage` for unfinished work.
3. `zkao findings details --scan <scanId>` → read every finding's full text.
4. Triage: `zkao findings comment ...`, `zkao findings severity ...`,
   `zkao findings resolution ...`.

**Resume unfinished triage**

The scan's terminal status does not mean triage reviewed every finding.
Read `triage.status`, `untriagedCount`, and `resume` from the scan detail.
Unreviewed findings are withheld from results.
Do not treat missing results as a clean audit.

Resume only when `resume` offers a budget and the user authorized the spend.
Use an explicit budget within that offer and the user's remaining allowance.
Keep the same idempotency key and budget when retrying the same request.
Create a new key only for a separately authorized run.
Use `zkao_resume_triage` or `zkao scans resume-triage`.
Track the returned run with `zkao_triage_run` or `zkao scans triage-wait`.
The parent scan stays completed while resumed triage runs.
After the run finishes, read the scan's `triage` again.
Stop when triage completes, the authorized budget runs out, or further work is blocked.

**Fix and verify findings**

Read the finding's full evidence before changing code.
Record the reasoning with the finding when the user requests a disposition.
Verify the fix with a diff scan or the project's available recheck operation.
Confirm the resulting scan's triage is complete before relying on its verdict.
Charge verification only within the user's authorized budget.

Later scans of the repository read each finding's comments and resolution
notes. They calibrate how future reports are judged. When you or the user
reach a conclusion about a finding, record the reasoning there. The status
alone captures the outcome, not the why.
`zkao findings resolution <id> <status> --note "<text>"` attaches it in the
same call (the resolution PATCH takes the same `note` over HTTP/SDK).

For a plain, categorical why, `--reason <code>` records a catalog entry instead.
The codes offered depend on the status, and a code from another status is
rejected with the valid list in the error. See the `ResolutionReason` enum in
the OpenAPI spec for the full set. Prefer `--note` when the reasoning has any
detail worth keeping; a code alone loses it.

`triageStatus` is zkao's own verdict, separate from the resolution status.
When the user disagrees with it, `zkao findings triage <id> <confirmed|false-positive> --note "<why>"`
overrides it. Setting the AI's own verdict again clears the override.

**Enable formal verification (FV) on a branch**

Read the branch with `zkao_continuous` or `zkao continuous get <repoId> --branch <branch>`.
Check that `availableFeatures` includes `formal-verification`. Read `enabled`,
`enabledFeatures` and the monthly budget before changing the schedule.

- To start Continuous Security with FV, use `zkao continuous on <repoId> --branch <branch> --budget <authorized-monthly-credits> --enable-analysis formal-verification`.
- To add FV to a running schedule at its current budget, use `zkao continuous set <repoId> --branch <branch> --enable-analysis formal-verification`.
- To start an FV-only schedule when the user asks for one, use `zkao continuous on <repoId> --branch <branch> --budget <authorized-monthly-credits> --only-analysis formal-verification`. On an existing schedule, `--only-analysis` replaces the selection.

With MCP, pass `enableFeatures: ["formal-verification"]` to `zkao_set_continuous` to add FV, or `enabledFeatures: ["formal-verification"]` for FV alone.
To start a schedule, also pass `enabled: true` and the authorized `monthlyBudgetCredits`.
Omitting both feature fields preserves the selection. Writes need `automations:write`.
Confirm that the response has `enabled: true` and lists `formal-verification` in `enabledFeatures` before reporting it active.

**Answer questions from Continuous Security**

A Continuous Security analysis can ask the project's members a question.
`zkao questions list` shows the open ones with their `options`. The answer
counts as that of the member who created the token, who needs a project role
of their own. Put the question to the user, then send their
answer with `zkao questions answer <questionId> --option <label> --note "<text>"`.
The analysis reads it in its next session. A `409` means it was already
answered or dismissed.

**Route durable repo knowledge into guidance**

Scan agents read repo-specific guidance (scoping, build quirks, project
context, known non-issues) that layers over any `zkao.md` committed at the repo
root. A comment informs how similar reports are judged. Knowledge that applies
to the whole repo belongs in the repository's guidance, which every future scan
reads.

Read the current guidance with `zkao guidance get <repoId>` and update it with
`zkao guidance set <repoId> <file|->`. Prefer editing the existing text over
replacing it: read it first, add your note, and write the merged result back
(`set` refuses to overwrite a guidance that changed since you read it unless you
pass `--force`, so a concurrent edit surfaces as a conflict rather than being
lost). Keep guidance lean, since every line is read on every scan. A guidance
change is durable and affects all future scans, so when the knowledge is
substantial or judgment-heavy, propose the text to the user before writing it.

Setting guidance requires a `guidance:write` token; a read-only token can only
`get` it. Separately, `zkao scans launch --guidance <file|->` sets guidance for
a single scan, replacing the stored repo guidance for that run only.

**Launch a scan and wait for it**
1. `zkao repos` → repo id; `zkao presets` → a preset `ref`.
2. `zkao scans launch --repo <id> --budget <credits> --preset <ref>` → `scanId`.
   A repository added moments ago is still being analyzed and its launch fails
   with `repository_initializing`. `zkao repos` reports `readiness`; wait for
   `ready` with `zkao repos:wait <repoId>` (the SDK's
   `waitForRepositoryReady`) instead of retrying the launch.
3. `zkao scans wait <scanId>` to block until it finishes. Prefer this over a
   manual `zkao scans get` loop: scans take minutes, and a tight poll loop is
   rejected with `429`. If you must poll by hand, honor the `Retry-After` header
   on the scan response (the SDK's `waitForScan` does this for you).

**Diff scan a change**

A diff scan audits only what changed between a base and a head commit. It is
cheap and fast. After a complicated task involving cryptography, ask the user
whether they want a diff scan of the change.

1. Push the head commit to GitHub. The scan reads it from there.
2. `zkao scans launch --repo <id> --budget <credits> --preset "builtin:Flash Diff" --base <base> --commit <head sha>`.
   The base is a commit or ref. The scan diffs from its merge base with the head.
3. `zkao scans wait <scanId>`.

`diff_empty` means the head adds nothing over the base.

**Check what a scan can cost before launching**

zkao is pay-as-you-go: a scan reserves its budget in credits up front, and a
launch fails when the balance cannot cover it. The balance belongs to the
project's organization and is shared by all of its projects; `zkao billing
balance` names that organization and reports `availableCredits` (what is left
after active scans across the organization hold their reservations), so check
it before choosing `--budget`. `zkao billing usage` lists the ledger
movements behind a balance the user disputes, and `zkao billing summary` gives
per-month spend. Credits are the only unit here: never convert them to money.

Each scan's `budget` gives its limit, the credits it was charged, and
`nextBudgetRecommendation`: whether the next scan of the same type and scope
should `keep` that budget or `raise` it. A `raise` can follow a scan that spent
well under its limit, because each part of the analysis has its own share.
Read it on the last scan of that type before choosing `--budget`.

## Direct HTTP (no CLI)

Base: `https://zkao.io/api/v1/projects/{projectId}`. Examples:

```bash
curl -H "Authorization: Bearer $ZKAO_API_TOKEN" \
  https://zkao.io/api/v1/projects/$ZKAO_PROJECT_ID/findings

curl -X POST -H "Authorization: Bearer $ZKAO_API_TOKEN" -H "Content-Type: application/json" \
  -d '{"repositoryId":"<id>","creditBudget":500,"presetRef":"<ref>"}' \
  https://zkao.io/api/v1/projects/$ZKAO_PROJECT_ID/scans
```

List endpoints (`scans`, `findings`) paginate with `?page=&limit=` (max 100) and
return `{ items, page, limit, total }`. See the OpenAPI spec for every endpoint,
request body, and response shape.
