These docs describe staging.zkao.io and the @zksecurity/zkao-cli@next release. For production, see docs.zkao.io.

Quickstart

This page takes you from nothing to your first findings in a terminal. You need Node 18 or later and a zkao project with at least one repository.

Install the CLI.
Terminal window
```
npm install -g @zksecurity/zkao-cli
```
This installs the zkao command. For a one-off run without installing, prefix commands with npx @zksecurity/zkao-cli. You can also use the install script:
Terminal window
```
curl -fsSL https://raw.githubusercontent.com/zksecurity/zkao-sdk/main/install.sh | bash
```
Authorize it for a project.
Terminal window
```
zkao login
```
The CLI opens a browser page and prints a short code. Check that the page shows the same code. Pick a project, review the permissions, and approve. The CLI saves the token for that project. There is nothing to copy.

Confirm which project you are connected to:
Terminal window
```
zkao whoami
```
See Authentication for tokens, scopes, and non-interactive logins.
Find a repository.
Terminal window
```
zkao repos
```
Note the id of the repository to scan. Its readiness must be ready. A repository added moments ago is analyzing for a short while. zkao repos:wait <repoId> blocks until it is ready.
Pick a scan preset.
Terminal window
```
zkao presets
```
Each preset is a scan type. Note the ref of the one you want.
Launch the scan.
Terminal window
```
zkao scans launch --repo <repoId> --preset <ref>
```
The response carries the scanId and the budget the scan reserved, in credits. Without --budget, zkao picks the budget it recommends for this scan type on this repository. Pass --budget <credits> to set your own ceiling. zkao billing balance shows the credits available to the project.
Wait for it to finish.
Terminal window
```
zkao scans wait <scanId>
```
The scan moves from QUEUED to PROCESSING to COMPLETED. Scans take minutes. wait polls at the pace the server asks for, so you do not need your own loop.
Read the findings.
Terminal window
```
zkao findings list --scan <scanId>
zkao findings get <findingId>
```
get returns the full finding, including the description, proof of concept, and recommended fix.

Every command prints JSON on stdout, so it pipes cleanly into jq or a script. zkao --help lists every command.

Launch without the CLI

The same launch over plain HTTP or the TypeScript SDK:

curl
TypeScript

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

import { ZkaoClient } from "@zksecurity/zkao-sdk";

const zkao = new ZkaoClient({
  token: process.env.ZKAO_API_TOKEN!,
  projectId: process.env.ZKAO_PROJECT_ID!,
});

const { scanId } = await zkao.launchScan({ repositoryId: "<repoId>", presetRef: "<ref>" });
await zkao.waitForScan(scanId);
const { items } = await zkao.listFindings({ scanId });

Next steps

Scans covers presets, budgets, branches, areas, and per-scan guidance.
Triage findings covers severity, resolution, and notes.
CLI reference lists every command and flag.