argorant 0.12.0 → 0.14.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(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 || {};
+  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);
+  }
+  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 || [];
 }
 
@@ -1308,6 +1460,89 @@ async function campaignsEmails(argv) {
   console.log(green("✓") + ` Saved ${(r.emails || emails).length} email(s) for ${dim(campaignId)}`);
 }
 
+// subsequences: follow-ups a reply keyword starts (GET / POST /api/v1/campaigns/{id}/subsequences).
+// The server replaces the whole set: subsequences left out are deleted with anyone still in them,
+// so `set` asks before it drops one that still has people in progress (-y skips the question).
+const SUBSEQUENCES_USAGE =
+  "usage: argorant campaigns subsequences list <campaign>\n" +
+  "   or: argorant campaigns subsequences set <campaign> --file subsequences.json [-y]\n" +
+  "   or: argorant campaigns subsequences clear <campaign> [-y]\n" +
+  '  subsequences.json: [{"name":"Interested","keywords":["interested","yes"],"emails":[{"body":"...","delay_days":0},{"body":"...","delay_days":3}]}]\n' +
+  "  Up to 5 subsequences, 1 to 10 keywords and 1 to 8 emails each. Email 1 defaults to the subject 'Re: {{thread_subject}}'.\n" +
+  "  Keywords also count in capitals, as a plural, with a small typo or inside a short sentence.\n" +
+  "  'not interested' and replies that ask to stop never start one.";
+
+function readSubsequencesFile(text, source) {
+  let data;
+  try { data = JSON.parse(text); } catch (e) { die(`${source}: not valid JSON (${e.message})`); }
+  const items = Array.isArray(data) ? data : data && Array.isArray(data.subsequences) ? data.subsequences : null;
+  if (!items) die(`${source}: expected a list of subsequences (or {"subsequences": [...]})`);
+  if (items.length > 5) die(`${source}: a campaign can have up to 5 subsequences (got ${items.length})`);
+  return items.map((item, i) => {
+    if (!item || typeof item !== "object" || Array.isArray(item)) die(`${source}: subsequence ${i + 1} is not an object`);
+    const keywords = typeof item.keywords === "string" ? item.keywords.split(",") : item.keywords;
+    if (!Array.isArray(keywords) || !keywords.some((k) => String(k || "").trim())) die(`${source}: subsequence ${i + 1} needs at least one keyword`);
+    const emails = item.emails || item.steps;
+    if (!Array.isArray(emails) || !emails.length) die(`${source}: subsequence ${i + 1} needs at least one email`);
+    const out = { name: item.name, keywords: keywords.map((k) => String(k).trim()).filter(Boolean), emails };
+    if (item.id) out.id = item.id;
+    return out;
+  });
+}
+
+function printSubsequences(r) {
+  const subs = r.subsequences || [];
+  console.log(dim(`Stop on reply: ${r.stop_on_reply === false ? "off" : "on"}`));
+  if (!subs.length) return console.log(dim("No subsequences. Add them with `argorant campaigns subsequences set <campaign> --file subsequences.json`."));
+  subs.forEach((s, i) => {
+    const st = s.stats || {};
+    console.log(`${bold(`${i + 1}. ${s.name}`)}  ${dim(s.id || "")}  ${s.status || ""}`);
+    console.log(`   keywords: ${(s.keywords || []).join(", ")}`);
+    console.log(`   emails: ${(s.steps || []).length}  ${dim(`in progress ${st.in_progress || 0}  replied ${st.replied || 0}  finished ${st.finished || 0}  sent ${st.emails_sent || 0}`)}`);
+    for (const step of s.steps || []) {
+      const preview = String(step.body || "").replace(/\s+/g, " ").slice(0, 70);
+      console.log(dim(`     ${step.step_number}. +${step.delay_days || 0}d  ${step.subject || "(same thread)"}  ${preview}`));
+    }
+  });
+}
+
+async function campaignsSubsequences(argv) {
+  const sub = argv[0];
+  if (!["list", "get", "set", "clear"].includes(sub)) die(SUBSEQUENCES_USAGE);
+  const key = requireKey();
+  const args = readFlags(argv.slice(1), { "--file": "file" });
+  const identifier = args._[0];
+  if (!identifier) die(SUBSEQUENCES_USAGE);
+  const campaignId = await resolveCampaign(args.base, key, identifier);
+  const route = `/api/v1/campaigns/${campaignId}/subsequences`;
+  if (sub === "list" || sub === "get") {
+    const r = need(await request("GET", args.base, route, { key }), "campaigns subsequences");
+    if (args.json) return console.log(JSON.stringify(r, null, 2));
+    return printSubsequences(r);
+  }
+  let items = [];
+  if (sub === "set") {
+    if (!args.file) die(SUBSEQUENCES_USAGE);
+    const text = args.file === "-" ? await readStdin() : (() => { try { return fs.readFileSync(args.file, "utf8"); } catch { die(`cannot read file: ${args.file}`); } })();
+    items = readSubsequencesFile(text, args.file === "-" ? "stdin" : args.file);
+  }
+  // What the replace would drop, and who is still inside it.
+  const current = need(await request("GET", args.base, route, { key }), "campaigns subsequences");
+  const keptIds = new Set(items.map((i) => i.id).filter(Boolean));
+  const dropped = (current.subsequences || []).filter((s) => !keptIds.has(s.id));
+  const busy = dropped.filter((s) => ((s.stats || {}).in_progress || 0) > 0);
+  if (dropped.length && !args.yes) {
+    const who = busy.length ? ` (${busy.map((s) => `${s.name}: ${s.stats.in_progress} in progress`).join(", ")})` : "";
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const ok = await new Promise((r) => rl.question(`This removes ${dropped.length} subsequence(s)${who}, with anyone still in them. Continue? [y/N] `, (a) => { rl.close(); r(/^y/i.test(a)); }));
+    if (!ok) return console.log(dim("aborted"));
+  }
+  const r = need(await request("POST", args.base, route, { key, body: { subsequences: items } }), "campaigns subsequences set");
+  if (args.json) return console.log(JSON.stringify(r, null, 2));
+  console.log(green("✓") + ` Saved ${(r.subsequences || []).length} subsequence(s) for ${dim(campaignId)}`);
+  printSubsequences(r);
+}
+
 // senders: which connected mailboxes send this campaign.
 async function campaignsSenders(argv) {
   const sub = argv[0];
@@ -1603,10 +1838,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 +1862,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 +1877,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 +1956,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)}`);
@@ -1757,6 +1995,9 @@ ${bold("USAGE")}
                 --gap 60-120 --unsubscribe|--no-unsubscribe --start YYYY-MM-DD --tags a,b --name "<n>"
   ${p} emails set <campaign> --file emails.json
   ${p} emails set <campaign> --step <n> --subject "..." (--body-file <path> | --body <text|->) [--delay-days <d>]
+  ${p} subsequences list <campaign>
+  ${p} subsequences set <campaign> --file subsequences.json [-y]   ${dim("reply keywords start follow-ups in the same thread")}
+  ${p} subsequences clear <campaign> [-y]
   ${p} leads add <campaign> --list <list-id> | --csv <file> [--include-catch-all]
   ${p} leads list <campaign> [--status replied] [--q text] [-n 50]
   ${p} leads remove <campaign> <email>
@@ -1774,6 +2015,10 @@ ${bold("USAGE")}
   ${bold("argorant inboxes")} set <mailbox> [--daily-limit 40] [--warmup|--no-warmup] [--active|--inactive] [--timezone <tz>]
   ${bold("argorant inboxes")} disconnect <mailbox>
   ${bold("argorant inboxes")} connect-google --admin <admin@yourdomain.com> [--emails a,b | --all]
+  ${bold("argorant inboxes")} connect-smtp --email <address> --preset <key> [--name "Sender"] [--password-env NAME]   ${dim("any provider; --smtp-host/--imap-host without a preset")}
+  ${bold("argorant inboxes")} connect-smtp --csv mailboxes.csv   ${dim("many at once, 25 per request, a result per row")}
+  ${bold("argorant inboxes")} test-smtp --email <address> --preset <key>   ${dim("checks sending and reading replies, saves nothing")}
+  ${bold("argorant inboxes")} presets   ${dim("provider keys for --preset (zoho, fastmail, yahoo, icloud, ...)")}
   ${bold("argorant inboxes")} endings   ${dim("the domain endings on offer (com, net, org, co, sbs, biz, info)")}
   ${bold("argorant inboxes")} suggest <website|brand> [--ending com] [-n 20]   ${dim("free domain names with prices")}
   ${bold("argorant inboxes")} quote --mailboxes 100 [--company acme.com] [--domains a.com,b.com] [--currency usd|eur] [--billing month|quarter]
@@ -1821,6 +2066,8 @@ async function cmdCampaigns(argv) {
     replies: campaignsReplies,
     analytics: campaignsAnalytics,
     emails: campaignsEmails,
+    subsequences: campaignsSubsequences,
+    subsequence: campaignsSubsequences,
     steps: campaignsSteps,
     senders: campaignsSenders,
     inboxes: campaignsInboxes,
@@ -1842,10 +2089,10 @@ 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."));
+    if (!rows.length) return console.log(dim("No mailboxes connected yet. Connect Google Workspace with `argorant inboxes connect-google --admin ...`, any other provider with `argorant inboxes connect-smtp --email ... --preset ...`, or Microsoft 365 in the app."));
     for (const i of rows) {
       console.log(`${bold(i.email)}  ${dim(i.name || "")}`);
       console.log(dim(`  ${i.provider} · ${i.status}${i.health ? ` · ${i.health}` : ""} · today ${i.sent_today || 0}/${i.daily_limit || "?"}`));
@@ -2052,7 +2299,267 @@ async function cmdInboxes(argv) {
     if (args.json) return console.log(JSON.stringify(r, null, 2));
     return console.log(green("✓") + ` Bundle ${target} cancelled${r.existing ? dim(" (already)") : ""}`);
   }
-  die(`unknown inboxes subcommand: ${sub} (list, set, disconnect, connect-google, endings, suggest, quote, order, status, renewal, cancel-bundle)`);
+  if (sub === "presets") {
+    const args = readFlags(argv.slice(1));
+    const r = need(await request("GET", args.base, "/api/v1/inboxes/smtp/presets", { key }), "inboxes presets");
+    if (args.json) return console.log(JSON.stringify(r, null, 2));
+    for (const p of r.presets || []) {
+      const out = p.smtp_host ? `${p.smtp_host}:${p.smtp_port} ${p.smtp_secure}` : "you enter the servers";
+      const inn = p.imap_host ? `${p.imap_host}:${p.imap_port} ${p.imap_secure}` : "";
+      console.log(`${bold(p.key.padEnd(14))} ${p.label}`);
+      console.log(dim(`  sending ${out}${inn ? `  ·  reading replies ${inn}` : ""}`));
+      if (p.hint) console.log(dim(`  ${p.hint}`));
+    }
+    return;
+  }
+  if (sub === "test-smtp" || sub === "connect-smtp") return cmdSmtpMailbox(sub, argv.slice(1), key);
+  die(`unknown inboxes subcommand: ${sub} (list, set, disconnect, connect-google, connect-smtp, test-smtp, presets, endings, suggest, quote, order, status, renewal, cancel-bundle)`);
+}
+
+// ---- mailboxes from any email provider (SMTP sending + IMAP replies), 0.14.0 ----
+// The password is never taken on the command line (shell history): --password-env NAME, the
+// ARGORANT_MAILBOX_PASSWORD variable, a hidden prompt, or the CSV file for many mailboxes.
+const SMTP_FLAGS = {
+  "--email": "email", "--name": "name", "--preset": "preset",
+  "--smtp-host": "smtpHost", "--smtp-port": "smtpPort", "--smtp-security": "smtpSecurity", "--smtp-user": "smtpUser",
+  "--imap-host": "imapHost", "--imap-port": "imapPort", "--imap-security": "imapSecurity", "--imap-user": "imapUser",
+  "--daily-limit": "dailyLimit", "--password-env": "passwordEnv", "--imap-password-env": "imapPasswordEnv", "--csv": "csv",
+};
+const SMTP_BULK_CHUNK = 25;
+const SMTP_USAGE = `usage: argorant inboxes connect-smtp --email <address> (--preset <key> | --smtp-host <h> --smtp-port <p> --imap-host <h>)
+         [--name "Sender Name"] [--smtp-security starttls|ssl|none] [--smtp-user <u>] [--imap-port 993]
+         [--imap-security ssl|starttls|none] [--imap-user <u>] [--daily-limit 25] [--password-env NAME] [--imap-password-env NAME]
+       argorant inboxes connect-smtp --csv mailboxes.csv
+       argorant inboxes test-smtp   (same flags as connect-smtp for one mailbox; saves nothing)
+       argorant inboxes presets     (the provider keys for --preset)`;
+// CSV header -> field (lower case, spaces and dashes as underscores).
+const SMTP_CSV_COLUMNS = {
+  email: "email", sender_name: "sender_name", name: "sender_name", display_name: "sender_name", preset: "preset",
+  smtp_host: "smtp_host", smtp_port: "smtp_port", smtp_security: "smtp_security", smtp_secure: "smtp_security",
+  smtp_username: "smtp_username", smtp_user: "smtp_username", smtp_password: "smtp_password", password: "smtp_password",
+  imap_host: "imap_host", imap_port: "imap_port", imap_security: "imap_security", imap_secure: "imap_security",
+  imap_username: "imap_username", imap_user: "imap_username", imap_password: "imap_password", daily_limit: "daily_limit",
+};
+
+function normalizeSecurity(value, what) {
+  if (value === undefined || value === null || String(value).trim() === "") return undefined;
+  const v = String(value).trim().toLowerCase().replace(/[\s_-]+/g, "");
+  if (["ssl", "ssl/tls", "tls", "ssltls", "implicit"].includes(v)) return "ssl";
+  if (["starttls", "start"].includes(v)) return "starttls";
+  if (["none", "no", "off", "plain"].includes(v)) return "none";
+  throw new Error(`${what} must be ssl, starttls or none`);
+}
+function parsePort(value, what) {
+  if (value === undefined || value === null || String(value).trim() === "") return undefined;
+  const n = Number(String(value).trim());
+  if (!Number.isInteger(n) || n < 1 || n > 65535) throw new Error(`${what} must be a port number from 1 to 65535`);
+  return n;
+}
+function parseDailyLimit(value) {
+  if (value === undefined || value === null || String(value).trim() === "") return undefined;
+  const n = Number(String(value).trim());
+  if (!Number.isInteger(n) || n < 1 || n > 10000) throw new Error("daily limit must be a whole number from 1 to 10000");
+  return n;
+}
+// One mailbox in the API's field names; empty values are left out (the server fills the defaults).
+function mailboxBody(f) {
+  const body = {};
+  const put = (k, v) => { if (v !== undefined && v !== null && String(v) !== "") body[k] = v; };
+  put("email", f.email ? String(f.email).trim().toLowerCase() : undefined);
+  put("display_name", f.sender_name ? String(f.sender_name).trim() : undefined);
+  put("preset", f.preset ? String(f.preset).trim().toLowerCase() : undefined);
+  put("smtp_host", f.smtp_host ? String(f.smtp_host).trim() : undefined);
+  put("smtp_port", parsePort(f.smtp_port, "smtp port"));
+  put("smtp_secure", normalizeSecurity(f.smtp_security, "smtp security"));
+  put("smtp_username", f.smtp_username ? String(f.smtp_username).trim() : undefined);
+  put("smtp_password", f.smtp_password);
+  put("imap_host", f.imap_host ? String(f.imap_host).trim() : undefined);
+  put("imap_port", parsePort(f.imap_port, "imap port"));
+  put("imap_secure", normalizeSecurity(f.imap_security, "imap security"));
+  put("imap_username", f.imap_username ? String(f.imap_username).trim() : undefined);
+  put("imap_password", f.imap_password);
+  put("daily_limit", parseDailyLimit(f.daily_limit));
+  if (!body.email || !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(body.email)) throw new Error("needs a valid email address");
+  if (!body.smtp_password) throw new Error("needs a password");
+  if (!body.preset && !(body.smtp_host && body.smtp_port && body.imap_host)) {
+    throw new Error("needs a preset, or the sending server, its port and the server for reading replies");
+  }
+  return body;
+}
+
+// RFC 4180 CSV: quoted fields, doubled quotes, commas and line breaks inside quotes, CRLF, a BOM.
+function parseCsv(text) {
+  const rows = [];
+  let row = [], field = "", quoted = false, i = 0;
+  const src = String(text || "").replace(/^\uFEFF/, "");
+  while (i < src.length) {
+    const ch = src[i];
+    if (quoted) {
+      if (ch === '"') {
+        if (src[i + 1] === '"') { field += '"'; i += 2; continue; }
+        quoted = false; i += 1; continue;
+      }
+      field += ch; i += 1; continue;
+    }
+    if (ch === '"' && field === "") { quoted = true; i += 1; continue; }
+    if (ch === ",") { row.push(field); field = ""; i += 1; continue; }
+    if (ch === "\r" && src[i + 1] === "\n") { i += 1; continue; }
+    if (ch === "\n" || ch === "\r") { row.push(field); rows.push(row); row = []; field = ""; i += 1; continue; }
+    field += ch; i += 1;
+  }
+  if (field !== "" || row.length) { row.push(field); rows.push(row); }
+  return rows.filter((r) => r.some((v) => String(v).trim() !== ""));
+}
+
+// CSV text -> { rows: [{ line, body }], invalid: [{ line, email, message }], ignored: [column] }
+function mailboxesFromCsv(text) {
+  const table = parseCsv(text);
+  if (!table.length) throw new Error("the file is empty");
+  const header = table[0].map((h) => String(h).trim().toLowerCase().replace(/[\s-]+/g, "_"));
+  const fields = header.map((h) => SMTP_CSV_COLUMNS[h] || null);
+  if (!fields.includes("email")) throw new Error("the file needs an email column (see: argorant inboxes connect-smtp --help)");
+  const ignored = header.filter((h, i) => h && !fields[i]);
+  const rows = [], invalid = [];
+  table.slice(1).forEach((cells, index) => {
+    const line = index + 2;
+    const f = {};
+    fields.forEach((name, i) => { if (name && cells[i] !== undefined && String(cells[i]).trim() !== "") f[name] = name.endsWith("password") ? String(cells[i]) : String(cells[i]).trim(); });
+    try {
+      rows.push({ line, body: mailboxBody(f) });
+    } catch (e) {
+      invalid.push({ line, email: f.email || "", status: "invalid", message: e.message });
+    }
+  });
+  return { rows, invalid, ignored };
+}
+
+function promptSecret(question) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout, terminal: true });
+    let muted = false;
+    rl._writeToOutput = (str) => { if (!muted) rl.output.write(str); };
+    rl.question(question, (answer) => { rl.close(); process.stdout.write("\n"); resolve(answer); });
+    muted = true;
+  });
+}
+async function mailboxPassword(args, which) {
+  const envFlag = which === "imap" ? args.imapPasswordEnv : args.passwordEnv;
+  if (envFlag) {
+    const v = process.env[envFlag];
+    if (!v) die(`the environment variable ${envFlag} is empty or not set.`);
+    return v;
+  }
+  if (which === "imap") return undefined;   // the server uses the sending password
+  if (process.env.ARGORANT_MAILBOX_PASSWORD) return process.env.ARGORANT_MAILBOX_PASSWORD;
+  if (process.stdin.isTTY) {
+    const v = await promptSecret("Mailbox password or app password (not shown): ");
+    if (!v) die("no password given.");
+    return v;
+  }
+  die("give the mailbox password with --password-env NAME or the ARGORANT_MAILBOX_PASSWORD variable.");
+}
+
+function printSignInTest(t) {
+  if (!t || typeof t !== "object") return;
+  for (const [leg, label] of [["smtp", "sending"], ["imap", "reading replies"]]) {
+    const r = t[leg];
+    if (!r) continue;
+    console.log(`  ${r.works ? green("✓") : red("✗")} ${label.padEnd(16)}${r.message || r.result || ""}`);
+  }
+}
+function printBulkResults(results) {
+  const w = Math.min(40, Math.max(5, ...results.map((r) => String(r.email || "").length)));
+  for (const r of results) {
+    const mark = r.status === "connected" ? green("✓ connected") : r.status === "skipped" ? yellow("- skipped  ") : red("✗ " + (r.status === "invalid" ? "invalid  " : "failed   "));
+    console.log(`${String(r.line).padStart(4)}  ${String(r.email || "").padEnd(w)}  ${mark}  ${r.status === "connected" ? "" : (r.message || "")}`);
+  }
+}
+
+async function cmdSmtpMailbox(sub, argv, key) {
+  if (argv.includes("--password") || argv.some((a) => a.startsWith("--password="))) {
+    die("for safety the password is never taken on the command line. Use --password-env NAME, the ARGORANT_MAILBOX_PASSWORD variable, or type it when asked.");
+  }
+  if (argv.includes("--help") || argv.includes("-h")) return console.log(SMTP_USAGE + `
+
+  CSV columns: email, sender_name, preset, smtp_host, smtp_port, smtp_security, smtp_username, smtp_password,
+               imap_host, imap_port, imap_security, imap_username, imap_password, daily_limit
+  Each row needs email, smtp_password (or password), and a preset or smtp_host + smtp_port + imap_host.
+  Empty columns take the defaults: username = email, reading replies uses the sending sign-in, port 993, 25 a day.
+  Send on port 587 (starttls). If you give 465, Argorant tries 587 and saves 587 when it works.
+  Rows go up 25 at a time; each row says whether it connected or what to fix. Exit 1 when any row did not connect.`);
+  const args = readFlags(argv, SMTP_FLAGS);
+  if (args.csv) {
+    if (sub !== "connect-smtp") die("--csv works with connect-smtp.");
+    let text;
+    try { text = fs.readFileSync(args.csv, "utf8"); } catch (e) { die(`cannot read ${args.csv}: ${e.message}`); }
+    let parsed;
+    try { parsed = mailboxesFromCsv(text); } catch (e) { die(`${args.csv}: ${e.message}`); }
+    if (parsed.ignored.length && !args.json) warn(`ignoring unknown column${parsed.ignored.length === 1 ? "" : "s"}: ${parsed.ignored.join(", ")}`);
+    const results = [...parsed.invalid];
+    const totals = { connected: 0, failed: 0, skipped: 0, invalid: parsed.invalid.length };
+    for (let i = 0; i < parsed.rows.length; i += SMTP_BULK_CHUNK) {
+      const chunk = parsed.rows.slice(i, i + SMTP_BULK_CHUNK);
+      if (!args.json) process.stderr.write(dim(`checking ${i + 1} to ${i + chunk.length} of ${parsed.rows.length}...\n`));
+      const res = await request("POST", args.base, "/api/v1/inboxes/smtp/bulk", { key, body: { mailboxes: chunk.map((r) => r.body) } });
+      if (res.status >= 400) {
+        if (results.length && !args.json) printBulkResults(results.sort((a, b) => a.line - b.line));
+        need(res, "inboxes connect-smtp --csv");
+      }
+      const r = res.json || {};
+      for (const item of r.results || []) {
+        const source = chunk[Number(item.row) - 1];
+        results.push({ line: source ? source.line : null, email: item.email || (source && source.body.email), status: item.status, result: item.result, message: item.message });
+        if (item.status in totals) totals[item.status] += 1;
+      }
+    }
+    results.sort((a, b) => (a.line || 0) - (b.line || 0));
+    if (totals.failed || totals.invalid || totals.skipped) process.exitCode = 1;
+    if (args.json) return console.log(JSON.stringify({ ...totals, results }, null, 2));
+    printBulkResults(results);
+    const parts = [`${totals.connected} connected`];
+    if (totals.failed) parts.push(`${totals.failed} could not sign in`);
+    if (totals.skipped) parts.push(`${totals.skipped} skipped`);
+    if (totals.invalid) parts.push(`${totals.invalid} with missing or wrong columns`);
+    return console.log(`\n${parts.join(", ")}.`);
+  }
+  if (!args.email) die(SMTP_USAGE);
+  const password = await mailboxPassword(args, "smtp");
+  const imapPassword = await mailboxPassword(args, "imap");
+  let body;
+  try {
+    body = mailboxBody({
+      email: args.email, sender_name: args.name, preset: args.preset, smtp_host: args.smtpHost, smtp_port: args.smtpPort,
+      smtp_security: args.smtpSecurity, smtp_username: args.smtpUser, smtp_password: password, imap_host: args.imapHost,
+      imap_port: args.imapPort, imap_security: args.imapSecurity, imap_username: args.imapUser, imap_password: imapPassword,
+      daily_limit: args.dailyLimit,
+    });
+  } catch (e) {
+    die(`${e.message}.\n${SMTP_USAGE}`);
+  }
+  if (sub === "test-smtp") {
+    delete body.display_name; delete body.daily_limit;
+    const r = need(await request("POST", args.base, "/api/v1/inboxes/smtp/test", { key, body }), "inboxes test-smtp");
+    if (!r.works) process.exitCode = 1;
+    if (args.json) return console.log(JSON.stringify(r, null, 2));
+    console.log(`${r.works ? green("✓") : red("✗")} ${body.email}  ${r.message || ""}`);
+    printSignInTest(r);
+    if (r.works) console.log(dim(`Connect it:  argorant inboxes connect-smtp ${process.argv.slice(4).join(" ")}`.trim()));
+    return;
+  }
+  const res = await request("POST", args.base, "/api/v1/inboxes/smtp", { key, body });
+  if (res.status === 422 && errorCode(res.json) === "sign_in_failed") {
+    const details = (res.json && res.json.error && res.json.error.details) || {};
+    process.exitCode = 1;
+    if (args.json) return console.log(JSON.stringify({ connected: false, message: errorMessage(res.json), test: details.test || null }, null, 2));
+    console.log(`${red("✗")} ${body.email} was not connected. ${errorMessage(res.json) || ""}`);
+    printSignInTest(details.test);
+    return;
+  }
+  const r = need(res, "inboxes connect-smtp");
+  if (args.json) return console.log(JSON.stringify(r, null, 2));
+  const i = r.inbox || {};
+  console.log(green("✓") + ` Connected ${bold(i.email || body.email)}${i.daily_limit ? dim(`  ${i.daily_limit} a day`) : ""}`);
+  console.log(dim("It is in `argorant inboxes list` now and can be picked as a sender for any campaign."));
 }
 
 // =============================================================================
@@ -2134,13 +2641,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 +2993,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" ? "€" : "$";
@@ -2525,10 +3721,17 @@ ${bold("COMMANDS")}
   ${cyan("find")} status | download | resume | cancel <job_id>   Manage a find job ${dim("(free)")}
   ${cyan("find pricing")}               Finder prices, balance, limits ${dim("(free)")}
   ${cyan("campaigns")} ...                Email outreach: create, write, enroll, launch ${dim("(argorant campaigns help)")}
-  ${cyan("inboxes")} list | connect-google  Connected mailboxes; connect a Google Workspace
+  ${cyan("inboxes")} list | connect-google | connect-smtp | test-smtp   Connected mailboxes; connect Google Workspace or any provider
   ${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 +3754,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 +3793,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 +3867,15 @@ 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,
+    parseCsv, mailboxesFromCsv, mailboxBody, normalizeSecurity, SMTP_BULK_CHUNK,
+  };
+}