@zksecurity/zkao-cli 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zkSecurity
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,30 @@
+# @zksecurity/zkao-cli
+
+Command-line interface for the [zkao](https://zkao.io) Project API. Launch and
+poll scans, read and triage findings, and publish results from your terminal or
+CI. Installs a `zkao` command.
+
+```bash
+npm install -g @zksecurity/zkao-cli
+# or run without installing:
+npx @zksecurity/zkao-cli --help
+```
+
+```bash
+zkao login                                  # browser approval; saves credentials
+zkao repos
+zkao scans launch --repo <repoId> --budget 500 --preset <ref>
+zkao scans wait <scanId>                    # block until the scan finishes
+zkao scans cancel <scanId>                  # cancel a running or queued scan
+zkao findings list --scan <scanId>
+```
+
+All output is JSON. `zkao --help` lists every command. Credentials come from
+`zkao login`, `zkao config set`, or the `ZKAO_API_TOKEN` / `ZKAO_PROJECT_ID`
+environment variables. Point at another environment with `ZKAO_URL`.
+
+Full docs and the SDK (`@zksecurity/zkao-sdk`): **https://github.com/zksecurity/zkao-sdk**
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,594 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { readFileSync as readFileSync3 } from "fs";
+import { createRequire } from "module";
+import { Command } from "commander";
+import {
+  ZkaoApiError,
+  ZkaoClient
+} from "@zksecurity/zkao-sdk";
+
+// src/config.ts
+import {
+  chmodSync,
+  mkdirSync,
+  readFileSync,
+  unlinkSync,
+  writeFileSync
+} from "fs";
+import { homedir } from "os";
+import { dirname, join } from "path";
+import { resolveBaseUrlFromEnv } from "@zksecurity/zkao-sdk";
+var CONFIG_PATH = join(homedir(), ".zkao", "config.json");
+function readFile() {
+  let raw;
+  try {
+    raw = readFileSync(CONFIG_PATH, "utf8");
+  } catch (err) {
+    if (err.code === "ENOENT") {
+      return {};
+    }
+    throw err;
+  }
+  try {
+    return JSON.parse(raw);
+  } catch (err) {
+    throw new Error(
+      `Could not parse ${CONFIG_PATH}: ${err.message}. Fix or delete the file, or overwrite it with \`zkao config set\`.`
+    );
+  }
+}
+function writeConfig(update) {
+  let existing;
+  try {
+    existing = readFile();
+  } catch {
+    console.error(`zkao: replacing unparseable config at ${CONFIG_PATH}`);
+    existing = {};
+  }
+  const merged = { ...existing, ...stripUndefined(update) };
+  writeSecretFile(CONFIG_PATH, `${JSON.stringify(merged, null, 2)}
+`);
+  return merged;
+}
+function writeSecretFile(path, contents) {
+  mkdirSync(dirname(path), { recursive: true, mode: 448 });
+  writeFileSync(path, contents, { mode: 384 });
+  chmodSync(path, 384);
+}
+function configPath() {
+  return CONFIG_PATH;
+}
+function stripUndefined(obj) {
+  return Object.fromEntries(
+    Object.entries(obj).filter(([, v]) => v !== void 0)
+  );
+}
+function resolveConfig(flags) {
+  const file = readFile();
+  return {
+    token: flags.token ?? process.env.ZKAO_API_TOKEN ?? file.token,
+    projectId: flags.projectId ?? process.env.ZKAO_PROJECT_ID ?? file.projectId,
+    baseUrl: flags.baseUrl ?? resolveBaseUrlFromEnv() ?? file.baseUrl
+  };
+}
+var PENDING_PATH = join(homedir(), ".zkao", "pending-login.json");
+function writePendingLogin(pending) {
+  writeSecretFile(PENDING_PATH, `${JSON.stringify(pending, null, 2)}
+`);
+}
+function readPendingLogin() {
+  let raw;
+  try {
+    raw = readFileSync(PENDING_PATH, "utf8");
+  } catch (err) {
+    if (err.code === "ENOENT") {
+      return null;
+    }
+    throw err;
+  }
+  try {
+    return JSON.parse(raw);
+  } catch {
+    console.error(
+      `zkao: ignoring unparseable pending login at ${PENDING_PATH}`
+    );
+    return null;
+  }
+}
+function clearPendingLogin() {
+  try {
+    unlinkSync(PENDING_PATH);
+  } catch (err) {
+    if (err.code !== "ENOENT") {
+      throw err;
+    }
+  }
+}
+
+// src/login.ts
+import { spawn } from "child_process";
+import { hostname } from "os";
+import { DEFAULT_BASE_URL } from "@zksecurity/zkao-sdk";
+function appOrigin(baseUrl) {
+  const url = new URL(baseUrl);
+  const prefix = url.pathname.replace(/\/+$/, "").replace(/\/api\/v\d+$/, "");
+  return `${url.origin}${prefix}`;
+}
+function openBrowser(url) {
+  const command = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
+  const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+  try {
+    const child = spawn(command, args, { stdio: "ignore", detached: true });
+    child.on("error", () => {
+    });
+    child.unref();
+  } catch {
+  }
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function postJson(url, body) {
+  const res = await fetch(url, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(body)
+  });
+  if (!res.ok) {
+    let detail = res.statusText;
+    try {
+      const data = await res.json();
+      detail = data.error?.message ?? detail;
+    } catch {
+    }
+    throw new Error(`Device authorization failed (${res.status}): ${detail}`);
+  }
+  return await res.json();
+}
+function printInstructions(start) {
+  console.log("\nTo authorize this CLI, open this URL and approve:\n");
+  console.log(`  ${start.verificationUriComplete}`);
+  console.log(
+    `
+Confirm the page shows this code:  ${start.userCode}
+Approve only if you started this login.
+`
+  );
+}
+function persistCredentials(poll, baseUrl) {
+  const saved = writeConfig({
+    token: poll.token,
+    projectId: poll.projectId,
+    baseUrl
+  });
+  clearPendingLogin();
+  console.log("Authorized. Credentials saved.\n");
+  console.log(`  project: ${saved.projectId}`);
+}
+async function login(flags) {
+  const cfg = resolveConfig({
+    token: flags.token,
+    projectId: flags.project,
+    baseUrl: flags.baseUrl
+  });
+  const apiBase = cfg.baseUrl ?? DEFAULT_BASE_URL;
+  const origin = appOrigin(apiBase);
+  const start = await postJson(`${origin}/api/auth/device`, {
+    label: hostname()
+  });
+  printInstructions(start);
+  if (!flags.noBrowser) {
+    openBrowser(start.verificationUriComplete);
+  }
+  writePendingLogin({
+    deviceCode: start.deviceCode,
+    origin,
+    interval: Math.max(1, start.interval),
+    expiresAtMs: Date.now() + start.expiresIn * 1e3,
+    baseUrl: cfg.baseUrl
+  });
+  if (flags.wait === false) {
+    console.log(
+      "Once you approve in the browser, run `zkao login --resume` to finish.\n"
+    );
+    return;
+  }
+  await pollUntilDone({
+    origin,
+    deviceCode: start.deviceCode,
+    intervalMs: Math.max(1, start.interval) * 1e3,
+    deadlineMs: Date.now() + start.expiresIn * 1e3,
+    baseUrl: cfg.baseUrl
+  });
+}
+async function resumeLogin(flags) {
+  const pending = readPendingLogin();
+  if (!pending) {
+    throw new Error(
+      "No pending login. Run `zkao login --no-wait` to start one first."
+    );
+  }
+  if (Date.now() >= pending.expiresAtMs) {
+    clearPendingLogin();
+    throw new Error("The login request expired. Run `zkao login` again.");
+  }
+  const waitMs = (flags.timeout ?? 0) * 1e3;
+  await pollUntilDone({
+    origin: pending.origin,
+    deviceCode: pending.deviceCode,
+    intervalMs: Math.max(1, pending.interval) * 1e3,
+    deadlineMs: Math.min(pending.expiresAtMs, Date.now() + waitMs),
+    baseUrl: pending.baseUrl,
+    reportStillPending: true
+  });
+}
+async function pollUntilDone(opts) {
+  let intervalMs = opts.intervalMs;
+  let polled = false;
+  for (; ; ) {
+    if (polled) {
+      const remaining = opts.deadlineMs - Date.now();
+      if (remaining <= 0) {
+        break;
+      }
+      await sleep(Math.min(intervalMs, remaining));
+    }
+    polled = true;
+    const poll = await postJson(
+      `${opts.origin}/api/auth/device/token`,
+      { deviceCode: opts.deviceCode }
+    );
+    switch (poll.status) {
+      case "pending":
+      case "slow_down":
+        if (poll.status === "slow_down") {
+          intervalMs += 2e3;
+        }
+        break;
+      case "denied":
+        clearPendingLogin();
+        throw new Error("Authorization was denied in the browser.");
+      case "expired":
+        clearPendingLogin();
+        throw new Error("The login request expired. Run `zkao login` again.");
+      case "approved":
+        persistCredentials(poll, opts.baseUrl);
+        return;
+      default: {
+        const _exhaustive = poll;
+        throw new Error(
+          `Unexpected device status: ${JSON.stringify(_exhaustive)}`
+        );
+      }
+    }
+  }
+  if (opts.reportStillPending) {
+    console.log(
+      "Still waiting for approval. Approve in the browser, then run `zkao login --resume` again."
+    );
+    return;
+  }
+  throw new Error("The login request expired. Run `zkao login` again.");
+}
+
+// src/update-check.ts
+import { mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "fs";
+import { dirname as dirname2, join as join2 } from "path";
+var CACHE_PATH = join2(dirname2(configPath()), "update-check.json");
+var CHECK_INTERVAL_MS = 24 * 60 * 60 * 1e3;
+var REGISTRY_TIMEOUT_MS = 1500;
+var PACKAGE = "@zksecurity/zkao-cli";
+function debug(message, err) {
+  if (process.env.ZKAO_DEBUG) {
+    console.error(`zkao: ${message}: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+function disabled() {
+  return Boolean(process.env.ZKAO_NO_UPDATE_CHECK);
+}
+function readCache() {
+  let raw;
+  try {
+    raw = readFileSync2(CACHE_PATH, "utf8");
+  } catch (err) {
+    if (err.code !== "ENOENT") {
+      debug("could not read the update cache", err);
+    }
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    return typeof parsed.latest === "string" && typeof parsed.checkedAtMs === "number" ? parsed : null;
+  } catch (err) {
+    debug("ignoring an unparseable update cache", err);
+    return null;
+  }
+}
+function writeCache(cache) {
+  try {
+    mkdirSync2(dirname2(CACHE_PATH), { recursive: true, mode: 448 });
+    writeFileSync2(CACHE_PATH, `${JSON.stringify(cache)}
+`);
+  } catch (err) {
+    debug("could not write the update cache", err);
+  }
+}
+function isNewerVersion(latest, current) {
+  const parse = (v) => {
+    const match = /^(\d+)\.(\d+)\.(\d+)$/.exec(v.trim());
+    return match ? [Number(match[1]), Number(match[2]), Number(match[3])] : null;
+  };
+  const a = parse(latest);
+  const b = parse(current);
+  if (!(a && b)) {
+    return false;
+  }
+  const [aMajor, aMinor, aPatch] = a;
+  const [bMajor, bMinor, bPatch] = b;
+  if (aMajor !== bMajor) {
+    return aMajor > bMajor;
+  }
+  if (aMinor !== bMinor) {
+    return aMinor > bMinor;
+  }
+  return aPatch > bPatch;
+}
+function printUpdateNotice(currentVersion) {
+  if (disabled()) {
+    return;
+  }
+  const cache = readCache();
+  if (!(cache && isNewerVersion(cache.latest, currentVersion))) {
+    return;
+  }
+  console.error(
+    `zkao: version ${cache.latest} is available (running ${currentVersion}). Update with \`npm install -g ${PACKAGE}\`. If you are an agent working from a zkao skill file, update that too: it may describe fewer commands than the API now offers.`
+  );
+}
+async function refreshUpdateCache() {
+  if (disabled()) {
+    return;
+  }
+  const cache = readCache();
+  if (cache && Date.now() - cache.checkedAtMs < CHECK_INTERVAL_MS) {
+    return;
+  }
+  const keepPrevious = () => writeCache({ checkedAtMs: Date.now(), latest: cache?.latest ?? "" });
+  try {
+    const res = await fetch(`https://registry.npmjs.org/${PACKAGE}/latest`, {
+      headers: { accept: "application/json" },
+      signal: AbortSignal.timeout(REGISTRY_TIMEOUT_MS)
+    });
+    if (!res.ok) {
+      debug("registry rejected the version lookup", new Error(`HTTP ${res.status}`));
+      keepPrevious();
+      return;
+    }
+    const body = await res.json();
+    if (typeof body.version !== "string") {
+      debug("registry returned no version", new Error("missing `version`"));
+      keepPrevious();
+      return;
+    }
+    writeCache({ checkedAtMs: Date.now(), latest: body.version });
+  } catch (err) {
+    debug("could not reach the npm registry", err);
+    keepPrevious();
+  }
+}
+
+// src/index.ts
+var { version } = createRequire(import.meta.url)("../package.json");
+var program = new Command();
+program.name("zkao").description("Control a zkao project from the command line.").version(version).option("--token <token>", "project API token (or env ZKAO_API_TOKEN)").option("--project <id>", "project id (or env ZKAO_PROJECT_ID)").option("--base-url <url>", "API base URL, used verbatim (env: ZKAO_URL sets the environment)");
+function out(data) {
+  console.log(JSON.stringify(data, null, 2));
+}
+function fail(message) {
+  console.error(message);
+  process.exit(1);
+}
+function client() {
+  const g = program.opts();
+  const cfg = resolveConfig({ token: g.token, projectId: g.project, baseUrl: g.baseUrl });
+  if (!cfg.token) {
+    fail("No API token. Pass --token, set ZKAO_API_TOKEN, or run `zkao config set --token <token>`.");
+  }
+  if (!cfg.projectId) {
+    fail("No project id. Pass --project, set ZKAO_PROJECT_ID, or run `zkao config set --project <id>`.");
+  }
+  return new ZkaoClient({ token: cfg.token, projectId: cfg.projectId, baseUrl: cfg.baseUrl });
+}
+async function run(fn) {
+  try {
+    out(await fn(client()));
+  } catch (err) {
+    if (err instanceof ZkaoApiError) {
+      fail(`Error ${err.status} (${err.code}): ${err.message}`);
+    }
+    throw err;
+  }
+}
+function readContentArg(source) {
+  try {
+    return readFileSync3(source === "-" ? 0 : source, "utf8");
+  } catch (err) {
+    fail(
+      `Could not read ${source === "-" ? "stdin" : `"${source}"`}: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+}
+var collect = (value, prev) => [...prev, value];
+var toInt = (value) => {
+  const n = Number.parseInt(value, 10);
+  if (!Number.isInteger(n)) {
+    fail(`Expected an integer, got "${value}"`);
+  }
+  return n;
+};
+program.command("login").description(
+  "Authorize this CLI by approving it in your browser (device flow)"
+).option("--no-browser", "print the URL instead of opening a browser").option(
+  "--no-wait",
+  "start the flow, print the URL/code, and exit; finish with --resume"
+).option("--resume", "poll a login previously started with --no-wait").option(
+  "--timeout <seconds>",
+  "with --resume, wait up to this long for approval (default: poll once)",
+  toInt
+).action(
+  async (opts) => {
+    if (opts.resume) {
+      await resumeLogin({ timeout: opts.timeout });
+      return;
+    }
+    const g = program.opts();
+    await login({
+      token: g.token,
+      project: g.project,
+      baseUrl: g.baseUrl,
+      noBrowser: opts.browser === false,
+      wait: opts.wait !== false
+    });
+  }
+);
+var config = program.command("config").description("Manage stored credentials");
+config.command("set").description(`Persist settings to ${configPath()}`).option("--token <token>", "project API token").option("--project <id>", "project id").option("--base-url <url>", "API base URL").action((opts) => {
+  const g = program.opts();
+  const update = {
+    token: opts.token ?? g.token,
+    projectId: opts.project ?? g.project,
+    baseUrl: opts.baseUrl ?? g.baseUrl
+  };
+  if (update.token === void 0 && update.projectId === void 0 && update.baseUrl === void 0) {
+    fail("Nothing to save. Pass --token, --project, or --base-url.");
+  }
+  writeConfig(update);
+  console.log(`Saved to ${configPath()}`);
+});
+config.command("show").description("Show the resolved settings (token masked)").action(() => {
+  const cfg = resolveConfig({});
+  out({
+    token: cfg.token ? `${cfg.token.slice(0, 14)}\u2026` : null,
+    projectId: cfg.projectId ?? null,
+    baseUrl: cfg.baseUrl ?? "https://zkao.io/api/v1 (default)"
+  });
+});
+program.command("repos").description("List repositories in the project").action(() => run((c) => c.listRepositories()));
+var guidance = program.command("guidance").description("Read and update a repository's guidance");
+guidance.command("get <repoId>").description("Show a repository's configured guidance").action((repoId) => run((c) => c.getRepositoryGuidance(repoId)));
+guidance.command("set <repoId> <file|->").description("Set a repository's guidance from a file (or - for stdin)").option(
+  "--force",
+  "overwrite without the safety check that guidance did not change since last read"
+).action((repoId, source, opts) => {
+  const content = readContentArg(source);
+  return run(async (c) => {
+    if (opts.force) {
+      return c.setRepositoryGuidance(repoId, content);
+    }
+    const current = await c.getRepositoryGuidance(repoId);
+    return c.setRepositoryGuidance(repoId, content, {
+      expectedContent: current.content
+    });
+  });
+});
+guidance.command("clear <repoId>").description("Remove a repository's guidance").option("--force", "overwrite without the concurrent-change safety check").action(
+  (repoId, opts) => run(async (c) => {
+    if (opts.force) {
+      return c.setRepositoryGuidance(repoId, null);
+    }
+    const current = await c.getRepositoryGuidance(repoId);
+    return c.setRepositoryGuidance(repoId, null, {
+      expectedContent: current.content
+    });
+  })
+);
+var scans = program.command("scans").description("Launch, list, and poll scans");
+scans.command("list").option("--page <n>", "page number", toInt).option("--limit <n>", "page size (max 100)", toInt).action(
+  (opts) => run((c) => c.listScans({ page: opts.page, limit: opts.limit }))
+);
+scans.command("get <scanId>").description("Get a scan's status and detail").action((scanId) => run((c) => c.getScan(scanId)));
+scans.command("wait <scanId>").description("Poll a scan until it finishes (honors server backoff)").option("--timeout <seconds>", "give up after this long", toInt).action((scanId, opts) => {
+  const controller = new AbortController();
+  const onSigint = () => controller.abort(new Error("Interrupted"));
+  process.once("SIGINT", onSigint);
+  return run(
+    (c) => c.waitForScan(scanId, {
+      timeoutMs: opts.timeout ? opts.timeout * 1e3 : void 0,
+      signal: controller.signal,
+      onPoll: (scan) => console.error(`  scan ${scan.id}: ${scan.status}`)
+    }).finally(() => process.removeListener("SIGINT", onSigint))
+  );
+});
+scans.command("launch").description("Launch a scan").requiredOption("--repo <id>", "repository id").requiredOption("--budget <credits>", "max budget, in credits", toInt).option("--preset <ref>", "scan preset ref (see `zkao presets`)").option("--branch <name>", "branch to scan").option("--commit <sha>", "specific commit to scan").option("--message <text>", "commit message (metadata)").option("--flow <id>", "optional-flow id to opt into (repeatable)", collect, []).option(
+  "--guidance <file|->",
+  "per-scan guidance from a file (or - for stdin); replaces the repo's guidance for this scan"
+).action(
+  (opts) => {
+    const body = {
+      repositoryId: opts.repo,
+      creditBudget: opts.budget,
+      presetRef: opts.preset,
+      branch: opts.branch ?? null,
+      commitHash: opts.commit ?? null,
+      commitMessage: opts.message ?? null,
+      optInFlowIds: opts.flow.length > 0 ? opts.flow : void 0,
+      ...opts.guidance !== void 0 ? { guidance: readContentArg(opts.guidance) } : {}
+    };
+    return run((c) => c.launchScan(body));
+  }
+);
+scans.command("cancel <scanId>").description("Cancel a running or queued scan").action((scanId) => run((c) => c.cancelScan(scanId)));
+scans.command("publish <scanId>").description("Publish a completed scan as a public artifact").option("--password", "generate an access password").action(
+  (scanId, opts) => run((c) => c.publishScan(scanId, { withPassword: opts.password }))
+);
+var findings = program.command("findings").description("Read and triage findings");
+findings.command("list").option("--scan <id>", "only findings for this scan").option("--page <n>", "page number", toInt).option("--limit <n>", "page size (max 100)", toInt).action(
+  (opts) => run((c) => c.listFindings({ scanId: opts.scan, page: opts.page, limit: opts.limit }))
+);
+findings.command("get <findingId>").description("Get a finding's full detail").action((findingId) => run((c) => c.getFinding(findingId)));
+findings.command("comment <findingId> <text>").description("Add a comment to a finding").action((findingId, text) => run((c) => c.addFindingNote(findingId, text)));
+findings.command("severity <findingId> <level>").description("Override severity (CRITICAL|HIGH|MEDIUM|LOW|INFO, or 'none' to clear)").action((findingId, level) => {
+  const value = level.toLowerCase() === "none" ? null : level.toUpperCase();
+  return run((c) => c.setFindingSeverity(findingId, value));
+});
+findings.command("resolution <findingId> <status>").description("Set resolution status (e.g. RESOLVED, WONT_FIX, FALSE_POSITIVE)").option("--note <text>", "record the why as a comment in the same call").option(
+  "--reason <code>",
+  "record the why as a catalog code instead (codes depend on the status; a wrong one is rejected with the valid list)"
+).action(
+  (findingId, status, opts) => run(
+    (c) => c.setFindingResolution(findingId, status.toUpperCase(), {
+      note: opts.note ? { content: opts.note } : void 0,
+      reason: opts.reason
+    })
+  )
+);
+findings.command("publish <findingId>").description("Publish a finding as a public artifact").option("--note <noteId>", "note to pin as the published note").option("--password", "generate an access password").action(
+  (findingId, opts) => run((c) => c.publishFinding(findingId, { noteId: opts.note, withPassword: opts.password }))
+);
+var billing = program.command("billing").description("Read the project's credit balance and usage");
+billing.command("balance").description("Credit balance, what active scans hold, and what is available").action(() => run((c) => c.getBillingBalance()));
+billing.command("usage").description("Credit ledger movements (defaults to the last 30 days)").option("--from <date>", "ISO date or timestamp to start from").option("--to <date>", "ISO date or timestamp to stop at").option("--limit <n>", "max events to return", toInt).action(
+  (opts) => run((c) => c.getBillingUsage(opts))
+);
+billing.command("summary").description("Per-month credits spent and purchased, newest first").option("--months <n>", "how many months to return", toInt).action(
+  (opts) => run((c) => c.getBillingSummary({ months: opts.months }))
+);
+program.command("presets").description("List scan presets the project can launch").action(() => run((c) => c.listScanPresets()));
+program.command("flows").description("List opt-in flows available at launch").action(() => run((c) => c.listOptionalFlows()));
+function errorMessage(err) {
+  if (err instanceof AggregateError && err.errors.length > 0) {
+    return err.errors.map(errorMessage).join("; ");
+  }
+  if (!(err instanceof Error)) {
+    return String(err);
+  }
+  const message = err.message || String(err);
+  return err.cause ? `${message}: ${errorMessage(err.cause)}` : message;
+}
+printUpdateNotice(version);
+program.parseAsync().then(() => refreshUpdateCache()).catch((err) => {
+  console.error(errorMessage(err));
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@zksecurity/zkao-cli",
+  "version": "0.2.0",
+  "description": "Command-line interface for the zkao Project API",
+  "license": "MIT",
+  "author": "zkSecurity",
+  "homepage": "https://github.com/zksecurity/zkao-sdk#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zksecurity/zkao-sdk.git",
+    "directory": "packages/cli"
+  },
+  "bugs": "https://github.com/zksecurity/zkao-sdk/issues",
+  "keywords": [
+    "zkao",
+    "security",
+    "audit",
+    "cli",
+    "scanner"
+  ],
+  "type": "module",
+  "bin": {
+    "zkao": "./dist/index.js"
+  },
+  "files": ["dist", "LICENSE", "README.md"],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "node -e \"if (!(process.env.npm_config_user_agent || '').includes('bun/')) { console.error('Publish with bun publish: npm ships the literal workspace:* dependency and breaks installs.'); process.exit(1); }\""
+  },
+  "dependencies": {
+    "@zksecurity/zkao-sdk": "0.2.0",
+    "commander": "^12.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsup": "^8.3.0",
+    "typescript": "^5.7.0"
+  }
+}