argorant 0.10.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".

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.
 
@@ -1935,6 +1935,434 @@ async function cmdInboxes(argv) {
   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}\`.`);
+  }
+  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) {
   if (cents === null || cents === undefined) return "?";
   const sign = String(currency || "usd").toLowerCase() === "eur" ? "€" : "$";
@@ -1944,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]
@@ -1968,6 +2396,11 @@ ${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 | renewal  New mailboxes on new domains ${dim("(saved card or payment link)")}
@@ -1991,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"
@@ -2017,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")}
 `);
@@ -2027,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.10.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"