argorant 0.12.0 → 0.13.0

package/bin/argorant.js

@@ -181,6 +181,39 @@ function parseArgs(argv) {
   return out;
 }
 
+// ---- Idempotency-Key on every write to /api/v1 ----
+// A retried command must never do the work twice (a second export, a second
+// reply, a second charge). Every POST/PUT/PATCH/DELETE to /api/v1 carries a
+// key: a fresh random one by default, or the one given with
+// --idempotency-key. With an explicit key the first write of the command uses
+// it as given and later writes in the same command use <key>-2, <key>-3, so
+// running the same command again with the same key replays every step.
+const IDEM = { override: null, count: 0 };
+const IDEM_KEY_RE = /^[A-Za-z0-9._:-]{1,120}$/;
+function nextIdempotencyKey() {
+  IDEM.count += 1;
+  if (IDEM.override) return IDEM.count === 1 ? IDEM.override : `${IDEM.override}-${IDEM.count}`;
+  return crypto.randomUUID();
+}
+// Pull --idempotency-key out of argv before any parser sees it (every command
+// accepts it). Returns argv without the flag.
+function takeIdempotencyFlag(argv) {
+  const out = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    let v = null;
+    if (a === "--idempotency-key") { v = flagValue(argv, i, a); i += 1; }
+    else if (a.startsWith("--idempotency-key=")) v = a.slice("--idempotency-key=".length);
+    else { out.push(a); continue; }
+    if (!IDEM_KEY_RE.test(v)) die(`--idempotency-key may use letters, digits and . _ : - (1 to 120 characters), got "${v}".`);
+    IDEM.override = v;
+  }
+  return out;
+}
+function isV1Write(method, pathname) {
+  return !["GET", "HEAD", "OPTIONS"].includes(String(method).toUpperCase()) && /^\/api\/v1(\/|$)/.test(pathname);
+}
+
 // ---- HTTP ----
 function request(method, base, urlPath, { key, query, body, headers: extraHeaders } = {}) {
   return new Promise((resolve, reject) => {
@@ -198,47 +231,92 @@ function request(method, base, urlPath, { key, query, body, headers: extraHeader
     const payload = body ? Buffer.from(JSON.stringify(body)) : null;
     const headers = { Accept: "application/json", "User-Agent": `argorant-cli/${VERSION}`, ...(extraHeaders || {}) };
     if (key) headers["Authorization"] = `Bearer ${key}`;
+    // Lets the server's purchase audit say a purchase came from the command line.
+    if (/^\/api\/v1(\/|$)/.test(u.pathname)) headers["X-Argorant-Channel"] = "cli";
+    if (isV1Write(method, u.pathname)) {
+      const own = Object.keys(headers).find((h) => h.toLowerCase() === "idempotency-key");
+      if (!own || IDEM.override) {
+        if (own) delete headers[own];
+        headers["Idempotency-Key"] = nextIdempotencyKey();
+      }
+    }
     if (payload) {
       headers["Content-Type"] = "application/json";
       headers["Content-Length"] = payload.length;
     }
     const lib = u.protocol === "http:" ? http : https;
-    const req = lib.request(
-      u,
-      { method, headers },
-      (res) => {
-        const chunks = [];
-        res.on("data", (d) => chunks.push(d));
-        res.on("end", () => {
-          const raw = Buffer.concat(chunks).toString("utf8");
-          let json = null;
-          try {
-            json = raw ? JSON.parse(raw) : null;
-          } catch {
-            /* non-JSON (e.g. CSV download) */
-          }
-          resolve({ status: res.statusCode, json, raw, res });
-        });
-      }
-    );
-    req.on("error", reject);
-    if (payload) req.write(payload);
-    req.end();
+    // The per-minute request limit: wait for the time the server names and send
+    // the SAME request again (same Idempotency-Key, so a write never runs twice).
+    // Longer waits (a daily limit) are not waited out; they surface as exit 4.
+    const send = (attempt) => {
+      const req = lib.request(
+        u,
+        { method, headers },
+        (res) => {
+          const chunks = [];
+          res.on("data", (d) => chunks.push(d));
+          res.on("end", () => {
+            const raw = Buffer.concat(chunks).toString("utf8");
+            let json = null;
+            try {
+              json = raw ? JSON.parse(raw) : null;
+            } catch {
+              /* non-JSON (e.g. CSV download) */
+            }
+            const wait = res.statusCode === 429 ? retryWaitSeconds(res.headers["retry-after"], attempt) : null;
+            if (wait !== null) {
+              warn(`too many requests this minute; waiting ${wait} second${wait === 1 ? "" : "s"}, then trying again.`);
+              setTimeout(() => send(attempt + 1), wait * 1000);
+              return;
+            }
+            resolve({ status: res.statusCode, json, raw, res });
+          });
+        }
+      );
+      req.on("error", reject);
+      if (payload) req.write(payload);
+      req.end();
+    };
+    send(0);
   });
 }
 
+// How long to wait before trying a 429 again, or null to give up and report it.
+// At most RATE_RETRY.attempts tries, each wait at most RATE_RETRY.maxWait
+// seconds (ARGORANT_MAX_RETRY_WAIT; 0 switches the retry off).
+const RATE_RETRY = {
+  attempts: 3,
+  maxWait: (() => {
+    const v = Number(process.env.ARGORANT_MAX_RETRY_WAIT);
+    return Number.isFinite(v) && v >= 0 ? v : 65;
+  })(),
+};
+function retryWaitSeconds(header, attempt) {
+  if (attempt >= RATE_RETRY.attempts || RATE_RETRY.maxWait <= 0) return null;
+  const n = Math.ceil(Number(header));
+  if (!Number.isFinite(n) || n < 0 || n > RATE_RETRY.maxWait) return null;
+  return Math.max(1, n);
+}
+
 function downloadTo(base, urlPath, key, dest) {
   return new Promise((resolve, reject) => {
     const u = new URL(urlPath, base);
     const lib = u.protocol === "http:" ? http : https;
     const req = lib.request(
       u,
-      { method: "GET", headers: { Authorization: `Bearer ${key}`, "User-Agent": `argorant-cli/${VERSION}` } },
+      { method: "GET", headers: { Authorization: `Bearer ${key}`, "User-Agent": `argorant-cli/${VERSION}`, ...(/^\/api\/v1(\/|$)/.test(u.pathname) ? { "X-Argorant-Channel": "cli" } : {}) } },
       (res) => {
         if (res.statusCode !== 200) {
           const chunks = [];
           res.on("data", (d) => chunks.push(d));
-          res.on("end", () => reject(new Error(`download failed (HTTP ${res.statusCode}): ${Buffer.concat(chunks).toString("utf8").slice(0, 300)}`)));
+          res.on("end", () => {
+            const raw = Buffer.concat(chunks).toString("utf8");
+            let json = null;
+            try { json = raw ? JSON.parse(raw) : null; } catch { /* plain text */ }
+            const msg = errorMessage(json) || raw.slice(0, 300);
+            const rid = requestIdOf({ res, json });
+            reject(new Error(`download failed (HTTP ${res.statusCode}): ${msg}${rid ? ` (request id ${rid})` : ""}`));
+          });
           return;
         }
         const file = fs.createWriteStream(dest);
@@ -279,26 +357,82 @@ function detailMsg(detail) {
   }
   return JSON.stringify(detail);
 }
+// Errors from /api/v1 come as one envelope:
+//   {"error": {"code", "message", "details"}, "request_id": "req_...", "detail": <old value>}
+// Older endpoints answer {"detail": ...} or a bare {"error": "<code>", "message"}.
+// errorMessage() reads all three; the envelope wins when present.
+function errorMessage(json) {
+  if (!json || typeof json !== "object" || Array.isArray(json)) return null;
+  const e = json.error;
+  if (e && typeof e === "object" && !Array.isArray(e)) {
+    let msg = e.message ? String(e.message) : e.code ? String(e.code).replace(/_/g, " ") : null;
+    const d = e.details && typeof e.details === "object" ? e.details : {};
+    const blockers = Array.isArray(d.blockers) ? d.blockers : [];
+    if (blockers.length) {
+      msg = (msg || "blocked") + "\n" + blockers.map((b) => `  · ${typeof b === "string" ? b : b && (b.message || b.label) ? b.message || b.label : JSON.stringify(b)}`).join("\n");
+    }
+    const fields = Array.isArray(d.fields) ? d.fields : [];
+    if (fields.length && !blockers.length) {
+      const named = fields
+        .map((f) => (typeof f === "string" ? f : f && (f.field || f.name) ? `${f.field || f.name}${f.message ? `: ${f.message}` : ""}` : null))
+        .filter(Boolean);
+      if (named.length && !(msg || "").includes(named[0])) msg = `${msg || "invalid request"} (${named.join("; ")})`;
+    }
+    if (msg) return msg;
+  }
+  if (typeof e === "string" && json.message) return String(json.message);
+  return detailMsg(json.detail) || (typeof e === "string" ? e.replace(/_/g, " ") : null);
+}
+function errorCode(json) {
+  if (!json || typeof json !== "object" || Array.isArray(json)) return null;
+  const e = json.error;
+  if (e && typeof e === "object" && !Array.isArray(e)) return e.code ? String(e.code) : null;
+  if (typeof e === "string") return e;
+  const d = json.detail;
+  if (d && typeof d === "object" && !Array.isArray(d)) return d.error || d.code || null;
+  return null;
+}
+// The id the server gave this request (header X-Request-Id, or request_id in
+// the error body). Printed with every error so a user can quote it to support.
+function requestIdOf(res) {
+  const h = res && res.res && res.res.headers;
+  const fromHeader = h && (h["x-request-id"] || h["X-Request-Id"]);
+  return String(fromHeader || (res && res.json && typeof res.json === "object" && res.json.request_id) || "") || null;
+}
+
 // Exit codes are part of the CLI's contract with agents/CI:
 //   0 ok · 1 generic failure · 2 not authenticated · 3 forbidden (scope)
 //   4 rate limit / daily quota · 5 plan upgrade required (402)
 const EXIT = { OK: 0, ERROR: 1, AUTH: 2, FORBIDDEN: 3, RATE_LIMIT: 4, UPGRADE: 5 };
 
 function need(res, what) {
+  if (res.status < 400) return res.json || {};
   const detail = res.json && res.json.detail;
-  if (res.status === 401) die("not authenticated. Run `argorant login` or set ARGORANT_API_KEY.", EXIT.AUTH);
+  const msg = errorMessage(res.json);
+  const code = errorCode(res.json);
+  const rid = requestIdOf(res);
+  const ref = rid ? `\nRequest id: ${rid} (quote it if you contact support)` : "";
+  if (res.status === 401) {
+    const lead = code && code !== "unauthorized" && msg ? `${msg}\n` : "";
+    die(`${lead}not authenticated. Run \`argorant login\` or set ARGORANT_API_KEY.${ref}`, EXIT.AUTH);
+  }
   if (res.status === 402) {
     // Distinct from a hard error: nothing is broken, the plan just doesn't
     // include this. Agents branch on exit 5 to surface an upgrade, not a bug.
     const d = detail && typeof detail === "object" && !Array.isArray(detail) ? detail : {};
-    const msg = detailMsg(detail) || `${what} requires a paid Argorant plan.`;
-    const url = d.upgrade_url || d.url || "https://argorant.com/pricing";
-    die(`${msg}${msg.includes(url) ? "" : `\nUpgrade: ${url}`}`, EXIT.UPGRADE);
+    const details = res.json && res.json.error && typeof res.json.error === "object" ? res.json.error.details || {} : {};
+    const text = msg || `${what} requires a paid Argorant plan.`;
+    const url = details.upgrade_url || d.upgrade_url || d.url || "https://argorant.com/pricing";
+    die(`${text}${text.includes(url) ? "" : `\nUpgrade: ${url}`}${ref}`, EXIT.UPGRADE);
+  }
+  if (res.status === 403) die(`${msg || `forbidden - your key lacks the scope for ${what}.`}${ref}`, EXIT.FORBIDDEN);
+  if (res.status === 429) {
+    const h = res.res && res.res.headers;
+    const ra = Number((h && h["retry-after"]) || 0);
+    const wait = Number.isFinite(ra) && ra > 0 ? ` Try again in ${ra === 1 ? "1 second" : fmtWait(Math.ceil(ra))}.` : "";
+    die(`${msg || "too many requests right now, or today's limit is used up."}${wait}${ref}`, EXIT.RATE_LIMIT);
   }
-  if (res.status === 403) die(detailMsg(detail) || `forbidden - your key lacks the scope for ${what}.`, EXIT.FORBIDDEN);
-  if (res.status === 429) die(detailMsg(detail) || "rate limit / daily quota reached.", EXIT.RATE_LIMIT);
-  if (res.status >= 400) die(detailMsg(detail) || `${what} failed (HTTP ${res.status}).`);
-  return res.json || {};
+  die(`${msg || `${what} failed (HTTP ${res.status}).`}${ref}`);
 }
 
 // A paid job must never die on a path problem AFTER it was billed: check the
@@ -598,11 +732,12 @@ async function addPhones(args, key, records) {
   });
   if (res.status !== 200 || !res.json) {
     const detail = res.json && res.json.detail;
-    const code = detail && typeof detail === "object" ? detail.error : null;
-    let message = detailMsg(detail) || `phone numbers failed (HTTP ${res.status}).`;
+    // The error envelope's stable code first, then the older detail.error (servers before the envelope).
+    const code = errorCode(res.json);
+    let message = errorMessage(res.json) || detailMsg(detail) || `phone numbers failed (HTTP ${res.status}).`;
     if (code === "phones_not_in_plan") message = "Your plan does not include phone numbers, so none were added and nothing was charged for them.";
     else if (code === "insufficient_credits") message = "Not enough credits for a phone number, so none were added and nothing was charged for them.";
-    else if (code === "mcp_quota_exceeded") message = "Today's reveal limit is used up, so no phone numbers were added. It resets at midnight UTC.";
+    else if (code === "mcp_quota_exceeded" || code === "daily_limit_reached") message = "Today's reveal limit is used up, so no phone numbers were added. It resets at midnight UTC.";
     for (const r of records) r.phone_status = "not_added";
     return { included: false, status: res.status, error: code || "error", message, summary: message };
   }
@@ -818,7 +953,20 @@ async function pollExportBatch(args, key, statusPath, { quiet = false } = {}) {
   }
 }
 
-async function downloadBatchChunks(args, key, batch, dest) {
+// Paths of the export endpoints. `export` keeps the paths it always used;
+// `exports` (0.13.0) uses the same operations under /api/v1.
+const EXPORT_API_MCP = {
+  job: (id) => `/api/mcp/exports/${id}`,
+  batch: (id) => `/api/mcp/export-batches/${id}`,
+  download: (id) => `/api/mcp/exports/${id}/download`,
+};
+const EXPORT_API_V1 = {
+  job: (id) => `/api/v1/exports/${id}`,
+  batch: (id) => `/api/v1/export-batches/${id}`,
+  download: (id) => `/api/v1/exports/${id}/download`,
+};
+
+async function downloadBatchChunks(args, key, batch, dest, api = EXPORT_API_MCP) {
   const chunks = (batch.chunks || []).filter((c) => c.downloadable || EXPORT_TERMINAL_OK.includes(String(c.status || "").toLowerCase()));
   if (!chunks.length) die("export batch reported done but returned no downloadable chunks.");
   const files = [];
@@ -826,7 +974,7 @@ async function downloadBatchChunks(args, key, batch, dest) {
   for (const chunk of chunks) {
     i += 1;
     const target = chunks.length === 1 ? dest : partPath(dest, chunk.chunk_index != null ? chunk.chunk_index + 1 : i);
-    const dl = chunk.download_api_path || `/api/mcp/exports/${chunk.job_id}/download`;
+    const dl = chunk.download_url || chunk.download_api_path || api.download(chunk.job_id);
     await downloadTo(args.base, dl, key, target);
     files.push(target);
   }
@@ -844,9 +992,9 @@ function countCsvRows(file) {
 // `argorant export status <id>` / `argorant export download <id> -o file`:
 // a paid export must never be unrecoverable because the CLI died after the
 // job was created (bad path, ctrl-c, dropped connection).
-async function exportStatusCmd(args, key, id) {
+async function exportStatusCmd(args, key, id, api = EXPORT_API_MCP, cmdName = "export") {
   const isBatch = args.batch;
-  const p = isBatch ? `/api/mcp/export-batches/${id}` : `/api/mcp/exports/${id}`;
+  const p = isBatch ? api.batch(id) : api.job(id);
   const res = await request("GET", args.base, p, { key });
   const s = need(res, "export status");
   if (args.json) return console.log(JSON.stringify(s, null, 2));
@@ -858,28 +1006,31 @@ async function exportStatusCmd(args, key, id) {
     console.log(`  ${Number(s.verified_rows || 0).toLocaleString()}/${Number(s.total_rows || 0).toLocaleString()} rows · ${s.progress_pct || 0}%${s.downloadable ? green("  · ready to download") : ""}`);
   }
   if (s.error_message) console.log(red("  " + s.error_message));
-  if (s.downloadable) console.log(dim(`  argorant export download ${id}${isBatch ? " --batch" : ""} -o leads.csv`));
+  if (s.downloadable) console.log(dim(`  argorant ${cmdName} download ${id}${isBatch ? " --batch" : ""} -o leads.csv`));
 }
 
-async function exportDownloadCmd(args, key, id) {
+async function exportDownloadCmd(args, key, id, api = EXPORT_API_MCP, cmdName = "export") {
   const dest = ensureWritable(args.output || "argorant-leads.csv");
   if (args.batch) {
-    const res = await request("GET", args.base, `/api/mcp/export-batches/${id}`, { key });
+    const res = await request("GET", args.base, api.batch(id), { key });
     const b = need(res, "export batch status");
     if (!EXPORT_TERMINAL_OK.includes(String(b.status || "").toLowerCase())) {
-      die(`export batch #${id} is ${b.status || "not ready"} - run \`argorant export status ${id} --batch\`.`);
+      die(`export batch #${id} is ${b.status || "not ready"} - run \`argorant ${cmdName} status ${id} --batch\`.`);
     }
-    const files = await downloadBatchChunks(args, key, b, dest);
+    const files = await downloadBatchChunks(args, key, b, dest, api);
     if (args.json) return console.log(JSON.stringify({ ok: true, batch_id: id, files }, null, 2));
     for (const f of files) console.log(green("✓") + ` ${bold(String(countCsvRows(f) ?? "?"))} rows → ${bold(f)}`);
     return;
   }
-  const res = await request("GET", args.base, `/api/mcp/exports/${id}`, { key });
+  const res = await request("GET", args.base, api.job(id), { key });
   const s = need(res, "export status");
-  if (!s.downloadable && !s.download_api_path) {
-    die(`export #${id} is ${s.status || "not ready"} - run \`argorant export status ${id}\`.`);
+  if (!s.downloadable && !s.download_api_path && !s.download_url) {
+    if (EXPORT_TERMINAL_FAIL.includes(String(s.status || "").toLowerCase())) {
+      die(`export #${id} ${String(s.status).toLowerCase() === "failed" ? "failed" : `was ${s.status}`}, so there is no file to download. Start a new export, or check it with \`argorant ${cmdName} status ${id}\`.`);
+    }
+    die(`export #${id} is ${s.status || "not ready"} - run \`argorant ${cmdName} status ${id}\`.`);
   }
-  await downloadTo(args.base, s.download_api_path || `/api/mcp/exports/${id}/download`, key, dest);
+  await downloadTo(args.base, s.download_url || s.download_api_path || api.download(id), key, dest);
   if (args.json) return console.log(JSON.stringify({ ok: true, file: dest, job_id: id }, null, 2));
   const rows = countCsvRows(dest);
   console.log(green("✓") + ` Saved ${rows != null ? bold(rows.toLocaleString()) + " rows → " : ""}${bold(dest)}`);
@@ -1191,9 +1342,10 @@ function readStdin() {
   });
 }
 
+// Every campaign, a page at a time (the API pages its lists; an older server
+// answers one page without next_cursor and the loop stops there).
 async function fetchCampaigns(base, key) {
-  const res = await request("GET", base, "/api/v1/campaigns", { key, query: { limit: "500" } });
-  const r = need(res, "campaigns list");
+  const r = await fetchPages(base, key, "/api/v1/campaigns", { limit: 100 }, "campaigns", "campaigns list", true);
   return r.campaigns || [];
 }
 
@@ -1603,10 +1755,11 @@ async function campaignsDelete(argv) {
 }
 
 async function campaignsLeadsList(args, campaignId, key) {
-  const query = { limit: args.limit || 50, offset: args.offset || 0 };
+  const query = { offset: args.offset || 0 };
   if (args.status) query.status = args.status;
   if (args.q) query.q = args.q;
-  const r = need(await request("GET", args.base, `/api/v1/campaigns/${campaignId}/leads`, { key, query }), "campaigns leads");
+  const want = args.limit ? parseLimit(args.limit, "-n") : 50;
+  const r = await fetchUpTo(args.base, key, `/api/v1/campaigns/${campaignId}/leads`, query, "leads", "campaigns leads", want);
   if (args.json) return console.log(JSON.stringify(r, null, 2));
   console.log(dim(`${r.total} lead(s)`));
   for (const l of r.leads || []) console.log(`${l.email}  ${dim([l.first_name, l.last_name].filter(Boolean).join(" ") || "")}  ${l.status}${l.current_step ? dim(`  step ${l.current_step}`) : ""}${l.replied_at ? green("  replied") : ""}${l.bounced_at ? red("  bounced") : ""}`);
@@ -1626,7 +1779,8 @@ async function campaignsReplies(argv) {
   const identifier = args._[0];
   if (!identifier) die("usage: argorant campaigns replies <campaign> [-n 50]");
   const campaignId = await resolveCampaign(args.base, key, identifier);
-  const r = need(await request("GET", args.base, `/api/v1/campaigns/${campaignId}/replies`, { key, query: { limit: args.limit || 50 } }), "campaigns replies");
+  const want = args.limit ? parseLimit(args.limit, "-n") : 50;
+  const r = await fetchUpTo(args.base, key, `/api/v1/campaigns/${campaignId}/replies`, {}, "replies", "campaigns replies", want);
   if (args.json) return console.log(JSON.stringify(r, null, 2));
   if (!(r.replies || []).length) return console.log(dim("No replies yet."));
   for (const e of r.replies) {
@@ -1640,11 +1794,12 @@ async function cmdInboxThreads(argv) {
   const key = requireKey();
   if (sub === "list") {
     const args = readFlags(argv.slice(1), { "--folder": "folder", "--campaign": "campaign", "--classification": "classification", "--q": "q", "-n": "limit", "--limit": "limit" });
-    const query = { folder: args.folder || "replies", limit: args.limit || 50 };
+    const query = { folder: args.folder || "replies" };
     if (args.classification) query.classification = args.classification;
     if (args.q) query.q = args.q;
     if (args.campaign) query.campaign_id = await resolveCampaign(args.base, key, args.campaign);
-    const r = need(await request("GET", args.base, "/api/v1/inbox", { key, query }), "inbox");
+    const want = args.limit ? parseLimit(args.limit, "-n") : 50;
+    const r = await fetchUpTo(args.base, key, "/api/v1/inbox", query, "events", "inbox", want);
     if (args.json) return console.log(JSON.stringify(r, null, 2));
     if (!(r.events || []).length) return console.log(dim(`No conversations in ${query.folder}.`));
     for (const e of r.events) {
@@ -1718,7 +1873,7 @@ async function cmdBlocklist(argv) {
   const key = requireKey();
   if (sub === "list") {
     const args = readFlags(argv.slice(1));
-    const r = need(await request("GET", args.base, "/api/v1/blocklist", { key }), "blocklist");
+    const r = await fetchPages(args.base, key, "/api/v1/blocklist", { limit: 100 }, "entries", "blocklist", true);
     if (args.json) return console.log(JSON.stringify(r, null, 2));
     if (!(r.entries || []).length) return console.log(dim("Blocklist is empty."));
     for (const e of r.entries) console.log(`${e.type === "domain" ? "@" : " "}${e.value}  ${dim(e.reason || "")}${e.yours ? "" : dim("  (Argorant-wide)")}  ${dim(e.id)}`);
@@ -1842,7 +1997,7 @@ async function cmdInboxes(argv) {
   const key = requireKey();
   if (sub === "list") {
     const args = readFlags(argv.slice(1));
-    const r = need(await request("GET", args.base, "/api/v1/inboxes", { key }), "inboxes list");
+    const r = await fetchPages(args.base, key, "/api/v1/inboxes", { limit: 100 }, "inboxes", "inboxes list", true);
     if (args.json) return console.log(JSON.stringify(r, null, 2));
     const rows = r.inboxes || [];
     if (!rows.length) return console.log(dim("No mailboxes connected yet. Connect Google Workspace with `argorant inboxes connect-google --admin ...` or Microsoft 365 in the app."));
@@ -2134,13 +2289,16 @@ function findNeed(res, what, { expect } = {}) {
     const to = res.res && res.res.headers && res.res.headers.location;
     die(`${what}: the server answered with a redirect (HTTP ${res.status}${to ? ` to ${to}` : ""}). Check --base / ARGORANT_API_BASE.`);
   }
-  if (res.status >= 400 && j && typeof j === "object" && !Array.isArray(j) && j.detail === undefined && (j.error || j.message)) {
+  const envelope = j && typeof j === "object" && j.error && typeof j.error === "object" && !Array.isArray(j.error);
+  if (res.status >= 400 && !envelope && j && typeof j === "object" && !Array.isArray(j) && j.detail === undefined && (j.error || j.message)) {
     r = { ...res, json: { detail: j } };
   }
   if (r.status === 429) {
     const ra = Number((res.res && res.res.headers && res.res.headers["retry-after"]) || 0);
-    const msg = detailMsg(r.json && r.json.detail) || "the email finder limit was reached.";
-    die(Number.isFinite(ra) && ra > 0 ? `${msg} Try again in ${fmtWait(Math.ceil(ra))}. Nothing was charged.` : `${msg} Nothing was charged.`, EXIT.RATE_LIMIT);
+    const msg = errorMessage(r.json) || "the email finder limit was reached.";
+    const rid = requestIdOf(res);
+    const ref = rid ? `\nRequest id: ${rid} (quote it if you contact support)` : "";
+    die((Number.isFinite(ra) && ra > 0 ? `${msg} Try again in ${fmtWait(Math.ceil(ra))}. Nothing was charged.` : `${msg} Nothing was charged.`) + ref, EXIT.RATE_LIMIT);
   }
   let out = need(r, what);
   // Job endpoints answer {ok, job: {...}}; the commands work on the job itself.
@@ -2483,6 +2641,692 @@ async function cmdFind(argv) {
   return findSingle(args, key);
 }
 
+// =============================================================================
+// API v1 commands (0.13.0): account, lists, exports, credits, webhooks,
+// companies and lookup. They call /api/v1 only. Every write carries an
+// Idempotency-Key (see request()), so running a command again never does the
+// work twice. Lists come back a page at a time: -n sets the page size,
+// --cursor continues where the last page ended, --all walks to the end.
+// =============================================================================
+
+const V1 = "/api/v1";
+const PAGE_FLAGS = { "-n": "limit", "--limit": "limit", "--cursor": "cursor", "--offset": "offset" };
+const COMPANY_FILTER_FLAGS = {
+  "--query": "q",
+  "--q": "q",
+  "--industry": "industry",
+  "--industries": "industries",
+  "--country": "country",
+  "--geography": "country",
+  "--region": "country",
+  "--state": "state",
+  "--city": "city",
+  "--company": "company_name",
+  "--domain": "company_domain",
+  "--employees": "employee_range",
+  "--employee-range": "employee_range",
+  "--keywords": "keywords",
+  "--keyword": "keywords",
+  "--technologies": "technologies",
+  "--technology": "technologies",
+};
+const LOOKUP_KINDS = ["industries", "countries", "keywords", "technologies", "titles"];
+const LOOKUP_ALIASES = { industry: "industries", country: "countries", keyword: "keywords", technology: "technologies", tech: "technologies", title: "titles" };
+
+// The page query every list command sends: limit plus cursor or offset.
+function pageQuery(args, def = 25) {
+  const q = { limit: args.limit !== undefined ? parseLimit(args.limit, "--limit") : def };
+  if (args.cursor !== undefined) q.cursor = String(args.cursor);
+  if (args.offset !== undefined) {
+    const n = Number(args.offset);
+    if (!Number.isInteger(n) || n < 0) die(`--offset must be 0 or a positive whole number (got "${args.offset}").`);
+    q.offset = n;
+  }
+  if (q.cursor !== undefined && q.offset !== undefined) die("pass --cursor or --offset, not both.");
+  return q;
+}
+
+// One page, or with all=true every page (following next_cursor) merged into
+// one answer of the same shape.
+async function fetchPages(base, key, urlPath, query, itemsKey, what, all) {
+  let page = need(await request("GET", base, urlPath, { key, query }), what);
+  if (!all) return page;
+  const items = [...pickItems(page, itemsKey)];
+  let guard = 0;
+  while (page.next_cursor && guard++ < 5000) {
+    const q = { ...query, cursor: page.next_cursor };
+    delete q.offset;
+    page = need(await request("GET", base, urlPath, { key, query: q }), what);
+    items.push(...pickItems(page, itemsKey));
+  }
+  return { ...page, [itemsKey]: items, offset: query.offset || 0, next_cursor: null, has_more: false };
+}
+
+// Up to `want` rows, a page of at most 100 at a time, following next_cursor.
+async function fetchUpTo(base, key, urlPath, query, itemsKey, what, want) {
+  let q = { ...query, limit: Math.min(100, want) };
+  let page = need(await request("GET", base, urlPath, { key, query: q }), what);
+  const rows = [...pickItems(page, itemsKey)];
+  let guard = 0;
+  while (rows.length < want && page.next_cursor && guard++ < 5000) {
+    q = { ...query, limit: Math.min(100, want - rows.length), cursor: page.next_cursor };
+    delete q.offset;
+    page = need(await request("GET", base, urlPath, { key, query: q }), what);
+    const more = pickItems(page, itemsKey);
+    if (!more.length) break;
+    rows.push(...more);
+  }
+  return { ...page, [itemsKey]: rows.slice(0, want) };
+}
+
+// The array of a list answer, by its resource key (lists, exports, ...) with
+// the usual fallbacks.
+function pickItems(r, itemsKey) {
+  if (!r || typeof r !== "object") return [];
+  for (const k of [itemsKey, "data", "results", "items"]) if (Array.isArray(r[k])) return r[k];
+  return [];
+}
+
+function pageFooter(r, itemsKey, hint) {
+  const n = pickItems(r, itemsKey).length;
+  const parts = [`${n.toLocaleString()} shown`];
+  if (r.total !== undefined && r.total !== null) parts.push(`${Number(r.total).toLocaleString()} in total`);
+  console.log(dim(parts.join(" · ")));
+  if (r.next_cursor) console.log(dim(`Next page:  ${hint} --cursor ${r.next_cursor}   (or --all for everything)`));
+}
+
+function numericId(raw, what, usage) {
+  const id = String(raw || "").trim();
+  if (!id) die(usage);
+  if (!/^\d+$/.test(id)) die(`${what} must be a number (got "${raw}").`);
+  return id;
+}
+
+// Destructive and paid-on-confirm commands: ask at a terminal, refuse without
+// --yes when there is nobody to ask (an agent, CI, a pipe).
+async function confirmOrDie(args, question, noTtyHint) {
+  if (args.yes) return true;
+  if (!process.stdin.isTTY) die(`${noTtyHint} Add --yes to confirm.`);
+  const ans = await prompt(`${question} [y/N] `);
+  if (!/^y(es)?$/i.test(ans)) {
+    console.log(dim("aborted."));
+    return false;
+  }
+  return true;
+}
+
+function fmtDate(v) {
+  if (!v) return "";
+  return String(v).slice(0, 16).replace("T", " ");
+}
+
+function fmtNum(v) {
+  if (v === undefined || v === null || v === "") return "-";
+  const n = Number(v);
+  return Number.isFinite(n) ? n.toLocaleString("en-US", { maximumFractionDigits: 2 }) : String(v);
+}
+
+// A price from cents (amount_cents, price_cents) or a decimal amount (price, amount).
+function fmtPrice(o, currency) {
+  if (!o || typeof o !== "object") return "?";
+  const cur = String(o.currency || currency || "usd").toLowerCase();
+  const cents = o.price_cents ?? o.amount_cents ?? o.total_cents ?? o.due_today_cents ?? o.charged_cents;
+  if (cents !== undefined && cents !== null) return money(cents, cur);
+  const dec = o.price ?? o.amount ?? o.total;
+  if (dec !== undefined && dec !== null && Number.isFinite(Number(dec))) return money(Math.round(Number(dec) * 100), cur);
+  return "?";
+}
+
+// ---- account ----
+async function cmdAccount(argv) {
+  const args = readFlags(argv);
+  const key = requireKey();
+  const a = need(await request("GET", args.base, `${V1}/account`, { key }), "account");
+  if (args.json) return console.log(JSON.stringify(a, null, 2));
+  const ws = a.workspace && typeof a.workspace === "object" ? a.workspace : {};
+  const role = a.workspace_role || ws.role;
+  console.log(`${bold("Account")}     ${a.email || (a.user && a.user.email) || "-"}${role ? dim(` (${role})`) : ""}`);
+  if (ws.name || a.workspace_name) console.log(`${bold("Workspace")}   ${ws.name || a.workspace_name}`);
+  const plan = a.plan && typeof a.plan === "object" ? a.plan : { name: a.plan };
+  if (plan.name) {
+    const interval = plan.billing_interval || plan.interval;
+    const bits = [plan.status, interval && `billed ${interval === "year" ? "yearly" : "monthly"}`, (plan.renews_at || plan.renewal_at) && `${plan.cancels_at_period_end ? "ends" : "renews"} ${fmtDate(plan.renews_at || plan.renewal_at).slice(0, 10)}`].filter(Boolean);
+    console.log(`${bold("Plan")}        ${plan.name}${bits.length ? dim(`  ${bits.join(" · ")}`) : ""}`);
+  }
+  const cr = a.credits;
+  if (cr !== undefined && cr !== null) {
+    if (typeof cr === "object") {
+      const avail = cr.available ?? cr.balance ?? cr.remaining ?? cr.total;
+      const parts = [];
+      for (const [k, label] of [["from_plan", "from your plan"], ["plan", "from your plan"], ["pay_as_you_go", "pay as you go"], ["free", "free"]]) {
+        if (cr[k] !== undefined && cr[k] !== null && Number(cr[k]) > 0) parts.push(`${fmtNum(cr[k])} ${label}`);
+      }
+      console.log(`${bold("Credits")}     ${bold(fmtNum(avail))} available${parts.length ? dim(`  (${parts.join(" · ")})`) : ""}`);
+    } else {
+      console.log(`${bold("Credits")}     ${bold(fmtNum(cr))} available`);
+    }
+  }
+  const lim = (a.limits && typeof a.limits === "object" && a.limits) || (a.rate_limit && typeof a.rate_limit === "object" && a.rate_limit) || {};
+  const perMin = lim.requests_per_minute ?? lim.per_minute ?? a.rate_limit_per_minute;
+  if (perMin !== undefined && perMin !== null) console.log(`${bold("Requests")}    ${fmtNum(perMin)} per minute`);
+  else if (lim.unlimited) console.log(`${bold("Requests")}    no per-minute or daily limit`);
+  const daily = lim.daily && typeof lim.daily === "object" ? Object.entries(lim.daily).filter(([, v]) => v && typeof v === "object" && v.limit !== undefined && v.limit !== null) : [];
+  if (daily.length) {
+    console.log(`${bold("Today")}       ${daily.map(([name, v]) => `${name.replace(/_/g, " ")} ${fmtNum(v.used_today || 0)}/${fmtNum(v.limit)}`).join(" · ")}`);
+  }
+  const ce = a.campaign_emails;
+  if (ce && typeof ce === "object") {
+    if (ce.unlimited) console.log(`${bold("Campaign emails")}  no monthly limit`);
+    else if (ce.allowance !== undefined && ce.allowance !== null) {
+      console.log(`${bold("Campaign emails")}  ${fmtNum(ce.used)} of ${fmtNum(ce.allowance)} used${ce.resets_on ? dim(`  resets ${String(ce.resets_on).slice(0, 10)}`) : ""}`);
+    }
+    if (ce.trial_active && ce.trial_days_left !== undefined && ce.trial_days_left !== null) console.log(dim(`  free trial: ${ce.trial_days_left} day(s) left`));
+  }
+  if (Array.isArray(a.scopes)) console.log(`${bold("Scopes")}      ${a.scopes.join(", ") || "-"}`);
+}
+
+// ---- lists ----
+function listsHelp() {
+  const p = bold("argorant lists");
+  console.log(`
+${bold("Argorant lists")} - saved lists of people (free to create and browse)
+
+  ${p} [ls] [--kind records|filtered] [-n 25] [--cursor <c>] [--all]
+  ${p} create --name "<name>" [filters]      ${dim("saves a search; the size is counted for you")}
+  ${p} show <id>
+  ${p} people <id> [-n 25] [--cursor <c>] [--all]   ${dim("the people in it, contact details hidden")}
+  ${p} rename <id> --name "<new name>"
+  ${p} rm <id> [--yes]
+  ${p} export <id> [-n 1000] [-o leads.csv] [--include-exported] [--include-phones] [--no-wait] [--yes]
+      ${dim("1 credit per valid contact; with --include-phones 10 credits per phone number returned")}
+
+  filters for create: --title --seniority --department --industry --keywords --country --state --city --company --domain
+  ${dim("Add --json to any command for the raw answer.")}
+`);
+}
+
+const LIST_FILTER_FLAGS = {
+  "--query": "q",
+  "--title": "title",
+  "--exclude-title": "exclude_title",
+  "--seniority": "seniority",
+  "--department": "departments",
+  "--departments": "departments",
+  "--industry": "industry",
+  "--keywords": "keywords",
+  "--keyword": "keywords",
+  "--country": "country",
+  "--geography": "country",
+  "--region": "country",
+  "--state": "state",
+  "--city": "city",
+  "--company": "company_name",
+  "--domain": "company_domain",
+};
+
+function listLine(l) {
+  const size = Number(l.snapshot_total || l.item_count || 0);
+  const kind = l.selection_mode === "filtered" ? "saved search" : "list";
+  return `${bold("#" + (l.list_id ?? l.id))}  ${l.name || "-"}  ${dim(`${size.toLocaleString()} people · ${kind}${l.updated_at ? ` · updated ${fmtDate(l.updated_at)}` : ""}`)}`;
+}
+
+async function cmdLists(argv) {
+  let sub = argv[0] && !argv[0].startsWith("-") ? argv[0].toLowerCase() : "ls";
+  let rest = argv[0] && !argv[0].startsWith("-") ? argv.slice(1) : argv;
+  if (/^\d+$/.test(sub)) { rest = argv; sub = "show"; }
+  if (sub === "help") return listsHelp();
+  const key = requireKey();
+  if (sub === "ls" || sub === "list") {
+    const args = readFlags(rest, { ...PAGE_FLAGS, "--kind": "kind" }, { "--all": "all" });
+    const query = pageQuery(args, 25);
+    if (args.kind) {
+      const kind = String(args.kind).toLowerCase();
+      if (!["all", "records", "filtered"].includes(kind)) die("--kind is all, records (hand-picked lists) or filtered (saved searches)");
+      query.kind = kind;
+    }
+    const r = await fetchPages(args.base, key, `${V1}/lists`, query, "lists", "lists", args.all);
+    if (args.json) return console.log(JSON.stringify(r, null, 2));
+    const rows = pickItems(r, "lists");
+    if (!rows.length) return console.log(dim('No saved lists yet. Create one with `argorant lists create --name "..." --title CEO --country Germany`.'));
+    for (const l of rows) console.log(listLine(l));
+    pageFooter(r, "lists", "argorant lists");
+    return;
+  }
+  if (sub === "create" || sub === "new") {
+    const args = readFlags(rest, { ...LIST_FILTER_FLAGS, "--name": "name" }, { "--has-phone": "has_phone", "--has-linkedin": "has_linkedin", "--has-email": "has_email" });
+    const name = String(args.name || "").trim();
+    if (!name) die('usage: argorant lists create --name "My list" [filters]   (e.g. --title CEO --country Germany)');
+    const filters = {};
+    for (const field of Object.values(LIST_FILTER_FLAGS)) if (args[field]) filters[field] = args[field];
+    for (const field of ["has_phone", "has_linkedin", "has_email"]) if (args[field]) filters[field] = "true";
+    if (args._.length) filters.q = args._.join(" ");
+    if (!Object.keys(filters).length) die("give at least one filter, for example --title CEO --country Germany");
+    const body = { name, filters };
+    const r = need(await request("POST", args.base, `${V1}/lists`, { key, body }), "lists create");
+    if (args.json) return console.log(JSON.stringify(r, null, 2));
+    const l = r.list && typeof r.list === "object" ? r.list : r;
+    console.log(green("✓") + ` Saved list ${bold("#" + (l.list_id ?? l.id))} ${dim("“" + (l.name || name) + "”")} · ${bold(Number(l.snapshot_total || 0).toLocaleString())} matching people`);
+    console.log(dim(`Export it:  argorant lists export ${l.list_id ?? l.id} -n 500 -o leads.csv`));
+    return;
+  }
+  if (sub === "show" || sub === "get" || sub === "status") {
+    const args = readFlags(rest);
+    const id = numericId(args._[0], "list id", "usage: argorant lists show <id>");
+    const r = need(await request("GET", args.base, `${V1}/lists/${id}`, { key }), "list");
+    if (args.json) return console.log(JSON.stringify(r, null, 2));
+    const l = r.list && typeof r.list === "object" ? r.list : r;
+    console.log(listLine(l));
+    const f = l.filters && typeof l.filters === "object" ? Object.entries(l.filters).filter(([k, v]) => v && k !== "record_type") : [];
+    if (f.length) console.log(dim(`  filters: ${f.map(([k, v]) => `${k}=${v}`).join(", ")}`));
+    console.log(dim(`  argorant lists people ${id}   ·   argorant lists export ${id} -o leads.csv`));
+    return;
+  }
+  if (sub === "people" || sub === "items") {
+    const args = readFlags(rest, PAGE_FLAGS, { "--all": "all" });
+    const id = numericId(args._[0], "list id", "usage: argorant lists people <id> [-n 25] [--cursor <c>] [--all]");
+    const r = await fetchPages(args.base, key, `${V1}/lists/${id}/people`, pageQuery(args, 25), "people", "list people", args.all);
+    if (args.json) return console.log(JSON.stringify(r, null, 2));
+    const rows = pickItems(r, "people");
+    if (!rows.length) return console.log(dim("This list has no people yet."));
+    for (const p of rows) {
+      const name = p.full_name || [p.first_name, p.last_name].filter(Boolean).join(" ") || p.preview || p.name;
+      const who = [name, p.title].filter(Boolean).join(" · ");
+      const where = [p.company || p.company_name, p.country].filter(Boolean).join(", ");
+      console.log(`  ${bold(who || "-")}${where ? dim("  " + where) : ""}${p.email ? "  " + cyan(p.email) : ""}`);
+    }
+    pageFooter(r, "people", `argorant lists people ${id}`);
+    return;
+  }
+  if (sub === "rename") {
+    const args = readFlags(rest, { "--name": "name" });
+    const id = numericId(args._[0], "list id", 'usage: argorant lists rename <id> --name "<new name>"');
+    const name = String(args.name || args._.slice(1).join(" ") || "").trim();
+    if (!name) die('usage: argorant lists rename <id> --name "<new name>"');
+    const r = need(await request("PATCH", args.base, `${V1}/lists/${id}`, { key, body: { name } }), "lists rename");
+    if (args.json) return console.log(JSON.stringify(r, null, 2));
+    const l = r.list && typeof r.list === "object" ? r.list : r;
+    return console.log(green("✓") + ` List #${id} is now ${bold("“" + (l.name || name) + "”")}`);
+  }
+  if (sub === "rm" || sub === "delete" || sub === "remove") {
+    const args = readFlags(rest);
+    const id = numericId(args._[0], "list id", "usage: argorant lists rm <id> [--yes]");
+    if (!(await confirmOrDie(args, `Delete list #${id}? Campaigns that already use its people keep them.`, `Deleting list #${id} needs a confirmation.`))) return;
+    const r = need(await request("DELETE", args.base, `${V1}/lists/${id}`, { key }), "lists rm");
+    if (args.json) return console.log(JSON.stringify(r, null, 2));
+    return console.log(green("✓") + ` Deleted list #${id}`);
+  }
+  if (sub === "export") return listsExport(rest, key);
+  die(`unknown lists subcommand: ${sub} (ls, create, show, people, rename, rm, export)`);
+}
+
+async function listsExport(rest, key) {
+  const args = readFlags(rest, { "-n": "limit", "--limit": "limit", "-o": "output", "--output": "output" }, {
+    "--include-phones": "includePhones",
+    "--include-exported": "includeExported",
+    "--exclude-previously-exported": "excludeExported",
+    "--no-wait": "noWait",
+  });
+  const id = numericId(args._[0], "list id", "usage: argorant lists export <id> [-n 1000] [-o leads.csv] [--include-exported] [--include-phones] [--no-wait] [--yes]");
+  if (args.includeExported && args.excludeExported) die("pass --include-exported or --exclude-previously-exported, not both.");
+  const limit = args.limit !== undefined ? parseLimit(args.limit, "--limit") : 1000;
+  const dest = args.noWait ? null : ensureWritable(args.output || "argorant-leads.csv");
+  // Same rule as `export`: the question is for a person at a terminal; with
+  // --yes, --json or no terminal it runs straight away.
+  if (!args.yes && !args.json && process.stdin.isTTY) {
+    const phones = args.includePhones ? " plus 10 credits per phone number returned" : "";
+    const ans = await prompt(`Export up to ${bold(limit)} people from list #${id}? 1 credit per valid contact${phones}; invalid ones cost nothing. [y/N] `);
+    if (!/^y(es)?$/i.test(ans)) return console.log(dim("aborted."));
+  }
+  const body = { limit, exclude_previously_exported: !args.includeExported };
+  if (args.includePhones) body.include_phones = true;
+  const job = need(await request("POST", args.base, `${V1}/lists/${id}/export`, { key, body }), "lists export");
+  const isBatch = job.type === "batch" || (job.batch_id && !job.job_id);
+  const jobId = isBatch ? job.batch_id : job.job_id;
+  if (args.noWait || !jobId) {
+    if (args.json) return console.log(JSON.stringify(job, null, 2));
+    console.log(green("✓") + ` Export ${isBatch ? "batch " : ""}${bold("#" + (jobId ?? "?"))} started for list #${id}`);
+    if (jobId) console.log(dim(`Check it:  argorant exports status ${jobId}${isBatch ? " --batch" : ""}   ·   download:  argorant exports download ${jobId}${isBatch ? " --batch" : ""} -o leads.csv`));
+    return;
+  }
+  if (isBatch) {
+    if (!args.json) process.stdout.write(dim(`Large export queued as batch #${jobId}\n`));
+    const batch = await pollExportBatch(args, key, EXPORT_API_V1.batch(jobId), { quiet: !!args.json });
+    if (!args.json) process.stdout.write("\n");
+    const files = await downloadBatchChunks(args, key, batch, dest, EXPORT_API_V1);
+    if (args.json) return console.log(JSON.stringify({ ...job, files }, null, 2));
+    for (const f of files) console.log(green("✓") + ` ${bold(String(countCsvRows(f) ?? "?"))} rows → ${bold(f)}`);
+    return;
+  }
+  if (!args.json) process.stdout.write(dim(`Export #${jobId} queued - checking every email and building the file`));
+  const started = Date.now();
+  let status = {};
+  for (;;) {
+    await new Promise((r) => setTimeout(r, 2500));
+    status = need(await request("GET", args.base, EXPORT_API_V1.job(jobId), { key }), "export status");
+    const st = String(status.status || "").toLowerCase();
+    if (!args.json) process.stdout.write(".");
+    if (EXPORT_TERMINAL_OK.includes(st) || status.downloadable) break;
+    if (EXPORT_TERMINAL_FAIL.includes(st)) die(`\nexport ${st}${status.error_message ? `: ${status.error_message}` : "."}`);
+    if (Date.now() - started > 1000 * 60 * 20) die(`\nstill running after 20 minutes. Check later with \`argorant exports status ${jobId}\`.`);
+  }
+  if (!args.json) process.stdout.write("\n");
+  try {
+    await downloadTo(args.base, status.download_url || status.download_api_path || EXPORT_API_V1.download(jobId), key, dest);
+  } catch (e) {
+    die(`${e.message}\nThe export itself is done. Download it again with \`argorant exports download ${jobId} -o ${args.output || "argorant-leads.csv"}\`.`);
+  }
+  if (args.json) return console.log(JSON.stringify({ ...job, file: dest }, null, 2));
+  const rows = countCsvRows(dest);
+  console.log(green("✓") + ` Saved ${rows != null ? bold(rows.toLocaleString()) + " rows → " : ""}${bold(dest)}`);
+}
+
+// ---- exports ----
+async function cmdExports(argv) {
+  const sub = argv[0] && !argv[0].startsWith("-") ? argv[0].toLowerCase() : "ls";
+  const rest = argv[0] && !argv[0].startsWith("-") ? argv.slice(1) : argv;
+  if (sub === "help") {
+    return console.log(`
+${bold("argorant exports")} [ls] [-n 25] [--cursor <c>] [--all]     ${dim("your exports, newest first")}
+${bold("argorant exports")} status <id> [--batch]
+${bold("argorant exports")} download <id> [--batch] [-o leads.csv]   ${dim("free; the file stays available for a while after it is built")}
+${dim("New exports: argorant export \"<query>\" -n 1000 -o leads.csv, or argorant lists export <list-id>")}
+`);
+  }
+  const key = requireKey();
+  if (sub === "ls" || sub === "list") {
+    const args = readFlags(rest, PAGE_FLAGS, { "--all": "all" });
+    const r = await fetchPages(args.base, key, `${V1}/exports`, pageQuery(args, 25), "exports", "exports", args.all);
+    if (args.json) return console.log(JSON.stringify(r, null, 2));
+    const rows = pickItems(r, "exports");
+    if (!rows.length) return console.log(dim('No exports yet. Start one with `argorant export "<query>" -n 500 -o leads.csv`.'));
+    for (const e of rows) {
+      const id = e.job_id ?? e.id;
+      console.log(`${bold("#" + id)}  ${e.status || "-"}  ${dim(`${Number(e.verified_rows || 0).toLocaleString()} valid of ${Number(e.total_rows || 0).toLocaleString()} rows · ${fmtDate(e.created_at)}`)}${e.downloadable ? green("  ready") : ""}`);
+    }
+    pageFooter(r, "exports", "argorant exports");
+    return;
+  }
+  if (sub === "status" || sub === "download") {
+    const args = readFlags(rest, { "-o": "output", "--output": "output" }, { "--batch": "batch" });
+    const id = numericId(args._[0], "export id", `usage: argorant exports ${sub} <id> [--batch]${sub === "download" ? " [-o leads.csv]" : ""}`);
+    return sub === "status" ? exportStatusCmd(args, key, id, EXPORT_API_V1, "exports") : exportDownloadCmd(args, key, id, EXPORT_API_V1, "exports");
+  }
+  die(`unknown exports subcommand: ${sub} (ls, status, download)`);
+}
+
+// ---- credits ----
+function packLine(p) {
+  const credits = Number(p.credits || 0);
+  const cents = p.price_cents ?? p.amount_cents;
+  const sign = String(p.currency || "usd").toLowerCase() === "eur" ? "€" : "$";
+  const per = cents !== undefined && cents !== null && credits ? ` · ${sign}${(Number(cents) / 100 / credits).toFixed(3)} per credit` : "";
+  return `${bold(credits.toLocaleString())} credits  ${fmtPrice(p)}${dim(per + (p.valid_days ? ` · valid ${p.valid_days} days` : ""))}`;
+}
+
+function quoteLines(q) {
+  const lines = [];
+  const pack = q.pack && typeof q.pack === "object" ? q.pack : q;
+  lines.push(`${bold(Number(pack.credits || q.credits || 0).toLocaleString())} credits for ${bold(fmtPrice(q.price_cents !== undefined || q.amount_cents !== undefined ? q : pack, q.currency))}`);
+  const card = q.payment && q.payment.saved_card;
+  if (card && card.usable) lines.push(`Paid with: the saved ${card.card || "card"}, charged right away when you confirm${card.charge_before ? ` (before ${fmtDate(card.charge_before)} UTC)` : ""}`);
+  else if (card) lines.push(dim(`Paid with: a payment link you open yourself${card.reason ? ` (${card.reason})` : ""}`));
+  else lines.push(dim("Paid with: a payment link you open yourself"));
+  if (q.expires_at) lines.push(dim(`Quote ${q.quote_id} is valid until ${fmtDate(q.expires_at)} UTC`));
+  return lines;
+}
+
+async function cmdCredits(argv) {
+  const sub = argv[0] && !argv[0].startsWith("-") ? argv[0].toLowerCase() : "packs";
+  const rest = argv[0] && !argv[0].startsWith("-") ? argv.slice(1) : argv;
+  if (sub === "help") {
+    return console.log(`
+${bold("argorant credits")} packs                      ${dim("the credit packs and their prices")}
+${bold("argorant credits")} quote <credits>            ${dim("a price quote for one pack; nothing is bought")}
+${bold("argorant credits")} buy <credits> [--pay-with link] [--yes]
+    ${dim("shows the quote, asks, then charges the saved card (when your workspace allows it) or gives you a payment link")}
+${bold("argorant credits")} purchases [<id>]           ${dim("purchases made with this account")}
+${dim("1 credit = 1 valid contact; 0.5 credit = 1 email check. Bought credits stay valid for 365 days.")}
+`);
+  }
+  const key = requireKey();
+  if (sub === "packs" || sub === "prices") {
+    const args = readFlags(rest);
+    const r = need(await request("GET", args.base, `${V1}/credits/packs`, { key }), "credit packs");
+    if (args.json) return console.log(JSON.stringify(r, null, 2));
+    const packs = pickItems(r, "packs");
+    if (!packs.length) return console.log(dim("No credit packs are on offer right now."));
+    for (const p of packs) console.log(packLine(p));
+    console.log(dim("Buy one:  argorant credits buy <credits>"));
+    return;
+  }
+  if (sub === "quote" || sub === "buy") {
+    const args = readFlags(rest, { "--currency": "currency", "--pay-with": "payWith" });
+    const credits = parseLimit(String(args._[0] || "").replace(/[,_]/g, "") || "x", "credits");
+    const body = { credits };
+    if (args.currency) body.currency = String(args.currency).toLowerCase();
+    const q = need(await request("POST", args.base, `${V1}/credits/quote`, { key, body }), "credit quote");
+    if (sub === "quote") {
+      if (args.json) return console.log(JSON.stringify(q, null, 2));
+      for (const l of quoteLines(q)) console.log(l);
+      console.log(dim(`Buy it:  argorant credits buy ${credits}`));
+      return;
+    }
+    const payWith = String(args.payWith || "auto").toLowerCase();
+    if (!["auto", "link"].includes(payWith)) die("--pay-with is link (always a payment link); leave it out to use the saved card when your workspace allows it");
+    if (!args.json) for (const l of quoteLines(q)) console.log(l);
+    const card = q.payment && q.payment.saved_card;
+    const how = payWith !== "link" && card && card.usable ? `The saved ${card.card || "card"} is charged now.` : "You get a payment link; nothing is charged before you pay it.";
+    if (!(await confirmOrDie(args, `Buy ${credits.toLocaleString()} credits for ${fmtPrice(q.price_cents !== undefined || q.amount_cents !== undefined ? q : q.pack || q, q.currency)}? ${how}`, "Buying credits needs a confirmation."))) return;
+    const pbody = { quote_id: q.quote_id, confirmed: true };
+    if (payWith !== "auto") pbody.pay_with = payWith;
+    const r = need(await request("POST", args.base, `${V1}/credits/purchases`, { key, body: pbody }), "credit purchase");
+    if (args.json) return console.log(JSON.stringify({ quote: q, purchase: r }, null, 2));
+    const p = r.purchase && typeof r.purchase === "object" ? { ...r.purchase, ...r } : r;
+    const url = p.checkout_url || p.payment_url || p.url;
+    if (String(p.status || "").toLowerCase() === "paid") {
+      console.log(green("✓") + ` Paid${p.card ? ` with the saved ${p.card}` : ""}: ${bold(Number(p.credits || credits).toLocaleString())} credits added${p.replayed ? dim(" (already done earlier)") : ""}`);
+      if (p.message) console.log(dim(p.message));
+    } else if (url) {
+      console.log(green("✓") + ` Purchase ${bold(p.purchase_id || p.id || "")} is waiting for payment${p.replayed ? dim(" (same purchase as before)") : ""}`);
+      if (p.saved_card && p.saved_card.reason) console.log(yellow(`Not charged to the saved card: ${p.saved_card.reason}`));
+      console.log(`Pay here: ${cyan(url)}`);
+      console.log(dim("The credits are added as soon as the payment goes through."));
+    } else {
+      console.log(`${p.status || "done"}. ${dim(p.message || "")}`);
+    }
+    return;
+  }
+  if (sub === "purchases" || sub === "purchase" || sub === "history") {
+    const args = readFlags(rest, PAGE_FLAGS, { "--all": "all" });
+    const id = args._[0];
+    if (id) {
+      const r = need(await request("GET", args.base, `${V1}/credits/purchases/${encodeURIComponent(id)}`, { key }), "credit purchase");
+      if (args.json) return console.log(JSON.stringify(r, null, 2));
+      const p = r.purchase && typeof r.purchase === "object" ? r.purchase : r;
+      console.log(`${bold(p.purchase_id || p.id || id)}  ${p.status || "-"}  ${fmtNum(p.credits)} credits · ${fmtPrice(p)}  ${dim(fmtDate(p.created_at))}`);
+      if (p.checkout_url && String(p.status || "") !== "paid") console.log(`Pay here: ${cyan(p.checkout_url)}`);
+      return;
+    }
+    const r = await fetchPages(args.base, key, `${V1}/credits/purchases`, pageQuery(args, 25), "purchases", "credit purchases", args.all);
+    if (args.json) return console.log(JSON.stringify(r, null, 2));
+    const rows = pickItems(r, "purchases");
+    if (!rows.length) return console.log(dim("No credit purchases yet. See the packs with `argorant credits packs`."));
+    for (const p of rows) console.log(`${bold(p.purchase_id || p.id)}  ${p.status || "-"}  ${fmtNum(p.credits)} credits · ${fmtPrice(p)}  ${dim(fmtDate(p.created_at))}`);
+    pageFooter(r, "purchases", "argorant credits purchases");
+    return;
+  }
+  die(`unknown credits subcommand: ${sub} (packs, quote, buy, purchases)`);
+}
+
+// ---- webhooks ----
+async function cmdWebhooks(argv) {
+  const sub = argv[0] && !argv[0].startsWith("-") ? argv[0].toLowerCase() : "ls";
+  const rest = argv[0] && !argv[0].startsWith("-") ? argv.slice(1) : argv;
+  if (sub === "help") {
+    return console.log(`
+${bold("argorant webhooks")} [ls]                                 ${dim("your webhooks and the events you can subscribe to")}
+${bold("argorant webhooks")} add <https-url> --events reply.received,export.ready
+${bold("argorant webhooks")} set <id> [--url <https-url>] [--events a,b] [--active|--inactive]
+${bold("argorant webhooks")} test <id>                            ${dim("sends a test event to the address")}
+${bold("argorant webhooks")} deliveries <id> [-n 25]              ${dim("recent deliveries and their result")}
+${bold("argorant webhooks")} rm <id> [--yes]
+${dim("Webhooks are included from the Pro plan. Each delivery is signed. Check its X-Argorant-Signature header (a SHA-256 HMAC of the body) with the secret shown when you add the webhook.")}
+`);
+  }
+  const key = requireKey();
+  if (sub === "ls" || sub === "list" || sub === "events") {
+    const args = readFlags(rest, PAGE_FLAGS, { "--all": "all" });
+    const r = await fetchPages(args.base, key, `${V1}/webhooks`, pageQuery(args, 25), "webhooks", "webhooks", args.all);
+    if (args.json) return console.log(JSON.stringify(r, null, 2));
+    if (sub !== "events") {
+      const rows = pickItems(r, "webhooks");
+      if (!rows.length) console.log(dim("No webhooks yet. Add one with `argorant webhooks add https://example.com/hook --events reply.received`."));
+      for (const w of rows) {
+        const events = Array.isArray(w.events) ? w.events.join(", ") : String(w.events || "");
+        console.log(`${bold("#" + w.id)}  ${w.url}  ${w.active === false ? yellow("paused") : green("active")}`);
+        console.log(dim(`  ${events}${w.last_error ? ` · last error: ${w.last_error}` : ""}`));
+      }
+      if (rows.length) pageFooter(r, "webhooks", "argorant webhooks");
+    }
+    if (Array.isArray(r.events) && r.events.length) console.log(dim(`Events: ${r.events.join(", ")}`));
+    return;
+  }
+  if (sub === "add" || sub === "create") {
+    const args = readFlags(rest, { "--events": "events", "--event": "events", "--url": "url" });
+    const url = String(args.url || args._[0] || "").trim();
+    const events = String(args.events || "").split(",").map((x) => x.trim()).filter(Boolean);
+    if (!url || !events.length) die("usage: argorant webhooks add <https-url> --events reply.received,export.ready   (argorant webhooks events lists them)");
+    if (!/^https:\/\//i.test(url)) die("the webhook address must start with https://");
+    const r = need(await request("POST", args.base, `${V1}/webhooks`, { key, body: { url, events } }), "webhooks add");
+    if (args.json) return console.log(JSON.stringify(r, null, 2));
+    const w = r.webhook && typeof r.webhook === "object" ? { ...r, ...r.webhook } : r;
+    console.log(green("✓") + ` Webhook ${bold("#" + w.id)} sends ${(w.events || events).join ? (w.events || events).join(", ") : w.events} to ${w.url || url}`);
+    if (w.secret) {
+      console.log(`Signing secret: ${bold(w.secret)}`);
+      console.log(yellow("Store it now. It is shown only once."));
+    }
+    return;
+  }
+  if (sub === "set" || sub === "update") {
+    const args = readFlags(rest, { "--events": "events", "--url": "url" }, { "--active": "activeOn", "--inactive": "activeOff", "--pause": "activeOff", "--resume": "activeOn" });
+    const id = numericId(args._[0], "webhook id", "usage: argorant webhooks set <id> [--url <https-url>] [--events a,b] [--active|--inactive]");
+    const body = {};
+    if (args.url) {
+      if (!/^https:\/\//i.test(args.url)) die("the webhook address must start with https://");
+      body.url = String(args.url).trim();
+    }
+    if (args.events) body.events = String(args.events).split(",").map((x) => x.trim()).filter(Boolean);
+    if (args.activeOn && args.activeOff) die("pass --active or --inactive, not both.");
+    if (args.activeOn) body.active = true;
+    if (args.activeOff) body.active = false;
+    if (!Object.keys(body).length) die("nothing to change: give --url, --events, --active or --inactive");
+    const r = need(await request("PATCH", args.base, `${V1}/webhooks/${id}`, { key, body }), "webhooks set");
+    if (args.json) return console.log(JSON.stringify(r, null, 2));
+    return console.log(green("✓") + ` Webhook #${id} updated`);
+  }
+  if (sub === "test") {
+    const args = readFlags(rest);
+    const id = numericId(args._[0], "webhook id", "usage: argorant webhooks test <id>");
+    const r = need(await request("POST", args.base, `${V1}/webhooks/${id}/test`, { key, body: {} }), "webhooks test");
+    if (args.json) return console.log(JSON.stringify(r, null, 2));
+    return console.log(green("✓") + ` Test event${r.event ? ` (${r.event})` : ""} queued for webhook #${id}. See the result with \`argorant webhooks deliveries ${id}\`.`);
+  }
+  if (sub === "deliveries") {
+    const args = readFlags(rest, PAGE_FLAGS, { "--all": "all" });
+    const id = numericId(args._[0], "webhook id", "usage: argorant webhooks deliveries <id> [-n 25]");
+    const r = await fetchPages(args.base, key, `${V1}/webhooks/${id}/deliveries`, pageQuery(args, 25), "deliveries", "webhook deliveries", args.all);
+    if (args.json) return console.log(JSON.stringify(r, null, 2));
+    const rows = pickItems(r, "deliveries");
+    if (!rows.length) return console.log(dim("No deliveries yet."));
+    for (const d of rows) {
+      const tag = d.ok || d.status === "delivered" ? green(d.status || "delivered") : yellow(d.status || "pending");
+      console.log(`${dim(fmtDate(d.created_at))}  ${d.event || "-"}  ${tag}${d.attempts ? dim(` · ${d.attempts} attempt(s)`) : ""}${d.last_error ? dim(` · ${d.last_error}`) : ""}`);
+    }
+    pageFooter(r, "deliveries", `argorant webhooks deliveries ${id}`);
+    return;
+  }
+  if (sub === "rm" || sub === "delete" || sub === "remove") {
+    const args = readFlags(rest);
+    const id = numericId(args._[0], "webhook id", "usage: argorant webhooks rm <id> [--yes]");
+    if (!(await confirmOrDie(args, `Delete webhook #${id}? Events stop going to its address.`, `Deleting webhook #${id} needs a confirmation.`))) return;
+    const r = need(await request("DELETE", args.base, `${V1}/webhooks/${id}`, { key }), "webhooks rm");
+    if (args.json) return console.log(JSON.stringify(r, null, 2));
+    return console.log(green("✓") + ` Deleted webhook #${id}`);
+  }
+  die(`unknown webhooks subcommand: ${sub} (ls, add, set, test, deliveries, rm, events)`);
+}
+
+// ---- companies ----
+async function cmdCompanies(argv) {
+  const sub = argv[0] && !argv[0].startsWith("-") ? argv[0].toLowerCase() : "help";
+  const rest = argv.slice(1);
+  if (sub === "help") {
+    return console.log(`
+${bold("argorant companies")} count [filters]                         ${dim("free")}
+${bold("argorant companies")} search [filters] [-n 25] [--cursor <c>] [--all]   ${dim("free")}
+${bold("argorant companies")} people <company.com> [--title <role>] [-n 5]      ${dim("free; same as argorant company")}
+  filters: --industry --country --state --city --company --domain --keywords --technologies --employees 11-50,51-200 [free text]
+`);
+  }
+  const key = requireKey();
+  if (sub === "count") {
+    const args = readFlags(rest, COMPANY_FILTER_FLAGS);
+    const query = companyFilters(args);
+    const r = need(await request("GET", args.base, `${V1}/companies/count`, { key, query }), "companies count");
+    if (args.json) return console.log(JSON.stringify(r, null, 2));
+    return console.log(bold(Number(r.count || 0).toLocaleString()) + dim(" matching companies"));
+  }
+  if (sub === "search" || sub === "ls") {
+    const args = readFlags(rest, { ...COMPANY_FILTER_FLAGS, ...PAGE_FLAGS }, { "--all": "all" });
+    const query = { ...companyFilters(args), ...pageQuery(args, 10) };
+    const r = await fetchPages(args.base, key, `${V1}/companies/search`, query, "companies", "companies search", args.all);
+    if (args.json) return console.log(JSON.stringify(r, null, 2));
+    const rows = pickItems(r, "companies");
+    if (!rows.length) return console.log(dim("No matching companies."));
+    for (const co of rows) {
+      const name = co.company_name || co.company || co.name || co.company_domain || "-";
+      const where = [co.city, co.country].filter(Boolean).join(", ");
+      const size = co.employee_range || (co.employee_count ? `${Number(co.employee_count).toLocaleString()} people` : "");
+      console.log(`${bold(name)}  ${dim([co.company_domain || co.domain, co.industry, size, where].filter(Boolean).join(" · "))}`);
+    }
+    pageFooter(r, "companies", "argorant companies search ...");
+    return;
+  }
+  if (sub === "people") {
+    return cmdCompany(applySavedBase(parseArgs(rest)));
+  }
+  die(`unknown companies subcommand: ${sub} (count, search, people)`);
+}
+
+function companyFilters(args) {
+  const q = {};
+  for (const field of new Set(Object.values(COMPANY_FILTER_FLAGS))) if (args[field]) q[field] = args[field];
+  if (args._.length) q.q = [q.q, ...args._].filter(Boolean).join(" ");
+  return q;
+}
+
+// ---- lookup ----
+async function cmdLookup(argv) {
+  const raw = String(argv[0] || "").toLowerCase();
+  const kind = LOOKUP_ALIASES[raw] || raw;
+  if (!LOOKUP_KINDS.includes(kind)) {
+    die(`usage: argorant lookup ${LOOKUP_KINDS.join("|")} [text] [-n 20]\n  Free. Use the exact labels it returns in your filters (for example --industry "Software Development").`);
+  }
+  const args = readFlags(argv.slice(1), { "-n": "limit", "--limit": "limit" });
+  const key = requireKey();
+  const query = { limit: args.limit !== undefined ? parseLimit(args.limit, "--limit") : 20 };
+  if (args._.length) query.q = args._.join(" ");
+  const r = need(await request("GET", args.base, `${V1}/lookups/${kind}`, { key, query }), `lookup ${kind}`);
+  if (args.json) return console.log(JSON.stringify(r, null, 2));
+  const rows = pickItems(r, "suggestions").length ? pickItems(r, "suggestions") : pickItems(r, kind);
+  if (!rows.length) return console.log(dim(`No ${kind} match${query.q ? ` "${query.q}"` : ""}.`));
+  for (const s of rows) {
+    const label = typeof s === "string" ? s : s.label ?? s.value ?? s.name;
+    const count = typeof s === "object" && s ? s.count : undefined;
+    console.log(`${bold(label)}${count !== undefined && count !== null ? dim(`  ${Number(count).toLocaleString()}`) : ""}`);
+  }
+}
+
 function money(cents, currency) {
   if (cents === null || cents === undefined) return "?";
   const sign = String(currency || "usd").toLowerCase() === "eur" ? "€" : "$";
@@ -2529,6 +3373,13 @@ ${bold("COMMANDS")}
   ${cyan("inboxes")} quote | order | status | renewal  New mailboxes on new domains ${dim("(saved card or payment link)")}
   ${cyan("inbox")} list | read | reply | forward | classify   Replies across campaigns; answer in-thread or forward
   ${cyan("blocklist")} list | add | remove       Addresses and domains never contacted
+  ${cyan("account")}                    Plan, credits, request limit, campaign emails ${dim("(free)")}
+  ${cyan("lists")} ls | create | show | people | rename | rm | export   Saved lists ${dim("(argorant lists help)")}
+  ${cyan("exports")} ls | status | download    Your exports, a page at a time ${dim("(free)")}
+  ${cyan("companies")} count | search | people   Companies that match your filters ${dim("(free)")}
+  ${cyan("lookup")} industries | countries | keywords | technologies | titles [text]   Exact filter labels ${dim("(free)")}
+  ${cyan("credits")} packs | quote | buy | purchases   Buy credit packs ${dim("(asks first; saved card or payment link)")}
+  ${cyan("webhooks")} ls | add | set | test | deliveries | rm   Get events sent to your server ${dim("(Pro plan and up)")}
 
 ${bold("FILTERS")}
   --keywords <k>     Comma = OR. The widest, most reliable filter - prefer it
@@ -2551,16 +3402,23 @@ ${bold("OPTIONS")}
                      10 credits per phone number returned, nothing if none is found;
                      numbers you already unlocked are free. From the Pro plan.
       --max-credits <n>  Credit cap for a \`find --file\` job (it pauses at the cap)
+      --cursor <c>   Next page of a list (printed under each page); --all reads every page
+      --idempotency-key <k>   Your own key for this command's writes, so running it
+                     again replays the first answer instead of doing the work twice
+                     (by default every write gets a fresh key)
       --grade <g>    valid (default) or valid-plus-catchall - which deliverable
                      grade to include on reveal/export. You only ever pay for
                      deliverable contacts; this is the one grade distinction
                      exposed anywhere. ${dim("(coming soon - currently a no-op; see docs)")}
 
 ${bold("NON-INTERACTIVE USE")} ${dim("(agents, CI, pipes)")}
-  ${red("reveal, export, verify --file, and find SPEND CREDITS WITHOUT A PROMPT")} whenever
+  ${red("reveal, export, lists export, verify --file, and find SPEND CREDITS WITHOUT A PROMPT")} whenever
   stdin is not a TTY, or when --yes / --json is passed. The confirmation is a
   convenience for humans at a terminal, never a safety net. Check your -n.
   A single \`find\` never asks: each lookup costs at most 1 credit.
+  \`credits buy\`, \`lists rm\` and \`webhooks rm\` never run without a yes: at a
+  terminal they ask, anywhere else they need --yes.
+  Errors print a request id. Quote it if you contact support.
 
 ${bold("EXIT CODES")}
   0 ok   ·   1 error   ·   2 not authenticated   ·   3 forbidden (missing scope)
@@ -2583,26 +3441,51 @@ ${bold("EXAMPLES")}
   ${p} verify --file my-list.csv -o verified.csv
   ${p} find "Patrick Collison" --domain stripe.com
   ${p} find --file people.csv -o found.csv --max-credits 200
+  ${p} lookup industries soft
+  ${p} lists create --name "DACH CFOs" --title CFO --country Germany,Austria,Switzerland
+  ${p} lists export 1240 -n 500 -o cfos.csv
+  ${p} credits buy 5000
+  ${p} webhooks add https://example.com/hooks/argorant --events reply.received,reply.positive
 
   Docs: ${cyan("https://argorant.com/docs/cli")}
 `);
 }
 
+// Commands with their own flag vocabulary (readFlags), never the generic
+// filter parser. `list` with a 0.13.0 subcommand goes to `lists`.
+const OWN_FLAG_COMMANDS = {
+  campaigns: (a) => cmdCampaigns(a),
+  campaign: (a) => cmdCampaigns(a),
+  inboxes: (a) => cmdInboxes(a),
+  mailboxes: (a) => cmdInboxes(a),
+  inbox: (a) => cmdInboxThreads(a),
+  unibox: (a) => cmdInboxThreads(a),
+  blocklist: (a) => cmdBlocklist(a),
+  find: (a) => cmdFind(a),
+  account: (a) => cmdAccount(a),
+  lists: (a) => cmdLists(a),
+  exports: (a) => cmdExports(a),
+  credits: (a) => cmdCredits(a),
+  webhooks: (a) => cmdWebhooks(a),
+  webhook: (a) => cmdWebhooks(a),
+  companies: (a) => cmdCompanies(a),
+  lookup: (a) => cmdLookup(a),
+  lookups: (a) => cmdLookup(a),
+};
+const LISTS_SUBCOMMANDS = new Set(["ls", "people", "items", "rename", "rm", "delete", "remove", "export", "show", "get", "help"]);
+
 async function main() {
-  const argv = process.argv.slice(2);
+  const argv = takeIdempotencyFlag(process.argv.slice(2));
   const cmd = argv[0];
   if (!cmd || cmd === "help" || cmd === "--help" || cmd === "-h") return help();
   if (cmd === "version" || cmd === "--version" || cmd === "-v") return console.log(VERSION);
   // `campaigns` and `find` have their own flag vocabulary (--step, --count, --first, --max-credits, ...)
   // handled by readFlags - it never goes through the generic filter parser
   // below, which would reject those flags as unknown.
-  if (cmd === "campaigns" || cmd === "campaign" || cmd === "inboxes" || cmd === "mailboxes" || cmd === "inbox" || cmd === "unibox" || cmd === "blocklist" || cmd === "find") {
+  const own = OWN_FLAG_COMMANDS[cmd] || (cmd === "list" && LISTS_SUBCOMMANDS.has(String(argv[1] || "").toLowerCase()) ? OWN_FLAG_COMMANDS.lists : null);
+  if (own) {
     try {
-      if (cmd.startsWith("campaign")) await cmdCampaigns(argv.slice(1));
-      else if (cmd === "find") await cmdFind(argv.slice(1));
-      else if (cmd === "blocklist") await cmdBlocklist(argv.slice(1));
-      else if (cmd === "inbox" || cmd === "unibox") await cmdInboxThreads(argv.slice(1));
-      else await cmdInboxes(argv.slice(1));
+      await own(argv.slice(1));
     } catch (e) {
       die(e && e.message ? e.message : String(e));
     }
@@ -2632,4 +3515,14 @@ async function main() {
   }
 }
 
-main();
+if (require.main === module) {
+  main();
+} else {
+  // Loaded by the offline tests (scripts/test-unit.mjs): nothing runs, the
+  // helpers are handed out.
+  module.exports = {
+    parseArgs, readFlags, flagValue, parseLimit, takeIdempotencyFlag, nextIdempotencyKey, isV1Write, IDEM,
+    errorMessage, errorCode, requestIdOf, detailMsg, need, EXIT, request, pageQuery, pickItems, fetchPages, retryWaitSeconds, RATE_RETRY,
+    companyFilters, numericId, fmtPrice, packLine, quoteLines, LOOKUP_KINDS, OWN_FLAG_COMMANDS, VERSION,
+  };
+}