argorant 0.9.0 → 0.11.0

package/README.md

@@ -1,7 +1,8 @@
 # argorant
 
 Search, count, reveal, export, and verify B2B contacts from the Argorant
-database — from your terminal, scripts, or coding agent. No install required.
+database, and find work emails by name and company domain, from your
+terminal, scripts, or coding agent. No install required.
 
 ```sh
 npx argorant count "fintech CFOs in germany"
@@ -9,7 +10,7 @@ npx argorant count "fintech CFOs in germany"
 
 Company lookups, counts, and masked searches spend **zero contact credits on
 an active plan**. Reveals and exports draw on your Argorant workspace
-quota/credits — the same pool as the app, API, and MCP server.
+quota/credits - the same pool as the app, API, and MCP server.
 
 ## Authenticate
 
@@ -19,15 +20,15 @@ Create an API key at **app.argorant.com/profile** (API keys), then:
 npx argorant login            # paste your ag_live_ key (stored in ~/.argorant)
 ```
 
-Or set `ARGORANT_API_KEY=ag_live_…` in your environment — ideal for scripts,
+Or set `ARGORANT_API_KEY=ag_live_…` in your environment - ideal for scripts,
 CI, and agents.
 
 ## Commands
 
 | Command | What it does | Cost |
 | --- | --- | --- |
-| `login [key]` | Save an API key | — |
-| `logout` | Forget the saved key and base (`~/.argorant/config.json`) | — |
+| `login [key]` | Save an API key | - |
+| `logout` | Forget the saved key and base (`~/.argorant/config.json`) | - |
 | `whoami` | Account, scopes, daily quota | free |
 | `count "<query>"` | Count matching contacts | free |
 | `company <company.com> -n 5` | Count people at a company, split business-email coverage, preview masked roles | free |
@@ -40,13 +41,77 @@ CI, and agents.
 | `list create --name "<n>" [filters]` | Save a reusable filtered list (server counts it) | free |
 | `list status <id>` | A saved list's size and mode | free |
 | `verify <email>` / `verify --file emails.csv -o out.csv` | Verify your own addresses (verification pool; recent re-checks free) | pool |
-| `campaigns …` | Live outbound campaigns — **operator keys only**, see below | — |
+| `find "<first last>" --domain <d>` / `find --file people.csv -o found.csv` | Find a person's work email from a name and company domain, one or a whole list ([details](#find-emails)) | 1 credit found, 0.25 nothing found |
+| `find status \| download \| resume \| cancel <job_id>`, `find pricing` | Manage a find job; show prices, balance and limits | free |
+| `campaigns …` | Live outbound campaigns - **operator keys only**, see below | - |
 
 Exports above 50,000 rows are created as a multi-chunk batch: the CLI polls
 `export status --batch` for you and writes one file per chunk
 (`leads-part1.csv`, `leads-part2.csv`, …). The batch id is printed so you can
 re-download any time with `export download <batch_id> --batch`.
 
+## Find emails
+
+Give a name and the company's domain, get the person's work email.
+
+```sh
+npx argorant find "Jane Doe" --domain acme.com
+npx argorant find --first Jane --last Doe --domain acme.com
+# jane.doe@acme.com  ·  Confirmed  ·  confidence 95  ·  1 credit
+```
+
+Each lookup prints one line: the email (or `no email found`), its status, the
+confidence and what it cost. Statuses:
+
+| Status | Meaning | Cost |
+| --- | --- | --- |
+| Confirmed | Address found and confirmed | 1 credit |
+| Unconfirmed, catch-all domain | The domain accepts every address, so the best address is returned without confirmation | 1 credit |
+| Not found | No address found for this person | 0.25 credit |
+| No mail server | The domain does not receive email | free |
+| Try again later | No answer for this domain right now; run it again later | free |
+
+Invalid rows and every failed request (out of credits, limits, a busy
+server) are free too. A 0.25 charge takes one whole credit and keeps the rest
+as prepaid no-result lookups, which cover your next three misses. Run
+`argorant find pricing` for the live prices, your balance, prepaid lookups and
+limits.
+
+A whole list runs as a job. The file is a CSV with a header row and the
+columns `first_name`, `last_name` and `domain`; an optional `ref` column is
+passed through to the results:
+
+```sh
+npx argorant find --file people.csv -o found.csv --max-credits 200 --name "Q4 list"
+```
+
+The CLI prints the job id, shows progress (processed/total, found, charged)
+and saves the results CSV when the job is done (`argorant-found.csv` by
+default). Columns: `row, ref, first_name, last_name, domain, email, status,
+confirmed, confidence, credits_charged`. The output path is checked before the
+job is created. On a terminal the CLI asks first, showing the prices and the
+maximum charge; with `--yes`, `--json` or no TTY it starts right away.
+Duplicate rows are removed before anything is charged. `--max-credits` caps
+the job: it pauses at the cap instead of spending more.
+
+A job pauses when your credits run out, when it reaches `--max-credits`, at
+the daily limit, or when almost none of the recent lookups found anything. The
+CLI says why and still saves what was found so far. Ctrl-C only stops
+watching; the job keeps running.
+
+```sh
+argorant find status <job_id>                      # progress and counts
+argorant find download <job_id> -o found.csv       # the results CSV, any time
+argorant find resume <job_id> [--max-credits 300]  # continue a paused job
+argorant find cancel <job_id>                      # stop; rows not processed yet are not charged
+```
+
+Exit codes: a single `find` exits `1` when no email came back, so scripts can
+branch without parsing. A `find --file` job that pauses exits `5` when out of
+credits and `4` at the daily limit or when slowed down; a job that stops at
+your own `--max-credits` cap exits `0`. Errors use the codes below (`5` out of
+credits, `4` rate limit with the wait time in the message).
+
 ## Filters
 
 Combine free text with structured filters:
@@ -57,7 +122,7 @@ Combine free text with structured filters:
 --has-phone --has-linkedin --has-email --verified-only
 ```
 
-`--keywords` is the widest, most reliable filter (comma = OR) — prefer it over
+`--keywords` is the widest, most reliable filter (comma = OR) - prefer it over
 `--industry`. `--country`/`--geography` accept regions (Europe, EMEA, DACH,
 Nordics, APAC, LATAM, GCC…).
 
@@ -84,13 +149,14 @@ npx argorant company stripe.com --json
 npx argorant reveal "heads of procurement" --country Germany -n 25 --json --yes
 ```
 
-### Non-interactive behaviour — read this before scripting `reveal`/`export`
+### Non-interactive behaviour - read this before scripting `reveal`/`export`
 
-`reveal`, `export`, and `verify --file` ask for confirmation **only** when
-stdin is a TTY and neither `-y/--yes` nor `--json` was passed. In CI, in a
-pipe, or inside an agent loop there is **no prompt at all** — these commands
-spend credits immediately. The prompt is a convenience for humans at a
-terminal, never a safety net. Check your `-n` before you run them.
+`reveal`, `export`, `verify --file` and `find --file` ask for confirmation
+**only** when stdin is a TTY and neither `-y/--yes` nor `--json` was passed.
+In CI, in a pipe, or inside an agent loop there is **no prompt at all**, these
+commands spend credits immediately. A single `find` never asks; each lookup
+costs at most 1 credit. The prompt is a convenience for humans at a terminal,
+never a safety net. Check your `-n` and `--max-credits` before you run them.
 
 Related guardrails, so a mistake stays cheap:
 
@@ -108,9 +174,9 @@ Related guardrails, so a mistake stays cheap:
 | `0` | success |
 | `1` | generic error (bad usage, network, failed job) |
 | `2` | not authenticated (no key, or the key was rejected) |
-| `3` | forbidden — the key lacks the required scope |
+| `3` | forbidden - the key lacks the required scope |
 | `4` | rate limit or daily quota reached |
-| `5` | plan upgrade required (HTTP 402); the message carries the upgrade URL |
+| `5` | plan upgrade required or out of credits (HTTP 402); the message carries the upgrade URL |
 
 Exit `5` is deliberately distinct from `1`: an agent can tell "this account
 needs a paid plan" apart from "something broke".
@@ -153,18 +219,29 @@ argorant inboxes connect-google --admin admin@yourdomain.com --emails a@x.com,b@
 ```
 
 New mailboxes on their own new domains, ordered from the terminal. The quote shows every domain with its
-first-year and renewal price, the mailboxes and the total; the order returns a checkout link that you pay
-yourself. Nothing is bought before that payment, and setup starts once it is confirmed. Warm-up is included
-in every plan; switch it on per mailbox with `argorant inboxes set <mailbox> --warmup`.
+first-year and renewal price, the mailboxes, the total and how it is paid. When your workspace saved its card
+for API and agent purchases (you ticked that box when you paid an earlier order, and the setting in
+Settings > Billing is on), the order is charged to that card right away, within any limit you set there, and a
+receipt is emailed to the workspace. Otherwise the order returns a payment link that you pay yourself.
+Nothing is bought before the payment, and setup starts once it went through. Warm-up is included in every
+plan; switch it on per mailbox with `argorant inboxes set <mailbox> --warmup`.
+
+Domains can end in .com, .net, .org, .co, .sbs, .biz or .info (`argorant inboxes endings` prints the live list).
 
 ```
-argorant inboxes suggest acme.com                                  # free domain names with prices
+argorant inboxes suggest acme.com [--ending com]                   # free domain names with prices
 argorant inboxes quote --mailboxes 100 --company acme.com          # or --domains getacme.com,tryacme.co
-argorant inboxes order <quote-id> --senders "Elena Vaughn"         # asks first; prints the checkout link
-argorant inboxes status [<order-id>]                               # steps, domains, renewal prices, bundles
-argorant inboxes cancel-bundle <order-id> <bundle-id> [--keep-domains]   |   cancel-domain <order-id> <domain>
+argorant inboxes order <quote-id> --senders "Elena Vaughn"         # asks first; saved card or a payment link
+argorant inboxes order <quote-id> --senders "Elena Vaughn" --pay-with link   # always a payment link
+argorant inboxes status [<order-id>]                               # steps, domains, renewal, bundles
+argorant inboxes renewal <order-id> <domain> --off                 # Stop renewal (nothing is charged now)
+argorant inboxes renewal <order-id> <domain> --on                  # Turn renewal back on (billed shortly before it renews)
+argorant inboxes cancel-bundle <order-id> <bundle-id> --reason too_expensive [--note "..."] [--keep-domains]
 ```
 
+Cancel reasons: `too_expensive`, `not_sending_enough`, `deliverability`, `switching_provider`,
+`campaign_finished`, `other`. `cancel-domain` still works as the old name of `renewal --off`.
+
 `<campaign>` accepts an id or an unambiguous case-insensitive name prefix. Every address is verified before
 it is enrolled; only valid ones send unless `--include-catch-all`. Variables: `{{first_name}}`, `{{last_name}}`,
 `{{company}}`, `{{title}}`; spintax `{a|b}` varies phrasing. `--query "..."` filter enrollment stays available

package/bin/argorant.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 "use strict";
 
-// Argorant CLI — a thin, dependency-free wrapper over the Argorant REST API.
-// Search, count, reveal, export, and verify B2B contacts from the terminal.
+// Argorant CLI - a thin, dependency-free wrapper over the Argorant REST API.
+// Search, count, reveal, export, and verify B2B contacts, and find work emails, from the terminal.
 // Auth: an Argorant API key (ag_live_*) via `argorant login`, or ARGORANT_API_KEY.
 
 const crypto = require("crypto");
@@ -83,7 +83,7 @@ const VALUE_FLAGS = {
 };
 // Boolean filter flags (presence => "true"). --verified-only is positive intent
 // only (deliverable contacts); there is deliberately NO flag to query invalid or
-// any raw verification status — that is never exposed on any surface.
+// any raw verification status - that is never exposed on any surface.
 const BOOL_FLAGS = {
   "--has-phone": "has_phone",
   "--has-linkedin": "has_linkedin",
@@ -124,7 +124,7 @@ function warnGradeGap(scope) {
 // A value flag must be followed by an actual value. Silently swallowing the
 // NEXT FLAG (`search "CFO" --title --base http://…` → title="--base") or a
 // missing trailing value (→ undefined, dropped by request()) sends a request
-// the user never asked for — against the wrong host, with the wrong filters.
+// the user never asked for - against the wrong host, with the wrong filters.
 // Fail loud instead. "-" stays legal: it is the documented stdin sentinel.
 function flagValue(argv, i, flag) {
   const v = argv[i + 1];
@@ -134,7 +134,7 @@ function flagValue(argv, i, flag) {
   }
   return v;
 }
-// -n/--limit drives billed row counts on reveal/export — a typo must never
+// -n/--limit drives billed row counts on reveal/export - a typo must never
 // fall through to the default (a mistyped `-n` used to become a 1000-row
 // billed export).
 function parseLimit(raw, flag) {
@@ -252,7 +252,7 @@ function downloadTo(base, urlPath, key, dest) {
 // `detail` is a plain string on most endpoints, a structured object on some
 // (plan_required, campaign launch blockers, native-delivery readiness) and a
 // LIST of validation errors on any FastAPI 422. All three have to render as
-// something a human or an agent can read — never "[object Object]".
+// something a human or an agent can read - never "[object Object]".
 function detailMsg(detail) {
   if (detail == null) return null;
   if (typeof detail === "string") return detail;
@@ -292,7 +292,7 @@ function need(res, what) {
     const url = d.upgrade_url || d.url || "https://argorant.com/pricing";
     die(`${msg}${msg.includes(url) ? "" : `\nUpgrade: ${url}`}`, EXIT.UPGRADE);
   }
-  if (res.status === 403) die(detailMsg(detail) || `forbidden — your key lacks the scope for ${what}.`, EXIT.FORBIDDEN);
+  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 || {};
@@ -351,7 +351,7 @@ async function cmdLogin(args) {
   let key = args._[0];
   if (!key) key = await prompt("Paste your Argorant API key (ag_live_…): ", { hidden: true });
   if (!key) die("no key provided.");
-  if (!/^ag_(live|test)_/.test(key)) process.stderr.write(dim("note: keys normally start with ag_live_ — continuing anyway.\n"));
+  if (!/^ag_(live|test)_/.test(key)) process.stderr.write(dim("note: keys normally start with ag_live_ - continuing anyway.\n"));
   const res = await request("GET", args.base, "/api/mcp/account", { key });
   if (res.status === 428 && res.json?.detail?.error === "access_key_activation_required") {
     const url = res.json.detail.claim_url;
@@ -370,7 +370,7 @@ async function cmdLogin(args) {
 
 async function cmdLogout() {
   if (!fs.existsSync(CONFIG_PATH)) {
-    console.log(dim(`Nothing to do — no saved credentials at ${CONFIG_PATH}.`));
+    console.log(dim(`Nothing to do - no saved credentials at ${CONFIG_PATH}.`));
   } else {
     try {
       fs.unlinkSync(CONFIG_PATH);
@@ -380,7 +380,7 @@ async function cmdLogout() {
     console.log(green("✓") + ` Removed saved key and base from ${bold(CONFIG_PATH)}`);
   }
   if (process.env.ARGORANT_API_KEY) {
-    warn("ARGORANT_API_KEY is still set in this environment and takes precedence — unset it too.");
+    warn("ARGORANT_API_KEY is still set in this environment and takes precedence - unset it too.");
   }
 }
 
@@ -389,8 +389,8 @@ async function cmdWhoami(args) {
   const res = await request("GET", args.base, "/api/mcp/account", { key });
   const a = need(res, "whoami");
   if (args.json) return console.log(JSON.stringify(a, null, 2));
-  console.log(`${bold("Account")}  ${a.email || "—"} ${dim("(" + (a.role || "member") + ")")}`);
-  console.log(`${bold("Scopes")}   ${(a.scopes || []).join(", ") || "—"}`);
+  console.log(`${bold("Account")}  ${a.email || "-"} ${dim("(" + (a.role || "member") + ")")}`);
+  console.log(`${bold("Scopes")}   ${(a.scopes || []).join(", ") || "-"}`);
   const u = a.usage || {};
   // Keys/fields must match _mcp_usage_summary: actions are count_requests /
   // preview_rows / reveal_rows / export_rows and each entry carries
@@ -471,7 +471,7 @@ async function cmdCompany(args) {
     for (const person of r.results) {
       const who = [person.preview, person.title].filter(Boolean).join(" · ");
       const where = [person.country].filter(Boolean).join(", ");
-      console.log(`    ${bold(who || "—")}${where ? dim("  " + where) : ""}`);
+      console.log(`    ${bold(who || "-")}${where ? dim("  " + where) : ""}`);
     }
   }
 }
@@ -484,13 +484,13 @@ async function cmdSearch(args) {
   const res = await request("GET", args.base, "/api/mcp/people/preview", { key, query });
   const r = need(res, "search");
   if (args.json) return console.log(JSON.stringify(r, null, 2));
-  console.log(dim(`${Number(r.total).toLocaleString()} total · showing ${r.returned} (details redacted — use \`reveal\` or \`export\`)`));
+  console.log(dim(`${Number(r.total).toLocaleString()} total · showing ${r.returned} (details redacted - use \`reveal\` or \`export\`)`));
   for (const p of r.results || []) {
     // _redacted_preview returns the masked identity as `preview` (e.g. "A* P"),
-    // never `name` — without this the row rendered as title-only.
+    // never `name` - without this the row rendered as title-only.
     const who = [p.preview || p.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) : ""}`);
+    console.log(`  ${bold(who || "-")}${where ? dim("  " + where) : ""}`);
   }
 }
 
@@ -546,9 +546,9 @@ async function cmdSample(args) {
       `${bold(Number(job.total_companies || 0).toLocaleString())} matching companies`
   );
   for (const lead of job.results || []) {
-    console.log(`  ${bold(lead.full_name || "—")} ${dim("· " + (lead.title || "—"))}`);
-    console.log(`    ${(lead.company || "—")} ${dim("· " + (lead.company_domain || "—"))}`);
-    console.log(`    ${cyan(lead.email || "—")} ${green("✓ Valid")}`);
+    console.log(`  ${bold(lead.full_name || "-")} ${dim("· " + (lead.title || "-"))}`);
+    console.log(`    ${(lead.company || "-")} ${dim("· " + (lead.company_domain || "-"))}`);
+    console.log(`    ${cyan(lead.email || "-")} ${green("✓ Valid")}`);
   }
   if (args.output) console.log(green("✓") + ` Saved CSV → ${bold(args.output)}`);
   console.log(dim(`These 25 are the sample; the full pool contains ${Number(job.total_companies || 0).toLocaleString()} companies.`));
@@ -573,11 +573,11 @@ async function cmdReveal(args) {
   if (args.json) return console.log(JSON.stringify(r, null, 2));
   console.log(dim(`${Number(r.total).toLocaleString()} total · revealed ${r.returned}`));
   for (const p of r.results || []) {
-    // _revealed_contact returns full_name / first_name / last_name — there is
+    // _revealed_contact returns full_name / first_name / last_name - there is
     // no `name` key. The customer just paid for this row; print who it is.
     const name = p.full_name || [p.first_name, p.last_name].filter(Boolean).join(" ") || p.name;
     const who = [name, p.title].filter(Boolean).join(" · ");
-    console.log(`  ${bold(who || "—")}`);
+    console.log(`  ${bold(who || "-")}`);
     const bits = [p.email && cyan(p.email), p.phone, p.linkedin_url, [p.company || p.company_name, p.country].filter(Boolean).join(", ")].filter(Boolean);
     if (bits.length) console.log("    " + bits.join(dim(" · ")));
   }
@@ -653,7 +653,7 @@ async function cmdEnrich(args) {
   }
   const p = r.person || {};
   const who = [p.full_name || [p.first_name, p.last_name].filter(Boolean).join(" "), p.title].filter(Boolean).join(" · ");
-  console.log(`  ${bold(who || "—")}`);
+  console.log(`  ${bold(who || "-")}`);
   const bits = [
     p.email && cyan(p.email),
     p.phone,
@@ -683,7 +683,7 @@ function partPath(dest, n) {
 }
 
 // >50k rows come back as {type:"batch", batch_id, status_api_path:
-// /api/mcp/export-batches/{id}} with NO job_id and NO download_api_path — the
+// /api/mcp/export-batches/{id}} with NO job_id and NO download_api_path - the
 // old code fell through to /api/mcp/exports/undefined/download, so large
 // exports were simply impossible from the CLI. Poll the batch, then download
 // each completed chunk.
@@ -740,10 +740,10 @@ async function exportStatusCmd(args, key, id) {
   const s = need(res, "export status");
   if (args.json) return console.log(JSON.stringify(s, null, 2));
   if (isBatch) {
-    console.log(`${bold("Batch #" + (s.batch_id ?? id))}  ${dim(s.status || "—")}`);
+    console.log(`${bold("Batch #" + (s.batch_id ?? id))}  ${dim(s.status || "-")}`);
     console.log(`  ${s.completed_chunks || 0}/${s.total_chunks || 0} chunks · ${Number(s.verified_rows || 0).toLocaleString()} rows · ${s.progress_pct || 0}%`);
   } else {
-    console.log(`${bold("Export #" + (s.job_id ?? id))}  ${dim(s.status || "—")}`);
+    console.log(`${bold("Export #" + (s.job_id ?? id))}  ${dim(s.status || "-")}`);
     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));
@@ -756,7 +756,7 @@ async function exportDownloadCmd(args, key, id) {
     const res = await request("GET", args.base, `/api/mcp/export-batches/${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 export status ${id} --batch\`.`);
     }
     const files = await downloadBatchChunks(args, key, b, dest);
     if (args.json) return console.log(JSON.stringify({ ok: true, batch_id: id, files }, null, 2));
@@ -766,7 +766,7 @@ async function exportDownloadCmd(args, key, id) {
   const res = await request("GET", args.base, `/api/mcp/exports/${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}\`.`);
+    die(`export #${id} is ${s.status || "not ready"} - run \`argorant export status ${id}\`.`);
   }
   await downloadTo(args.base, s.download_api_path || `/api/mcp/exports/${id}/download`, key, dest);
   if (args.json) return console.log(JSON.stringify({ ok: true, file: dest, job_id: id }, null, 2));
@@ -776,7 +776,7 @@ async function exportDownloadCmd(args, key, id) {
 
 async function cmdExport(args) {
   const key = requireKey();
-  // `export status <id>` / `export download <id>` — recovery subcommands, no
+  // `export status <id>` / `export download <id>` - recovery subcommands, no
   // job is created and nothing is billed.
   const sub = (args._[0] || "").toLowerCase();
   if (sub === "status" || sub === "download") {
@@ -817,7 +817,7 @@ async function cmdExport(args) {
     const batchPath = job.status_api_path || `/api/mcp/export-batches/${job.batch_id}`;
     if (!args.json) {
       process.stdout.write(
-        dim(`Large export queued as batch #${job.batch_id} — ${job.total_chunks || "?"} chunk(s) of up to ${Number(job.chunk_size || 0).toLocaleString()} rows\n`)
+        dim(`Large export queued as batch #${job.batch_id} - ${job.total_chunks || "?"} chunk(s) of up to ${Number(job.chunk_size || 0).toLocaleString()} rows\n`)
       );
     }
     const batch = await pollExportBatch(args, key, batchPath, { quiet: !!args.json });
@@ -833,7 +833,7 @@ async function cmdExport(args) {
     if (args.json) return console.log(JSON.stringify(job, null, 2));
     return console.log("Export queued. " + JSON.stringify(job));
   }
-  if (!args.json) process.stdout.write(dim("Export queued — verifying & building CSV"));
+  if (!args.json) process.stdout.write(dim("Export queued - verifying & building CSV"));
   let downloadPath = job.download_api_path || null;
   const started = Date.now();
   // Poll until the job reports a terminal state.
@@ -851,7 +851,7 @@ async function cmdExport(args) {
     }
     if (EXPORT_TERMINAL_FAIL.includes(status)) die(`\nexport ${status}${s.error_message ? `: ${s.error_message}` : "."}`);
     if (Date.now() - started > 1000 * 60 * 20) {
-      die(`\nexport timed out after 20 minutes. It is still running server-side — check with \`argorant export status ${job.job_id}\`.`);
+      die(`\nexport timed out after 20 minutes. It is still running server-side - check with \`argorant export status ${job.job_id}\`.`);
     }
   }
   if (!args.json) process.stdout.write("\n");
@@ -862,7 +862,7 @@ async function cmdExport(args) {
   try {
     await downloadTo(args.base, downloadPath, key, dest);
   } catch (e) {
-    // The job is already paid for — always tell the user how to get it back.
+    // The job is already paid for - always tell the user how to get it back.
     die(`${e.message}\nThe export itself completed. Retry the download with \`argorant export download ${job.job_id} -o ${dest}\`.`);
   }
   if (args.json) return console.log(JSON.stringify({ ok: true, file: dest, job_id: job.job_id }, null, 2));
@@ -870,7 +870,7 @@ async function cmdExport(args) {
   console.log(green("✓") + ` Saved ${rows != null ? bold(rows.toLocaleString()) + " rows → " : ""}${bold(dest)}`);
 }
 
-// ---- verify: external email verification (own lists) — the verification pool,
+// ---- verify: external email verification (own lists) - the verification pool,
 // separate from contact credits. 60-day re-checks are free. ----
 const EMAIL_RE = /[^\s,;"']+@[^\s,;"']+\.[^\s,;"']+/;
 
@@ -911,7 +911,7 @@ async function cmdVerifyFile(args, key) {
   emails = [...new Set(emails)];
   if (!emails.length) die("no email addresses found in file (try --column <name>)");
   const out = ensureWritable(args.output || "argorant-verified.csv");
-  // Interactive-only by design — see reveal/export.
+  // Interactive-only by design - see reveal/export.
   if (!args.yes && !args.json && process.stdin.isTTY) {
     const ans = await prompt(`Verify ${bold(emails.length.toLocaleString())} emails? Fresh checks cost half a credit each; recent re-checks are free. [y/N] `);
     if (!/^y(es)?$/i.test(ans)) return console.log(dim("aborted."));
@@ -938,7 +938,7 @@ async function cmdVerifyFile(args, key) {
 }
 
 // ---- list: save & inspect reusable lead lists (parity with MCP/app). Creating a
-// filtered list is free and does NOT reveal contacts — the server counts the
+// filtered list is free and does NOT reveal contacts - the server counts the
 // matches itself, so the list reports its real size right away. ----
 async function cmdList(args) {
   const key = requireKey();
@@ -952,7 +952,7 @@ async function cmdList(args) {
     const r = need(res, "list create");
     if (args.json) return console.log(JSON.stringify(r, null, 2));
     const total = Number(r.snapshot_total || 0);
-    console.log(green("✓") + ` Created list ${bold("#" + r.list_id)} ${dim("“" + r.name + "”")} — ${bold(total.toLocaleString())} matching contacts`);
+    console.log(green("✓") + ` Created list ${bold("#" + r.list_id)} ${dim("“" + r.name + "”")} - ${bold(total.toLocaleString())} matching contacts`);
     console.log(dim(`Export it with:  argorant export ${Object.entries(args.filters).filter(([, v]) => v).map(([k, v]) => `--${k.replace(/_/g, "-")} ${/\s/.test(String(v)) ? `"${v}"` : v}`).join(" ")} -o leads.csv`));
     return;
   }
@@ -960,14 +960,14 @@ async function cmdList(args) {
     const id = args._[1] || args.name;
     if (!id) die("usage: argorant list status <list_id>");
     // Validate locally: the API path param is an int, so anything else came
-    // back as a FastAPI 422 whose detail is an array — a useless error for a
+    // back as a FastAPI 422 whose detail is an array - a useless error for a
     // plain typo.
     if (!/^\d+$/.test(String(id).trim())) die(`list id must be a number (got "${id}").`);
     const res = await request("GET", args.base, `/api/mcp/lists/${encodeURIComponent(String(id).trim())}`, { key });
     const r = need(res, "list status");
     if (args.json) return console.log(JSON.stringify(r, null, 2));
     const total = Number(r.snapshot_total ?? r.item_count ?? 0);
-    console.log(`${bold("List #" + (r.list_id ?? id))}  ${dim("“" + (r.name || "—") + "”")}`);
+    console.log(`${bold("List #" + (r.list_id ?? id))}  ${dim("“" + (r.name || "-") + "”")}`);
     console.log(`  ${bold(total.toLocaleString())} contacts · ${dim((r.selection_mode || "filtered") + " · " + (r.record_type || "person"))}`);
     return;
   }
@@ -977,9 +977,9 @@ async function cmdList(args) {
 // =============================================================================
 // campaigns: god-mode native outbound campaign control from the terminal.
 //
-// OPERATOR KEYS ONLY. Every command above talks to /api/mcp/* — the
+// OPERATOR KEYS ONLY. Every command above talks to /api/mcp/* - the
 // customer-facing contact-data API, gated by plan scopes. Everything below
-// talks to /api/sequencer/* — the internal Argorant Sequencer that runs live
+// talks to /api/sequencer/* - the internal Argorant Sequencer that runs live
 // outbound sends. It authenticates via the SAME ag_live_ Bearer key, but only
 // works for a key that (a) belongs to an owner/admin account and (b) carries
 // the `argorant:operator` scope (see cli/GODMODE-PLAN.md). Any other key gets
@@ -987,14 +987,14 @@ async function cmdList(args) {
 // access.
 //
 // Kept on its own tiny flag reader (readFlags) instead of the top-level
-// parseArgs — these subcommands have their own vocabulary (--step, --subject,
+// parseArgs - these subcommands have their own vocabulary (--step, --subject,
 // --count, --pool, --csv, ...) that would otherwise collide with, or be
 // rejected by, the generic filter-flag parser used for search/reveal/export.
 // =============================================================================
 
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 
-// Filter flags for `campaigns leads add --query ...` — the same names/mapping
+// Filter flags for `campaigns leads add --query ...` - the same names/mapping
 // as the top-level VALUE_FLAGS/BOOL_FLAGS (minus the ones the sequencer's
 // filter-enroll endpoint doesn't accept, e.g. --verified-only), plus --query
 // as an explicit alias for free-text `q` (clearer than a bare positional in a
@@ -1053,7 +1053,7 @@ function readFlags(argv, valueFlags = {}, boolFlags = {}) {
 // A saved base from `argorant login --base …` only applies when the caller did
 // NOT pass --base. Inferring "no flag given" from the VALUE (=== DEFAULT_BASE)
 // meant `--base https://argorant.com` was silently ignored after a staging
-// login — requests went to the wrong host with no indication.
+// login - requests went to the wrong host with no indication.
 function applySavedBase(args) {
   if (args.baseExplicit || process.env.ARGORANT_API_BASE) return args;
   const saved = loadConfig().base;
@@ -1088,7 +1088,7 @@ async function resolveCampaign(base, key, identifier) {
   }
   if (matches.length > 1) {
     die(
-      `"${identifier}" matches ${matches.length} campaigns — be more specific:\n` +
+      `"${identifier}" matches ${matches.length} campaigns - be more specific:\n` +
         matches.map((c) => `  ${c.name}  ${dim(c.id)}`).join("\n")
     );
   }
@@ -1106,8 +1106,8 @@ async function campaignsList(argv) {
   for (const c of campaigns) {
     const sent = Number(c.sent_count || 0);
     const replied = Number(c.replied_count || 0);
-    const rate = sent > 0 ? `${((replied / sent) * 100).toFixed(1)}%` : "—";
-    console.log(`${bold(c.name || "—")}  ${dim(c.id)}`);
+    const rate = sent > 0 ? `${((replied / sent) * 100).toFixed(1)}%` : "-";
+    console.log(`${bold(c.name || "-")}  ${dim(c.id)}`);
     console.log(
       `  ${c.status}` +
         dim("  ·  leads ") + Number(c.lead_count || 0).toLocaleString() +
@@ -1248,7 +1248,7 @@ async function campaignsSteps(argv) {
   }
   body = (body || "").trim();
   if (!body) die("body is empty");
-  // The CLI never generates copy — the operator/agent writes it; this command
+  // The CLI never generates copy - the operator/agent writes it; this command
   // only upserts what it's given.
   const campaignId = await resolveCampaign(args.base, key, identifier);
   const stepBody = { step_number: stepNumber, subject, body, copy_status: args.approve ? "approved" : "draft" };
@@ -1270,7 +1270,7 @@ async function campaignsInboxes(argv) {
   if (!count || count < 1) die("--count must be a positive integer");
   const campaignId = await resolveCampaign(args.base, key, identifier);
 
-  // Fleet changes only ever happen via this explicit command — never
+  // Fleet changes only ever happen via this explicit command - never
   // implicitly from create/start. Exclude whatever's already attached to THIS
   // campaign (an inbox can serve multiple campaigns; "unattached" is relative
   // to this one), then page through the healthy/usable pool for candidates.
@@ -1405,7 +1405,7 @@ async function campaignsStatus(argv) {
   const r = need(await request("GET", args.base, `/api/v1/campaigns/${campaignId}`, { key }), "campaign");
   if (args.json) return console.log(JSON.stringify(r, null, 2));
   const c = r.campaign || {};
-  console.log(`${bold(c.name || "—")}  ${dim(c.id)}`);
+  console.log(`${bold(c.name || "-")}  ${dim(c.id)}`);
   console.log(`  status ${bold(c.status)}  ·  leads ${Number(c.lead_count || 0).toLocaleString()}  ·  sent ${Number(c.sent_count || 0).toLocaleString()}  ·  replies ${Number(c.replied_count || 0).toLocaleString()}  ·  bounced ${Number(c.bounced_count || 0).toLocaleString()}`);
   console.log(`  emails ${(r.emails || []).length}  ·  senders ${(r.senders || []).length}`);
   printSettings({ settings: r.settings });
@@ -1511,7 +1511,7 @@ async function campaignsReplies(argv) {
   if (!(r.replies || []).length) return console.log(dim("No replies yet."));
   for (const e of r.replies) {
     console.log(`${bold(e.from_email || "")}  ${dim([e.first_name, e.last_name].filter(Boolean).join(" "))}  ${e.classification || ""}  ${dim(e.created_at || "")}`);
-    console.log(dim(`  ${(e.subject || "").slice(0, 80)} — ${(e.body || "").replace(/\s+/g, " ").slice(0, 140)}`));
+    console.log(dim(`  ${(e.subject || "").slice(0, 80)} - ${(e.body || "").replace(/\s+/g, " ").slice(0, 140)}`));
   }
 }
 
@@ -1530,7 +1530,7 @@ async function cmdInboxThreads(argv) {
     for (const e of r.events) {
       console.log(`${dim(e.id)}`);
       console.log(`  ${bold(e.from_email || e.lead_email || "")}  ${e.classification || ""}  ${dim(e.campaign_name || "")}  ${dim(e.created_at || "")}`);
-      console.log(dim(`  ${(e.subject || "").slice(0, 80)} — ${(e.body || e.snippet || "").replace(/\s+/g, " ").slice(0, 140)}`));
+      console.log(dim(`  ${(e.subject || "").slice(0, 80)} - ${(e.body || e.snippet || "").replace(/\s+/g, " ").slice(0, 140)}`));
     }
     return;
   }
@@ -1624,7 +1624,7 @@ async function cmdBlocklist(argv) {
 function campaignsHelp() {
   const p = bold("argorant campaigns");
   console.log(`
-${bold("Argorant Campaigns")} — email outreach from the terminal
+${bold("Argorant Campaigns")} - email outreach from the terminal
 
 Works with any Argorant API key. Nothing is sent until you launch.
 
@@ -1654,11 +1654,14 @@ ${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")} suggest <website|brand> [-n 20]   ${dim("free domain names with prices")}
+  ${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]
-  ${bold("argorant inboxes")} order <quote-id> --senders "Elena Vaughn[,Mark Hill]" [--website acme.com] [-y]   ${dim("returns a checkout link; nothing is bought before you pay it")}
+  ${bold("argorant inboxes")} order <quote-id> --senders "Elena Vaughn[,Mark Hill]" [--website acme.com] [--pay-with link] [-y]   ${dim("the saved card when your workspace allows it, else a payment link")}
   ${bold("argorant inboxes")} status [<order-id>]
-  ${bold("argorant inboxes")} cancel-bundle <order-id> <bundle-id> [--keep-domains] [-y]  |  cancel-domain <order-id> <domain> [-y]
+  ${bold("argorant inboxes")} renewal <order-id> <domain> --off|--on [-y]   ${dim("Stop renewal / Turn renewal back on; nothing is charged now")}
+  ${bold("argorant inboxes")} cancel-bundle <order-id> <bundle-id> --reason <reason> [--note "..."] [--keep-domains] [-y]
+  ${dim("  reasons: too_expensive, not_sending_enough, deliverability, switching_provider, campaign_finished, other")}
   ${bold("argorant blocklist")} list | add <email|domain> | remove <id>
 
   ${bold("argorant inbox")} list [--folder replies|interested|not_interested|out_of_office|bounces|unsubscribes|all] [--campaign <c>] [--q text]
@@ -1780,11 +1783,18 @@ async function cmdInboxes(argv) {
     for (const c of r.connected || []) console.log(dim(`  ${c.email} · ${c.health || "ok"}`));
     return;
   }
+  if (sub === "endings") {
+    const args = readFlags(argv.slice(1));
+    const r = need(await request("GET", args.base, "/api/v1/inboxes/endings", { key }), "inboxes endings");
+    if (args.json) return console.log(JSON.stringify(r, null, 2));
+    return console.log((r.endings || []).map((e) => "." + e).join("  "));
+  }
   if (sub === "suggest") {
-    const args = readFlags(argv.slice(1), { "-n": "limit", "--limit": "limit" });
+    const args = readFlags(argv.slice(1), { "-n": "limit", "--limit": "limit", "--ending": "ending", "--tld": "ending" });
     const company = args._.join(" ").trim();
-    if (!company) die("usage: argorant inboxes suggest <website|brand> [-n 20]");
+    if (!company) die("usage: argorant inboxes suggest <website|brand> [--ending com] [-n 20]");
     const query = { company, limit: args.limit ? parseLimit(args.limit, "--limit") : 20 };
+    if (args.ending) query.ending = String(args.ending).replace(/^\./, "").toLowerCase();
     const r = need(await request("GET", args.base, "/api/v1/inboxes/domains/suggest", { key, query }), "inboxes suggest");
     if (args.json) return console.log(JSON.stringify(r, null, 2));
     for (const d of r.results || []) {
@@ -1816,32 +1826,47 @@ async function cmdInboxes(argv) {
     console.log(bold(`Due today: ${money(q.due_today_cents, cur)}`) + `  then ${money(q.recurring_cents, cur)} per ${q.mailboxes.billing}; domains renew at ${money(q.renewal_per_year_cents, cur)} a year in total`);
     console.log(dim(q.currency_rule));
     for (const line of q.included || []) console.log(dim(`  · ${line}`));
+    const card = q.payment && q.payment.saved_card;
+    if (card && card.usable) console.log(bold(`Paid with: the saved ${card.card}, charged right away when you order (within 15 minutes of this quote)`));
+    else if (card) console.log(dim(`Paid with: a payment link${card.reason ? ` (saved card: ${card.reason})` : ""}`));
     console.log(`\nQuote ${bold(q.quote_id)} ${dim(`(valid until ${String(q.expires_at).slice(0, 16).replace("T", " ")} UTC)`)}`);
     if (q.can_order) console.log(dim(`Order it:  argorant inboxes order ${q.quote_id} --senders "First Last"`));
     else console.log(yellow(q.next_step));
     return;
   }
   if (sub === "order") {
-    const args = readFlags(argv.slice(1), { "--senders": "senders", "--sender": "senders", "--website": "website" });
+    const args = readFlags(argv.slice(1), { "--senders": "senders", "--sender": "senders", "--website": "website", "--pay-with": "payWith" });
     const quoteId = args._[0];
-    if (!quoteId || !args.senders) die("usage: argorant inboxes order <quote-id> --senders \"Elena Vaughn[,Mark Hill]\" [--website acme.com] [-y]");
+    if (!quoteId || !args.senders) die("usage: argorant inboxes order <quote-id> --senders \"Elena Vaughn[,Mark Hill]\" [--website acme.com] [--pay-with link] [-y]");
+    const payWith = String(args.payWith || "auto").toLowerCase();
+    if (!["auto", "link"].includes(payWith)) die("--pay-with is link (always a payment link); leave it out for the saved card when allowed");
     const senders = String(args.senders).split(",").map((x) => x.trim()).filter(Boolean).map((full) => {
       const parts = full.split(/\s+/);
       if (parts.length < 2) die(`sender "${full}" needs a first and a last name`);
       return { first_name: parts[0], last_name: parts.slice(1).join(" ") };
     });
     if (!args.yes) {
+      const how = payWith === "link" ? "You get a payment link; nothing is bought before you pay it."
+        : "If your workspace saved its card for API and agent purchases (the quote says so), that card is charged now; otherwise you get a payment link.";
       const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-      const ok = await new Promise((r) => rl.question(`Order the inboxes in quote ${quoteId}? You get a checkout link to pay; nothing is bought before that. [y/N] `, (a) => { rl.close(); r(/^y/i.test(a)); }));
+      const ok = await new Promise((r) => rl.question(`Order the inboxes in quote ${quoteId}? ${how} [y/N] `, (a) => { rl.close(); r(/^y/i.test(a)); }));
       if (!ok) return console.log(dim("aborted"));
     }
     const body = { quote_id: quoteId, senders, website: args.website || "", confirmed: true };
-    // Same command, same key: running it again returns the same order and link instead of a second order.
+    if (payWith !== "auto") body.pay_with = payWith;
+    // Same command, same key: running it again returns the same order (and never charges twice).
     const idem = "cli-" + crypto.createHash("sha256").update(JSON.stringify(body)).digest("hex").slice(0, 40);
     const r = need(await request("POST", args.base, "/api/v1/inboxes/orders", { key, body, headers: { "Idempotency-Key": idem } }), "inboxes order");
     if (args.json) return console.log(JSON.stringify(r, null, 2));
+    if (r.status === "paid") {
+      console.log(green("✓") + ` Order ${bold(r.order_id)} paid with the saved ${r.card || "card"}${r.replayed ? dim(" (already placed)") : ""}`);
+      console.log(dim(r.message || ""));
+      console.log(dim(`Track it:  argorant inboxes status ${r.order_id}`));
+      return;
+    }
     if (!r.checkout_url) return console.log(`Order ${r.order_id}: ${r.status}. ${dim(r.message || "")}`);
     console.log(green("✓") + ` Order ${bold(r.order_id)}${r.existing || r.replayed ? dim(" (already placed)") : ""}`);
+    if (r.saved_card && r.saved_card.reason) console.log(yellow(`Not charged to the saved card: ${r.saved_card.reason}`));
     console.log(`Pay here: ${cyan(r.checkout_url)}`);
     console.log(dim("Nothing is bought until you pay it; setup starts after the payment is confirmed."));
     console.log(dim(`Track it:  argorant inboxes status ${r.order_id}`));
@@ -1857,7 +1882,7 @@ async function cmdInboxes(argv) {
     if (!rows.length) return console.log(dim("No inbox orders yet. Start with: argorant inboxes quote --mailboxes 100 --company <your website>"));
     for (const o of rows) {
       const mb = o.mailboxes || {};
-      console.log(`${bold(o.order_id)}  ${o.status}${o.step ? dim(` · ${o.step}`) : ""}  ${dim(`${mb.created || 0}/${mb.total || 0} mailboxes`)}${o.aging_ends_at ? dim(` · aging ends ${o.aging_ends_at}`) : ""}`);
+      console.log(`${bold(o.order_id)}  ${o.status}${o.step ? dim(` · ${o.step}`) : ""}  ${dim(`${mb.created || 0}/${mb.total || 0} mailboxes`)}${o.aging_ends_at ? dim(` · aging ends ${o.aging_ends_at}`) : ""}${o.ordered_via ? dim(` · ordered via API/agent${o.paid_with === "saved_card" ? ", saved card" : ""}`) : ""}`);
       for (const d of o.domains || []) {
         console.log(dim(`  ${d.name}${d.expires_at ? ` · expires ${String(d.expires_at).slice(0, 10)}` : ""} · renews at ${money(d.renewal_per_year_cents, o.currency)}/year${d.auto_renew === false ? " · renewal off" : ""}`));
       }
@@ -1867,26 +1892,475 @@ async function cmdInboxes(argv) {
     }
     return;
   }
-  if (sub === "cancel-bundle" || sub === "cancel-domain") {
-    const args = readFlags(argv.slice(1), {}, { "--keep-domains": "keepDomains" });
+  if (sub === "renewal" || sub === "cancel-domain") {
+    // cancel-domain is the old name of `renewal --off` (kept working, deprecated).
+    const args = readFlags(argv.slice(1), {}, { "--on": "on", "--off": "off" });
+    const [orderId, domain] = args._;
+    const on = sub === "renewal" ? (args.on ? true : args.off ? false : null) : false;
+    if (!orderId || !domain || on === null || (args.on && args.off)) die("usage: argorant inboxes renewal <order-id> <domain> --off|--on [-y]");
+    if (sub === "cancel-domain") console.error(dim("cancel-domain is deprecated: use `argorant inboxes renewal <order-id> <domain> --off`."));
+    const question = on
+      ? `Turn renewal back on for ${domain}? Nothing is charged now; it renews at its expiry date, billed shortly before. [y/N] `
+      : `Stop renewal for ${domain}? Nothing is charged now; it keeps working until its expiry date and is not renewed. [y/N] `;
+    if (!args.yes) {
+      const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+      const ok = await new Promise((r) => rl.question(question, (a) => { rl.close(); r(/^y/i.test(a)); }));
+      if (!ok) return console.log(dim("aborted"));
+    }
+    const r = need(await request("POST", args.base, `/api/v1/inboxes/orders/${encodeURIComponent(orderId)}/domains/${encodeURIComponent(domain)}/renewal`,
+      { key, body: { on } }), "inboxes renewal");
+    if (args.json) return console.log(JSON.stringify(r, null, 2));
+    return console.log(green("✓") + ` ${r.message || (on ? `${domain} renews again` : `${domain} will not renew`)}`);
+  }
+  if (sub === "cancel-bundle") {
+    const REASONS = ["too_expensive", "not_sending_enough", "deliverability", "switching_provider", "campaign_finished", "other"];
+    const args = readFlags(argv.slice(1), { "--reason": "reason", "--note": "note" }, { "--keep-domains": "keepDomains" });
     const [orderId, target] = args._;
-    if (!orderId || !target) die(sub === "cancel-bundle" ? "usage: argorant inboxes cancel-bundle <order-id> <bundle-id> [--keep-domains] [-y]" : "usage: argorant inboxes cancel-domain <order-id> <domain> [-y]");
-    const question = sub === "cancel-bundle"
-      ? `Cancel bundle ${target}? Billing for its mailboxes stops now (no refund); they work until the paid period ends, then they are deleted${args.keepDomains ? "" : " and its domains stop renewing"}. [y/N] `
-      : `Stop renewing ${target}? It works until its expiry date and is not renewed. [y/N] `;
+    if (!orderId || !target || !args.reason) die("usage: argorant inboxes cancel-bundle <order-id> <bundle-id> --reason <reason> [--note \"...\"] [--keep-domains] [-y]\n  reasons: " + REASONS.join(", "));
+    const reason = String(args.reason).toLowerCase();
+    if (!REASONS.includes(reason)) die(`--reason is one of: ${REASONS.join(", ")}`);
+    const question = `Cancel bundle ${target}? Billing for its mailboxes stops now (no refund); they work until the paid period ends, then they are deleted${args.keepDomains ? "" : " and its domains stop renewing"}. [y/N] `;
     if (!args.yes) {
       const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
       const ok = await new Promise((r) => rl.question(question, (a) => { rl.close(); r(/^y/i.test(a)); }));
       if (!ok) return console.log(dim("aborted"));
     }
-    const base = `/api/v1/inboxes/orders/${encodeURIComponent(orderId)}`;
-    const r = sub === "cancel-bundle"
-      ? need(await request("POST", args.base, `${base}/bundles/${encodeURIComponent(target)}/cancel`, { key, body: { keep_domains: !!args.keepDomains } }), "inboxes cancel-bundle")
-      : need(await request("POST", args.base, `${base}/domains/${encodeURIComponent(target)}/cancel`, { key, body: {} }), "inboxes cancel-domain");
+    const body = { keep_domains: !!args.keepDomains, reason };
+    if (args.note) body.note = String(args.note);
+    const r = need(await request("POST", args.base, `/api/v1/inboxes/orders/${encodeURIComponent(orderId)}/bundles/${encodeURIComponent(target)}/cancel`,
+      { key, body }), "inboxes cancel-bundle");
     if (args.json) return console.log(JSON.stringify(r, null, 2));
-    return console.log(green("✓") + (sub === "cancel-bundle" ? ` Bundle ${target} cancelled${r.existing ? dim(" (already)") : ""}` : ` ${target} will not renew`));
+    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)`);
+}
+
+// =============================================================================
+// find: the email finder. A person's name plus a company domain in, a work
+// email out. Priced per outcome by the server (GET /api/v1/email-finder/pricing):
+// an address returned costs 1 credit, a lookup that finds nothing 0.25 credit,
+// and lookups that cannot run (no mail server, try again later, invalid input)
+// are free. Nothing is charged on any error response.
+//
+// Own flag reader (readFlags) like `campaigns`: --first/--last/--max-credits
+// are not search filters, and `--name` means the job name with --file but the
+// person's name on a single lookup (same habit as `enrich --name`).
+// Exit codes: a single lookup exits 1 when no email came back (like `enrich`);
+// a --file job that pauses exits 5 (out of credits) or 4 (daily limit or slowed
+// down), so scripts can branch without parsing output.
+// =============================================================================
+
+const FIND_API = "/api/v1/email-finder";
+const FIND_DEFAULT_OUT = "argorant-found.csv";
+const FIND_POLL_MS = 2500;
+const FIND_VALUE_FLAGS = {
+  "--domain": "domain",
+  "--first": "first",
+  "--first-name": "first",
+  "--last": "last",
+  "--last-name": "last",
+  "--name": "name",
+  "-f": "file",
+  "--file": "file",
+  "-o": "output",
+  "--output": "output",
+  "--max-credits": "maxCredits",
+};
+const FIND_STATUS_LABELS = {
+  valid: "Confirmed",
+  catch_all: "Unconfirmed, catch-all domain",
+  not_found: "Not found",
+  no_mail_domain: "No mail server",
+  retry_later: "Try again later",
+  invalid_input: "Invalid input",
+  pending: "Pending",
+};
+const FIND_PAUSED_REASONS = {
+  insufficient_credits: "your workspace ran out of credits. Add credits, then resume.",
+  spend_limit: "the job reached its credit cap (--max-credits). Resume with a higher cap to continue.",
+  daily_limit: "the daily lookup limit was reached.",
+  miss_rate: "almost none of the recent lookups found an address, so lookups are slowed down for a while.",
+};
+const FIND_TERMINAL = ["done", "cancelled", "canceled", "paused"];
+const FIND_USAGE =
+  'usage: argorant find "<first last>" --domain <company.com>\n' +
+  "       argorant find --first <first> --last <last> --domain <company.com>\n" +
+  '       argorant find --file people.csv [-o found.csv] [--max-credits N] [--name "Q4 list"]\n' +
+  "       argorant find status | download | resume | cancel <job_id>\n" +
+  "       argorant find pricing";
+
+// 1 -> "1 credit", 0.25 -> "0.25 credit", 2 / 0 -> "2 credits" / "0 credits".
+function fmtCredits(n) {
+  const v = Number(n || 0);
+  return `${v.toLocaleString("en-US", { maximumFractionDigits: 2 })} credit${v > 0 && v <= 1 ? "" : "s"}`;
+}
+function fmtCharge(n) {
+  return Number(n || 0) > 0 ? fmtCredits(n) : "not charged";
+}
+function fmtWait(sec) {
+  if (sec < 90) return `${sec} seconds`;
+  if (sec < 5400) return `${Math.round(sec / 60)} minutes`;
+  return `${Math.round(sec / 3600)} hours`;
+}
+
+// The finder answers errors FastAPI-style under `detail`; tolerate a bare
+// {error, message} body too, and turn Retry-After into a plain wait time.
+function findNeed(res, what, { expect } = {}) {
+  const j = res.json;
+  let r = res;
+  // need() lets any status below 400 through. A redirect (http -> https, a
+  // wrong --base) must not read as "no email found" or "job resumed".
+  if (res.status >= 300 && res.status < 400) {
+    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)) {
+    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);
+  }
+  let out = need(r, what);
+  // Job endpoints answer {ok, job: {...}}; the commands work on the job itself.
+  if (out && typeof out === "object" && out.job && typeof out.job === "object" && !Array.isArray(out.job)) out = out.job;
+  if (expect && (out === null || typeof out !== "object" || out[expect] === undefined || out[expect] === null)) {
+    die(`${what}: unexpected response from the server (no "${expect}" field). Check --base / ARGORANT_API_BASE.`);
+  }
+  return out;
+}
+
+function parseMaxCredits(raw) {
+  if (raw === undefined || raw === null) return null;
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n <= 0) die(`--max-credits must be a positive number (got "${raw}").`);
+  return n;
+}
+
+function findJobId(args, sub) {
+  const id = String(args._[1] || "").trim();
+  if (!id) die(`usage: argorant find ${sub} <job_id>${sub === "download" ? " [-o found.csv]" : sub === "resume" ? " [--max-credits N]" : ""}`);
+  if (!/^[A-Za-z0-9_.:-]{1,128}$/.test(id)) die(`that does not look like a job id: ${id}`);
+  return id;
+}
+const findJobPath = (id, suffix = "") => `${FIND_API}/jobs/${encodeURIComponent(id)}${suffix}`;
+
+// Server prices, tolerant of a flat or nested shape. Fallbacks are the
+// documented defaults; the server stays the source of truth for charges.
+function findPrices(p) {
+  const pr = (p && (p.prices || p.pricing)) || {};
+  const pick = (...vals) => {
+    for (let v of vals) {
+      if (v && typeof v === "object") v = v.credits;
+      if (v !== undefined && v !== null && v !== "" && Number.isFinite(Number(v))) return Number(v);
+    }
+    return null;
+  };
+  const found = pick(pr.valid, pr.found, p && p.price_found);
+  return {
+    known: found !== null,
+    found: found ?? 1,
+    catchAll: pick(pr.catch_all, p && p.price_catch_all) ?? found ?? 1,
+    notFound: pick(pr.not_found, p && p.price_not_found) ?? 0.25,
+  };
+}
+
+function findCounts(job) {
+  const c = job.counts || {};
+  const confirmed = Number(c.valid || 0);
+  const catchAll = Number(c.catch_all || 0);
+  return {
+    confirmed,
+    catchAll,
+    found: confirmed + catchAll,
+    notFound: Number(c.not_found || 0),
+    free: Number(c.no_mail_domain || 0) + Number(c.retry_later || 0) + Number(c.invalid_input || 0),
+  };
+}
+function findProgress(job) {
+  const k = findCounts(job);
+  return `${job.status || "queued"}  ${Number(job.processed || 0).toLocaleString()}/${Number(job.total || 0).toLocaleString()} processed · ${k.found.toLocaleString()} found · ${fmtCredits(job.credits_charged)} charged`;
+}
+function findSummaryLines(job) {
+  const k = findCounts(job);
+  const lines = [
+    `  ${Number(job.processed || 0).toLocaleString()}/${Number(job.total || 0).toLocaleString()} processed · ` +
+      `${bold(k.found.toLocaleString())} found ${dim(`(${k.confirmed.toLocaleString()} confirmed, ${k.catchAll.toLocaleString()} unconfirmed catch-all)`)} · ` +
+      `${k.notFound.toLocaleString()} not found · ${k.free.toLocaleString()} not charged`,
+    `  ${fmtCredits(job.credits_charged)} charged` + (job.max_credits != null ? dim(` · cap ${fmtCredits(job.max_credits)}`) : ""),
+  ];
+  if (Number(job.duplicates_removed || 0) > 0) lines.push(dim(`  ${Number(job.duplicates_removed).toLocaleString()} duplicate rows removed`));
+  const bad = Array.isArray(job.invalid_rows) ? job.invalid_rows : [];
+  if (bad.length) {
+    lines.push(dim(`  ${bad.length.toLocaleString()} rows skipped as invalid (row ${bad.slice(0, 10).join(", ")}${bad.length > 10 ? ", ..." : ""})`));
+  }
+  return lines;
+}
+function findPausedLines(job, id) {
+  const r = job.paused_reason;
+  const lines = [yellow(`Paused: ${FIND_PAUSED_REASONS[r] || (r ? `reason "${r}".` : "no reason given.")}`)];
+  if (job.resume_after) lines.push(dim(`It can continue after ${job.resume_after}.`));
+  lines.push(`Resume: argorant find resume ${id} ${r === "spend_limit" ? "--max-credits <new cap>" : "[--max-credits N]"}`);
+  return lines;
+}
+function findPausedExit(reason) {
+  if (reason === "insufficient_credits") return EXIT.UPGRADE;
+  if (reason === "daily_limit" || reason === "miss_rate") return EXIT.RATE_LIMIT;
+  return EXIT.OK; // spend_limit: the job stopped at the cap the caller set.
+}
+function findStatusTag(status) {
+  const s = String(status || "").toLowerCase();
+  if (s === "done") return green(s);
+  if (s === "paused") return yellow(s);
+  return dim(s || "unknown");
+}
+
+async function findSingle(args, key) {
+  const raw = String(args.domain || "").trim();
+  const domain = normalizeDomain(raw.includes("@") ? raw.split("@").pop() : raw);
+  const first = String(args.first || "").trim();
+  const last = String(args.last || "").trim();
+  const name = (args._.join(" ") || String(args.name || "")).trim();
+  if (!domain && !first && !last && !name) die(FIND_USAGE);
+  if (!domain) die(`--domain is required (the company the person works at).\n${FIND_USAGE}`);
+  if (!domain.includes(".")) die(`--domain needs a company domain like acme.com (got "${raw}").`);
+  if ((first || last) && name) die("pass either a full name or --first/--last, not both.");
+  if (!first && !last && !name) die(`a name is required.\n${FIND_USAGE}`);
+  if (args.output) warn("-o is for --file jobs; a single lookup prints its result.");
+  if (args.maxCredits !== undefined) warn("--max-credits is for --file jobs; a single lookup costs at most 1 credit.");
+  const body = first || last ? { first_name: first, last_name: last, domain } : { name, domain };
+  const r = findNeed(await request("POST", args.base, `${FIND_API}/find`, { key, body }), "find", { expect: "status" });
+  const gotEmail = Boolean(r.email);
+  if (args.json) {
+    console.log(JSON.stringify(r, null, 2));
+    if (!gotEmail) process.exit(EXIT.ERROR);
+    return;
+  }
+  const label = FIND_STATUS_LABELS[r.status] || r.status || "unknown";
+  const tag = r.status === "valid" ? green(label) : r.status === "catch_all" ? yellow(label) : dim(label);
+  const parts = [gotEmail ? bold(r.email) : dim("no email found"), tag];
+  if (gotEmail && r.confidence !== undefined && r.confidence !== null) parts.push(`confidence ${r.confidence}`);
+  parts.push(fmtCharge(r.credits_charged));
+  console.log(parts.join(dim("  ·  ")));
+  if (!gotEmail) process.exit(EXIT.ERROR);
+}
+
+async function pollFindJob(args, key, job) {
+  const id = job.job_id;
+  const tty = Boolean(process.stdout.isTTY);
+  const recovery = `The job keeps running. Check it with \`argorant find status ${id}\` and download with \`argorant find download ${id} -o ${args.output || FIND_DEFAULT_OUT}\`.`;
+  const onInt = () => {
+    if (tty && !args.json) process.stdout.write("\n");
+    process.stderr.write(dim(`Stopped watching. ${recovery}\n`));
+    process.exit(130);
+  };
+  process.once("SIGINT", onInt);
+  const started = Date.now();
+  let shown = "";
+  let failures = 0;
+  try {
+    for (;;) {
+      if (!args.json) {
+        const line = findProgress(job);
+        if (line !== shown) {
+          if (tty) process.stdout.write(`\r\x1b[K${dim(line)}`);
+          else console.log(line);
+          shown = line;
+        }
+      }
+      if (FIND_TERMINAL.includes(String(job.status || "").toLowerCase())) break;
+      if (Date.now() - started > 1000 * 60 * 60 * 12) die(`\nstopped watching after 12 hours. ${recovery}`);
+      await new Promise((r) => setTimeout(r, FIND_POLL_MS));
+      let res;
+      try {
+        res = await request("GET", args.base, findJobPath(id), { key });
+      } catch (e) {
+        res = { error: e };
+      }
+      // Ride out short network blips and gateway errors; the job is server-side.
+      if (res.error || res.status >= 500) {
+        failures += 1;
+        if (failures > 5) die(`\n${res.error ? res.error.message : `job status failed (HTTP ${res.status})`}. ${recovery}`);
+        continue;
+      }
+      failures = 0;
+      job = findNeed(res, "find job status", { expect: "status" });
+    }
+  } finally {
+    process.removeListener("SIGINT", onInt);
+  }
+  if (tty && !args.json) process.stdout.write("\n");
+  return job;
+}
+
+async function findFile(args, key) {
+  if (args._.length) die("pass either a name or --file, not both.");
+  if (args.domain || args.first || args.last) {
+    die("--domain/--first/--last are for a single lookup; with --file every row carries its own name and domain.");
+  }
+  const maxCredits = parseMaxCredits(args.maxCredits);
+  let text;
+  try {
+    text = fs.readFileSync(args.file, "utf8");
+  } catch {
+    die(`cannot read file: ${args.file}`);
+  }
+  text = text.replace(/^/, "");
+  const lines = text.split(/\r?\n/).filter((l) => l.trim());
+  if (!lines.length) die("file is empty");
+  // Local count for the prompt only; the server parses the file and reports
+  // the real total, duplicates and invalid rows on the job.
+  const rows = lines.length - 1;
+  if (rows < 1) die("file has a header but no rows.");
+  // A paid job must never die on a path problem after it was created.
+  const destArg = args.output || FIND_DEFAULT_OUT;
+  const dest = ensureWritable(destArg);
+  // Interactive-only by design, like reveal/export: with --yes, --json or a
+  // non-TTY stdin this spends credits with no prompt.
+  if (!args.yes && !args.json && process.stdin.isTTY) {
+    const p = findNeed(await request("GET", args.base, `${FIND_API}/pricing`, { key }), "find pricing");
+    const pr = findPrices(p);
+    if (!pr.known) warn("the server did not return prices in a known shape; showing the standard prices.");
+    let max = rows * Math.max(pr.found, pr.catchAll, pr.notFound);
+    if (maxCredits !== null) max = Math.min(max, maxCredits);
+    const ans = await prompt(
+      `Find emails for ${bold(rows.toLocaleString())} rows? ${fmtCredits(pr.found)} per email found, ` +
+        `${fmtCredits(pr.notFound)} when nothing is found (maximum ${fmtCredits(max)}). [y/N] `
+    );
+    if (!/^y(es)?$/i.test(ans)) return console.log(dim("aborted."));
+  }
+  const body = { csv: text };
+  if (args.name) body.name = String(args.name).trim();
+  if (maxCredits !== null) body.max_credits = maxCredits;
+  const created = findNeed(await request("POST", args.base, `${FIND_API}/jobs`, { key, body }), "find job", { expect: "job_id" });
+  const id = created.job_id;
+  if (args.json) {
+    // stdout stays pure JSON; the id still reaches the terminal for recovery.
+    process.stderr.write(dim(`job ${id}\n`));
+  } else {
+    const extra = [];
+    if (Number(created.duplicates_removed || 0) > 0) extra.push(`${created.duplicates_removed} duplicates removed`);
+    if (Array.isArray(created.invalid_rows) && created.invalid_rows.length) extra.push(`${created.invalid_rows.length} invalid rows skipped`);
+    console.log(
+      green("✓") + ` Job ${bold(id)} created: ${Number(created.total ?? rows).toLocaleString()} rows` + (extra.length ? dim(` (${extra.join(", ")})`) : "")
+    );
+    console.log(dim("Ctrl-C stops watching; the job keeps running."));
+  }
+  const job = await pollFindJob(args, key, created);
+  const status = String(job.status || "").toLowerCase();
+  try {
+    await downloadTo(args.base, findJobPath(id, "/results?format=csv"), key, dest);
+  } catch (e) {
+    die(`${e.message}\nThe job itself is saved. Download it again with \`argorant find download ${id} -o ${destArg}\`.`);
   }
-  die(`unknown inboxes subcommand: ${sub} (list, set, disconnect, connect-google, suggest, quote, order, status, cancel-bundle, cancel-domain)`);
+  const exitCode = status === "paused" ? findPausedExit(job.paused_reason) : EXIT.OK;
+  if (args.json) {
+    console.log(JSON.stringify({ ...job, file: dest }, null, 2));
+    if (exitCode !== EXIT.OK) process.exit(exitCode);
+    return;
+  }
+  const head = status === "done" ? green("✓") + " Done" : status === "paused" ? yellow("Paused") : dim(status || "stopped");
+  console.log(`${head}  ${bold(id)}`);
+  for (const l of findSummaryLines(job)) console.log(l);
+  const saved = countCsvRows(dest);
+  console.log(
+    `  Saved ${saved !== null ? bold(saved.toLocaleString()) + " rows → " : ""}${bold(dest)}` +
+      (status === "done" ? "" : dim("  (rows not processed yet show as pending)"))
+  );
+  if (status === "paused") for (const l of findPausedLines(job, id)) console.log(l);
+  if (exitCode !== EXIT.OK) process.exit(exitCode);
+}
+
+async function findStatus(args, key) {
+  const id = findJobId(args, "status");
+  const job = findNeed(await request("GET", args.base, findJobPath(id), { key }), "find job status", { expect: "status" });
+  if (args.json) return console.log(JSON.stringify(job, null, 2));
+  const status = String(job.status || "").toLowerCase();
+  console.log(`${bold("Job " + (job.job_id || id))}${job.name ? "  " + dim(`"${job.name}"`) : ""}  ${findStatusTag(status)}`);
+  for (const l of findSummaryLines(job)) console.log(l);
+  if (status === "paused") for (const l of findPausedLines(job, id)) console.log("  " + l);
+  if (Number(job.processed || 0) > 0 || FIND_TERMINAL.includes(status)) {
+    console.log(dim(`  Download: argorant find download ${id} -o found.csv`));
+  }
+}
+
+async function findDownload(args, key) {
+  const id = findJobId(args, "download");
+  const dest = ensureWritable(args.output || FIND_DEFAULT_OUT);
+  const job = findNeed(await request("GET", args.base, findJobPath(id), { key }), "find job status", { expect: "status" });
+  await downloadTo(args.base, findJobPath(id, "/results?format=csv"), key, dest);
+  const status = String(job.status || "").toLowerCase();
+  if (args.json) return console.log(JSON.stringify({ ok: true, job_id: id, status, file: dest }, null, 2));
+  const rows = countCsvRows(dest);
+  console.log(green("✓") + ` Saved ${rows !== null ? bold(rows.toLocaleString()) + " rows → " : ""}${bold(dest)}`);
+  if (status !== "done") {
+    console.log(dim(`  Job is ${status || "not finished"}: ${Number(job.processed || 0).toLocaleString()}/${Number(job.total || 0).toLocaleString()} processed, the rest show as pending.`));
+  }
+}
+
+async function findResume(args, key) {
+  const id = findJobId(args, "resume");
+  const maxCredits = parseMaxCredits(args.maxCredits);
+  const body = maxCredits !== null ? { max_credits: maxCredits } : {};
+  const job = findNeed(await request("POST", args.base, findJobPath(id, "/resume"), { key, body }), "find job resume", { expect: "status" });
+  if (args.json) return console.log(JSON.stringify(job, null, 2));
+  console.log(green("✓") + ` Resumed job ${bold(job.job_id || id)}  ${findStatusTag(job.status)}`);
+  for (const l of findSummaryLines(job)) console.log(l);
+  console.log(dim(`  Follow it with: argorant find status ${id}`));
+}
+
+async function findCancel(args, key) {
+  const id = findJobId(args, "cancel");
+  const job = findNeed(await request("POST", args.base, findJobPath(id, "/cancel"), { key }), "find job cancel", { expect: "status" });
+  if (args.json) return console.log(JSON.stringify(job, null, 2));
+  console.log(green("✓") + ` Cancelled job ${bold(job.job_id || id)}. Remaining rows will not be looked up or charged.`);
+  for (const l of findSummaryLines(job)) console.log(l);
+  if (Number(job.processed || 0) > 0) console.log(dim(`  Download what was found: argorant find download ${id} -o found.csv`));
+}
+
+async function findPricing(args, key) {
+  const p = findNeed(await request("GET", args.base, `${FIND_API}/pricing`, { key }), "find pricing");
+  if (args.json) return console.log(JSON.stringify(p, null, 2));
+  const pr = findPrices(p);
+  if (!pr.known) warn("the server did not return prices in a known shape; showing the standard prices (see --json for the raw answer).");
+  console.log(bold("Email finder prices"));
+  console.log(`  Email found and confirmed        ${fmtCredits(pr.found)}`);
+  console.log(`  Catch-all domain, unconfirmed    ${fmtCredits(pr.catchAll)}`);
+  console.log(`  Nothing found                    ${fmtCredits(pr.notFound)}`);
+  console.log(`  No mail server, try again later, invalid input   ${green("free")}`);
+  const b = p.balance || {};
+  const bal = [];
+  if (b.credits !== undefined && b.credits !== null) bal.push(`${bold(Number(b.credits).toLocaleString("en-US", { maximumFractionDigits: 2 }))} credits`);
+  const pre = b.prepaid_no_result_lookups;
+  if (pre !== undefined && pre !== null) bal.push(`${Number(pre).toLocaleString()} prepaid no-result lookup${Number(pre) === 1 ? "" : "s"}`);
+  if (bal.length) console.log(`${bold("Balance")}  ${bal.join(" · ")}`);
+  const l = p.limits || {};
+  const perMin = l.per_minute ?? l.single_per_minute ?? l.minute;
+  const perDay = l.per_day ?? l.daily ?? l.daily_limit;
+  const used = l.used_today;
+  const lim = [];
+  if (perMin !== undefined && perMin !== null) lim.push(`${Number(perMin).toLocaleString()} lookups per minute`);
+  if (perDay !== undefined && perDay !== null) lim.push(`${Number(perDay).toLocaleString()} per day` + (used !== undefined && used !== null ? ` (${Number(used).toLocaleString()} used today)` : ""));
+  if (lim.length) console.log(`${bold("Limits")}   ${lim.join(" · ")}`);
+  if (p.billing_exempt) console.log(dim("Lookups on this account are not charged."));
+  console.log(dim("Nothing is charged when a request fails. A 0.25 charge takes 1 whole credit and keeps the rest for your next no-result lookups."));
+}
+
+async function cmdFind(argv) {
+  const args = readFlags(argv, FIND_VALUE_FLAGS);
+  const sub = String(args._[0] || "").toLowerCase();
+  if (sub === "help" || (!args._.length && !args.file && !args.domain && !args.first && !args.last && !args.name)) {
+    if (sub === "help") return console.log(FIND_USAGE);
+    die(FIND_USAGE);
+  }
+  const subs = { status: findStatus, download: findDownload, resume: findResume, cancel: findCancel, pricing: findPricing, prices: findPricing };
+  const key = requireKey();
+  // A subcommand word only counts as one when no single-lookup flags are set,
+  // so `find "Pricing" --domain x.com` still looks up a person.
+  if (subs[sub] && !args.file && !args.domain && !args.first && !args.last) return subs[sub](args, key);
+  if (args.file) return findFile(args, key);
+  return findSingle(args, key);
 }
 
 function money(cents, currency) {
@@ -1898,7 +2372,7 @@ function money(cents, currency) {
 function help() {
   const p = bold("argorant");
   console.log(`
-${bold("Argorant")} — verified B2B contacts from your terminal  ${dim("v" + VERSION)}
+${bold("Argorant")} - verified B2B contacts from your terminal  ${dim("v" + VERSION)}
 
 ${bold("USAGE")}
   ${p} <command> "<query>" [filters]
@@ -1922,9 +2396,14 @@ ${bold("COMMANDS")}
   ${cyan("list status")} <id>           Show a saved list's size       ${dim("(free)")}
   ${cyan("verify")} <email>             Verify one of your own emails  ${dim("(verification pool)")}
   ${cyan("verify")} --file emails.csv -o out.csv      Bulk-verify your own list ${dim("(recent re-checks free)")}
+  ${cyan("find")} "<first last>" --domain <d>   Find a person's work email ${dim("(1 credit found, 0.25 credit nothing found)")}
+  ${cyan("find")} --first <f> --last <l> --domain <d>   Same, with the name in two parts
+  ${cyan("find")} --file people.csv -o found.csv   Find emails for a list ${dim("(same prices; --max-credits caps the job)")}
+  ${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")} quote | order | status  New mailboxes on new domains ${dim("(you pay each order at checkout)")}
+  ${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
 
@@ -1945,20 +2424,23 @@ ${bold("OPTIONS")}
       --json         Raw JSON output    -y, --yes             Skip confirmations
       --base <url>   Override API base  (or ARGORANT_API_BASE)
       --batch        Treat the id in \`export status/download\` as a batch id
+      --max-credits <n>  Credit cap for a \`find --file\` job (it pauses at the cap)
       --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, and verify --file SPEND CREDITS WITHOUT A PROMPT")} whenever
+  ${red("reveal, 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.
 
 ${bold("EXIT CODES")}
   0 ok   ·   1 error   ·   2 not authenticated   ·   3 forbidden (missing scope)
   4 rate limit / daily quota   ·   5 plan upgrade required
   ${dim("`enrich` exits 1 when nothing matched, so scripts can branch without parsing the payload.")}
+  ${dim("`find` exits 1 when no email came back; a paused `find --file` job exits 5 (out of credits) or 4 (daily limit).")}
 
 ${bold("EXAMPLES")}
   ${p} count "fintech CFOs in germany"
@@ -1971,6 +2453,8 @@ ${bold("EXAMPLES")}
   ${p} enrich --domain stripe.com
   ${p} verify ceo@stripe.com
   ${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
 
   Docs: ${cyan("https://argorant.com/docs/cli")}
 `);
@@ -1981,12 +2465,13 @@ async function main() {
   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` has its own flag vocabulary (--step, --count, --pool, --csv, ...)
-  // handled by readFlags — it never goes through the generic filter parser
+  // `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") {
+  if (cmd === "campaigns" || cmd === "campaign" || cmd === "inboxes" || cmd === "mailboxes" || cmd === "inbox" || cmd === "unibox" || cmd === "blocklist" || cmd === "find") {
     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));

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "argorant",
-  "version": "0.9.0",
-  "description": "Search, count, reveal, export, and verify B2B contacts from the Argorant database — from your terminal, scripts, or coding agent.",
+  "version": "0.11.0",
+  "description": "Search, count, reveal, export, and verify B2B contacts from the Argorant database, and find work emails by name and company domain, from your terminal, scripts, or coding agent.",
   "bin": {
     "argorant": "bin/argorant.js"
   },
@@ -19,6 +19,7 @@
     "leads",
     "prospecting",
     "email-verification",
+    "email-finder",
     "sales",
     "contacts",
     "cli"