argorant 0.5.0 → 0.6.0

package/README.md

@@ -122,43 +122,31 @@ needs a paid plan" apart from "something broke".
 command always wins over the stored one, `ARGORANT_API_BASE` overrides both,
 and `argorant logout` removes the file.
 
-## Campaigns — operator keys only
+## Campaigns and inboxes
 
-`argorant campaigns ...` drives live outbound campaigns end to end from the
-terminal (create → copy → inboxes → leads → start), in about two minutes.
-This group talks to a different, internal surface than everything above and
-only works for an `ag_live_` key that belongs to an **owner/admin** account
-and carries the `argorant:operator` scope — a normal customer key gets a
-401/403, same as a browser session would without outbound access.
+Email outreach from the terminal, with any Argorant API key. Nothing sends until you launch.
 
-```sh
-npx argorant campaigns create --name "Q3 CFO outreach" --brand argorant \
-  --timezone America/New_York --window 08:00-17:00 --skip-weekends
-npx argorant campaigns steps set "Q3 CFO outreach" --step 1 \
-  --subject "Quick question" --body-file ./copy/step1.txt --approve
-npx argorant campaigns inboxes attach "Q3 CFO outreach" --count 5 --pool argorant
-npx argorant campaigns leads add "Q3 CFO outreach" --query "CFO" --industry fintech --country Germany
-npx argorant campaigns start "Q3 CFO outreach"
+```
+argorant campaigns list
+argorant campaigns create --name "Q4 CFO outreach" [--daily-limit 40] [--timezone Europe/Berlin] [--gap 60-120] [--start 2026-10-01]
+argorant campaigns emails set <campaign> --step 1 --subject "Quick question, {{first_name}}" --body-file ./step1.txt
+argorant campaigns emails set <campaign> --step 2 --body "Bumping this." --delay-days 3
+argorant campaigns emails set <campaign> --file emails.json        # whole sequence at once
+argorant campaigns leads add <campaign> --list <list-id>           # a saved list
+argorant campaigns leads add <campaign> --csv leads.csv            # email, first_name, last_name, company, title
+argorant campaigns senders set <campaign> --emails a@x.com,b@y.com # or --all
+argorant campaigns launch <campaign> [-y]                          # asks for confirmation
+argorant campaigns pause | stop | status <campaign>
+
+argorant inboxes list
+argorant inboxes connect-google --admin admin@yourdomain.com       # lists mailboxes (or the delegation setup to do first)
+argorant inboxes connect-google --admin admin@yourdomain.com --emails a@x.com,b@x.com   # or --all
 ```
 
-| Command | What it does |
-| --- | --- |
-| `campaigns list [--brand <key>]` | Name, status, contacted, replies, reply rate |
-| `campaigns create --name "<n>" [--brand] [--timezone] [--window HH:MM-HH:MM] [--skip-weekends]` | New native campaign |
-| `campaigns steps set <campaign> --step <n> --subject "..." (--body-file <path> \| --body <text\|->) [--approve]` | Upsert one sequence step's copy. The CLI never writes copy for you. |
-| `campaigns inboxes attach <campaign> --count <n> [--pool <brand>]` | Attach N healthy, unattached sending inboxes (explicit fleet change; prints exactly which ones) |
-| `campaigns leads add <campaign> --csv <file>` | Import leads from a CSV (email + optional first_name/last_name/company/title/...) |
-| `campaigns leads add <campaign> --query "..." [filters]` | Enroll leads straight from a server-side search (same filters as above) |
-| `campaigns start <campaign>` / `pause <campaign>` | Start (auto-approves draft copy + campaign, background-schedules sends) / pause |
-| `campaigns status <campaign>` | Setup completeness (steps/inboxes/leads) + launch blockers |
-
-`<campaign>` accepts a raw id or an unambiguous case-insensitive name prefix;
-an ambiguous prefix lists every match instead of guessing.
-
-**Known gap:** `campaigns leads add --query` has no server-side row cap yet —
-`-n/--limit` is accepted for a familiar CLI surface but not forwarded/honored
-(it enrolls every valid match up to the platform's own cap). The CLI warns
-when you pass it. See `cli/GODMODE-PLAN.md`.
+`<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
+for operator keys.
 
 ## Releasing
 

package/bin/argorant.js

@@ -26,6 +26,7 @@ const dim = (s) => c("2", s);
 const green = (s) => c("32", s);
 const red = (s) => c("31", s);
 const cyan = (s) => c("36", s);
+const yellow = (s) => c("33", s);
 
 function die(msg, code = 1) {
   process.stderr.write(red("error: ") + msg + "\n");
@@ -75,6 +76,9 @@ const VALUE_FLAGS = {
   "--company": "company_name",
   "--domain": "company_domain",
   "--website": "website",
+  // Used by `enrich` (email → full profile). Harmless on the other commands,
+  // which simply ignore an unknown query field.
+  "--email": "email",
 };
 // Boolean filter flags (presence => "true"). --verified-only is positive intent
 // only (deliverable contacts); there is deliberately NO flag to query invalid or
@@ -348,6 +352,14 @@ async function cmdLogin(args) {
   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"));
   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;
+    process.stdout.write(cyan("Your access key is reserved. Confirm your email to activate it:\n"));
+    process.stdout.write(`${url}\n\n`);
+    process.stdout.write(dim("After confirmation, run the same login command again.\n"));
+    process.exitCode = 3;
+    return;
+  }
   if (res.status === 401) die("that key was rejected (401). Double-check you copied the whole ag_live_ key.", 2);
   const acct = need(res, "login");
   saveConfig({ apiKey: key, base: args.baseExplicit && args.base !== DEFAULT_BASE ? args.base : undefined });
@@ -570,6 +582,96 @@ async function cmdReveal(args) {
   }
 }
 
+// ---- enrich: one record in, one record out. Three modes, one endpoint:
+//   --email <addr>                 → the person behind an address (billed like a reveal)
+//   --name "<n>" --domain <d>      → find that person and reveal a verified email
+//   --domain <d>                   → the company profile, free
+// Exit code is part of the contract: a miss returns 0 rows and exits 1, so a
+// script or agent can branch on it without parsing the payload.
+function normalizeDomain(raw) {
+  return String(raw || "")
+    .trim()
+    .replace(/^https?:\/\//i, "")
+    .replace(/^www\./i, "")
+    .split(/[/?#]/, 1)[0]
+    .toLowerCase();
+}
+
+async function cmdEnrich(args) {
+  const key = requireKey();
+  const usage =
+    'usage: argorant enrich --email <name@company.com>\n' +
+    '       argorant enrich --name "Jane Doe" --domain <company.com>\n' +
+    "       argorant enrich --domain <company.com>";
+  const positional = (args._[0] || "").trim();
+  let email = String(args.filters.email || "").trim().toLowerCase();
+  let domain = String(args.filters.company_domain || "").trim();
+  const name = String(args.name || "").trim();
+  // Bare argument: an address is an email, anything else is a domain.
+  if (!email && !domain && positional) {
+    if (positional.includes("@")) email = positional.toLowerCase();
+    else domain = positional;
+  }
+  domain = domain ? normalizeDomain(domain) : "";
+  if (email && !email.includes("@")) die(`--email needs a full address (got "${email}").`);
+  if (!email && !domain) die(usage);
+  if (name && !domain) die(`--name needs --domain (the company the person works at).\n${usage}`);
+  const body = {};
+  if (email) body.email = email;
+  else if (name) { body.name = name; body.domain = domain; }
+  else body.domain = domain;
+  const personMode = Boolean(body.email || body.name);
+  // Company mode is free, so it never asks. Person mode is billed exactly like
+  // a reveal, so it gets the same interactive-only confirmation as `reveal`.
+  if (personMode && !args.yes && !args.json && process.stdin.isTTY) {
+    const ans = await prompt(
+      `Enrich this contact? A match costs 1 credit; a miss and a non-deliverable address are free. [y/N] `
+    );
+    if (!/^y(es)?$/i.test(ans)) return console.log(dim("aborted."));
+  }
+  const res = await request("POST", args.base, "/api/v1/enrich", { key, body });
+  const r = need(res, "enrich");
+  if (args.json) {
+    console.log(JSON.stringify(r, null, 2));
+    if (!r.found) process.exit(EXIT.ERROR);
+    return;
+  }
+  if (!r.found) {
+    console.log(dim(`no ${r.type || (personMode ? "person" : "company")} found · 0 credits charged`));
+    process.exit(EXIT.ERROR);
+  }
+  if (r.type === "company") {
+    const co = r.company || {};
+    console.log(`${bold(co.company || domain)}  ${dim(co.company_domain || domain)}`);
+    const where = [co.city, co.state, co.country].filter(Boolean).join(", ");
+    const what = co.industry || (co.industries || [])[0];
+    if (what) console.log(`  ${what}`);
+    if (where) console.log(`  ${dim(where)}`);
+    console.log(dim("  company profile · 0 credits charged"));
+    return;
+  }
+  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 || "—")}`);
+  const bits = [
+    p.email && cyan(p.email),
+    p.phone,
+    p.linkedin_url,
+    [p.current_company_name, p.current_company_domain, p.country].filter(Boolean).join(", "),
+  ].filter(Boolean);
+  if (bits.length) console.log("    " + bits.join(dim(" · ")));
+  if (r.deliverable === false) {
+    console.log("    " + dim(r.message || "This address did not pass live verification, so nothing was charged."));
+  }
+  const charged = Number(r.charged || 0);
+  console.log(
+    dim(
+      `    ${charged === 0 ? "0 credits charged" : `${charged} credit${charged === 1 ? "" : "s"} charged`}` +
+        (r.already_revealed ? " · already in your workspace" : "")
+    )
+  );
+}
+
 const EXPORT_TERMINAL_OK = ["completed", "done", "ready", "succeeded"];
 const EXPORT_TERMINAL_FAIL = ["failed", "error", "cancelled", "canceled"];
 
@@ -967,36 +1069,34 @@ function readStdin() {
   });
 }
 
-async function fetchCampaigns(base, key, { brand, includeCounts = true } = {}) {
-  const query = { include_counts: includeCounts ? "true" : "false", limit: "500" };
-  if (brand) query.brand = brand;
-  const res = await request("GET", base, "/api/sequencer/campaigns", { key, query });
+async function fetchCampaigns(base, key) {
+  const res = await request("GET", base, "/api/v1/campaigns", { key, query: { limit: "500" } });
   const r = need(res, "campaigns list");
   return r.campaigns || [];
 }
 
-// <campaign> accepts a raw id (uuid) or an unambiguous case-insensitive name
-// prefix. Errors listing every match when the prefix is ambiguous.
 async function resolveCampaign(base, key, identifier) {
-  if (!identifier) die("campaign id or name is required.");
   if (UUID_RE.test(identifier)) return identifier;
-  const campaigns = await fetchCampaigns(base, key, { includeCounts: false });
-  const needle = identifier.trim().toLowerCase();
-  const matches = campaigns.filter((c) => String(c.name || "").toLowerCase().startsWith(needle));
-  if (matches.length === 1) return matches[0].id;
-  if (matches.length === 0) {
+  const needle = String(identifier || "").toLowerCase();
+  const campaigns = await fetchCampaigns(base, key);
+  const exact = campaigns.filter((c) => String(c.name || "").toLowerCase() === needle);
+  const matches = exact.length ? exact : campaigns.filter((c) => String(c.name || "").toLowerCase().startsWith(needle));
+  if (!matches.length) {
     die(`no campaign matching "${identifier}". Run \`argorant campaigns list\` to see names.`);
   }
-  die(
-    `"${identifier}" matches ${matches.length} campaigns — be more specific:\n` +
-      matches.map((c) => `  ${c.id}  ${c.name}`).join("\n")
-  );
+  if (matches.length > 1) {
+    die(
+      `"${identifier}" matches ${matches.length} campaigns — be more specific:\n` +
+        matches.map((c) => `  ${c.name}  ${dim(c.id)}`).join("\n")
+    );
+  }
+  return matches[0].id;
 }
 
 async function campaignsList(argv) {
   const key = requireKey();
-  const args = readFlags(argv, { "--brand": "brand" });
-  const campaigns = await fetchCampaigns(args.base, key, { brand: args.brand, includeCounts: true });
+  const args = readFlags(argv);
+  const campaigns = await fetchCampaigns(args.base, key);
   if (args.json) return console.log(JSON.stringify(campaigns, null, 2));
   if (!campaigns.length) {
     return console.log(dim('No campaigns yet. Create one with `argorant campaigns create --name "..."`.'));
@@ -1008,7 +1108,9 @@ async function campaignsList(argv) {
     console.log(`${bold(c.name || "—")}  ${dim(c.id)}`);
     console.log(
       `  ${c.status}` +
-        dim("  ·  contacted ") + sent.toLocaleString() +
+        dim("  ·  leads ") + Number(c.lead_count || 0).toLocaleString() +
+        dim("  ·  senders ") + Number(c.inbox_count || 0).toLocaleString() +
+        dim("  ·  sent ") + sent.toLocaleString() +
         dim("  ·  replies ") + replied.toLocaleString() +
         dim("  ·  reply rate ") + rate
     );
@@ -1019,43 +1121,102 @@ async function campaignsCreate(argv) {
   const key = requireKey();
   const args = readFlags(
     argv,
-    { "--name": "name", "--brand": "brand", "--timezone": "timezone", "--window": "window" },
-    { "--skip-weekends": "skipWeekends", "--no-skip-weekends": "noSkipWeekends" }
+    { "--name": "name", "--timezone": "timezone", "--daily-limit": "dailyLimit", "--gap": "gap", "--start": "start" },
+    { "--html": "html" }
   );
   const name = (args.name || "").trim();
   if (!name) {
-    die(
-      'usage: argorant campaigns create --name "<name>" [--brand <key>] [--timezone <tz>] ' +
-        "[--window HH:MM-HH:MM] [--skip-weekends | --no-skip-weekends]"
-    );
+    die('usage: argorant campaigns create --name "<name>" [--daily-limit 100] [--timezone America/New_York] [--gap 60-120] [--start YYYY-MM-DD] [--html]');
   }
-  // lead_source defaults to "argorant_campaign" server-side, which requires a
-  // source_outbound_campaign_id this command doesn't collect. CLI-created
-  // campaigns add leads afterwards via `campaigns leads add`, so force "manual"
-  // — it's a plain attribute on the campaign row, independent of how leads
-  // actually get imported later.
-  const body = { name, lead_source: "manual" };
-  if (args.brand) body.product_key = args.brand;
-  if (args.timezone) body.default_timezone = args.timezone;
-  if (args.window) {
-    const m = /^(\d{1,2}:\d{2})-(\d{1,2}:\d{2})$/.exec(args.window);
-    if (!m) die("--window must look like 08:00-17:00");
-    body.sending_window_start = m[1];
-    body.sending_window_end = m[2];
-  }
-  if (args.skipWeekends) body.skip_weekends = true;
-  if (args.noSkipWeekends) body.skip_weekends = false;
-  const res = await request("POST", args.base, "/api/sequencer/campaigns", { key, body });
+  const body = { name };
+  if (args.timezone) body.timezone = args.timezone;
+  if (args.dailyLimit) body.daily_limit = parseLimit(args.dailyLimit, "--daily-limit");
+  if (args.gap) {
+    const m = /^(\d+)(?:-(\d+))?$/.exec(args.gap);
+    if (!m) die("--gap must look like 60-120 (minutes between two sends from one mailbox)");
+    body.gap_minutes_min = Number(m[1]);
+    body.gap_minutes_max = Number(m[2] || m[1]);
+  }
+  if (args.start) {
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(args.start)) die("--start must be YYYY-MM-DD");
+    body.planned_start_date = args.start;
+  }
+  if (args.html) body.plain_text = false;
+  const res = await request("POST", args.base, "/api/v1/campaigns", { key, body });
   const r = need(res, "campaigns create");
-  const c = r.campaign || {};
+  const c = r.campaign || r;
   if (args.json) return console.log(JSON.stringify(r, null, 2));
-  console.log(green("✓") + ` Created campaign ${bold(c.name)} ${dim(c.id)}`);
-  console.log(
-    dim(
-      `  ${c.status} · ${c.default_timezone} · ${c.sending_window_start}–${c.sending_window_end} · skip weekends: ${c.skip_weekends}`
-    )
+  console.log(green("✓") + ` Created campaign ${bold(c.name || name)} ${dim(c.id)}`);
+  console.log(dim(`  ${c.status || "draft"} · ${c.default_timezone || body.timezone || "America/New_York"} · ${c.daily_limit || body.daily_limit || 100} a day`));
+  console.log(dim(`Next:  argorant campaigns emails set ${c.id} --step 1 --subject "..." --body-file ./copy.txt`));
+}
+
+// emails: the whole sequence at once (--file emails.json, or - for stdin) or
+// one step merged into what is already there (--step n ...).
+async function campaignsEmails(argv) {
+  const sub = argv[0];
+  if (sub !== "set") {
+    die(
+      'usage: argorant campaigns emails set <campaign> --file emails.json\n' +
+        '   or: argorant campaigns emails set <campaign> --step <n> --subject "..." (--body-file <path> | --body <text|->) [--delay-days <d>] [--new-thread]\n' +
+        '  emails.json: [{"subject":"...","body":"...","delay_days":0},{"body":"...","delay_days":3}]'
+    );
+  }
+  const key = requireKey();
+  const args = readFlags(
+    argv.slice(1),
+    { "--file": "file", "--step": "step", "--subject": "subject", "--body": "body", "--body-file": "bodyFile", "--delay-days": "delayDays" },
+    { "--new-thread": "newThread" }
   );
-  console.log(dim(`Next:  argorant campaigns steps set ${c.id} --step 1 --subject "..." --body-file ./copy.txt`));
+  const identifier = args._[0];
+  if (!identifier) die("usage: argorant campaigns emails set <campaign> ...");
+  const campaignId = await resolveCampaign(args.base, key, identifier);
+  let emails;
+  if (args.file) {
+    const text = args.file === "-" ? await readStdin() : (() => { try { return fs.readFileSync(args.file, "utf8"); } catch { die(`cannot read file: ${args.file}`); } })();
+    try { emails = JSON.parse(text); } catch (e) { die(`${args.file}: not valid JSON (${e.message})`); }
+    if (!Array.isArray(emails) || !emails.length) die("emails.json must be a non-empty array");
+  } else {
+    const step = Number(args.step);
+    if (!Number.isInteger(step) || step < 1) die("--step must be 1, 2, 3 …");
+    let body = args.body;
+    if (args.bodyFile) { try { body = fs.readFileSync(args.bodyFile, "utf8"); } catch { die(`cannot read file: ${args.bodyFile}`); } }
+    else if (body === "-") body = await readStdin();
+    if (!body || !body.trim()) die("give the email text with --body or --body-file");
+    if (step === 1 && !(args.subject || "").trim()) die("the first email needs --subject");
+    // merge into the current sequence
+    const cur = need(await request("GET", args.base, `/api/v1/campaigns/${campaignId}`, { key }), "campaign");
+    const existing = (cur.emails || []).map((e) => ({ subject: e.subject || "", body: e.body || "", delay_days: e.delay_days || 0, same_thread: e.same_thread !== false }));
+    while (existing.length < step) existing.push({ subject: "", body: "", delay_days: 3, same_thread: true });
+    existing[step - 1] = {
+      subject: (args.subject || existing[step - 1].subject || "").trim(),
+      body,
+      delay_days: args.delayDays !== undefined ? Number(args.delayDays) : (step === 1 ? 0 : existing[step - 1].delay_days || 3),
+      same_thread: !args.newThread,
+    };
+    emails = existing.filter((e) => e.body && e.body.trim());
+  }
+  const res = await request("POST", args.base, `/api/v1/campaigns/${campaignId}/emails`, { key, body: { emails } });
+  const r = need(res, "campaigns emails set");
+  if (args.json) return console.log(JSON.stringify(r, null, 2));
+  console.log(green("✓") + ` Saved ${(r.emails || emails).length} email(s) for ${dim(campaignId)}`);
+}
+
+// senders: which connected mailboxes send this campaign.
+async function campaignsSenders(argv) {
+  const sub = argv[0];
+  if (sub !== "set") die("usage: argorant campaigns senders set <campaign> --emails a@x.com,b@y.com | --all");
+  const key = requireKey();
+  const args = readFlags(argv.slice(1), { "--emails": "emails" }, { "--all": "all" });
+  const identifier = args._[0];
+  if (!identifier) die("usage: argorant campaigns senders set <campaign> --emails a@x.com,b@y.com | --all");
+  const campaignId = await resolveCampaign(args.base, key, identifier);
+  const emails = String(args.emails || "").split(",").map((x) => x.trim()).filter(Boolean);
+  if (!emails.length && !args.all) die("give --emails <a,b,c> or --all (see: argorant inboxes list)");
+  const res = await request("POST", args.base, `/api/v1/campaigns/${campaignId}/senders`, { key, body: { emails, all_connected: !!args.all } });
+  const r = need(res, "campaigns senders set");
+  if (args.json) return console.log(JSON.stringify(r, null, 2));
+  console.log(green("✓") + ` ${r.attached || 0} sender(s) attached` + (r.senders && r.senders.length ? dim(`  ${r.senders.join(", ")}`) : ""));
 }
 
 async function campaignsSteps(argv) {
@@ -1165,153 +1326,133 @@ async function campaignsInboxes(argv) {
 
 async function campaignsLeads(argv) {
   const sub = argv[0];
-  if (sub !== "add") {
-    die(
-      'usage: argorant campaigns leads add <campaign> --csv <file>\n' +
-        '   or: argorant campaigns leads add <campaign> --query "..." [filters] -n <n>'
-    );
-  }
+  const usage =
+    'usage: argorant campaigns leads add <campaign> --list <list-id>\n' +
+    '   or: argorant campaigns leads add <campaign> --csv <file>        (columns: email, first_name, last_name, company, title)\n' +
+    '   or: argorant campaigns leads add <campaign> --query "..." [filters] -n <n>   (operator keys)';
+  if (sub !== "add") die(usage);
   const key = requireKey();
-  const valueFlags = { ...CAMPAIGN_FILTER_VALUE_FLAGS, "--csv": "csv", "-n": "limit", "--limit": "limit" };
-  const args = readFlags(argv.slice(1), valueFlags, CAMPAIGN_FILTER_BOOL_FLAGS);
+  const valueFlags = { ...CAMPAIGN_FILTER_VALUE_FLAGS, "--csv": "csv", "--file": "csv", "--list": "list", "-n": "limit", "--limit": "limit" };
+  const args = readFlags(argv.slice(1), valueFlags, { ...CAMPAIGN_FILTER_BOOL_FLAGS, "--include-catch-all": "includeCatchAll" });
   const identifier = args._[0];
-  if (!identifier) {
-    die(
-      'usage: argorant campaigns leads add <campaign> --csv <file>\n' +
-        '   or: argorant campaigns leads add <campaign> --query "..." [filters] -n <n>'
-    );
-  }
+  if (!identifier) die(usage);
   const campaignId = await resolveCampaign(args.base, key, identifier);
-  const body = {};
-  if (args.csv) {
-    let text;
-    try {
-      text = fs.readFileSync(args.csv, "utf8");
-    } catch {
-      die(`cannot read file: ${args.csv}`);
-    }
-    if (!text.trim()) die(`file is empty: ${args.csv}`);
-    body.csv_text = text;
-  } else {
-    const filters = {};
-    for (const field of Object.values(CAMPAIGN_FILTER_VALUE_FLAGS)) if (args[field]) filters[field] = args[field];
-    for (const field of Object.values(CAMPAIGN_FILTER_BOOL_FLAGS)) if (args[field]) filters[field] = "true";
-    if (!Object.keys(filters).length) {
-      die(
-        'provide --csv <file>, or at least one filter: --query "..." --title --country --industry ' +
-          "--seniority --department --state --city --company --domain --has-phone --has-linkedin --has-email"
-      );
-    }
-    // GAP (see GODMODE-PLAN.md): the sequencer's filter-enroll endpoint has no
-    // per-request row cap — it enrolls every valid match up to its own
-    // server-side limit (currently 50,000). -n/--limit is accepted here for a
-    // familiar CLI surface but is NOT forwarded/honored; warn rather than
-    // silently ignoring a flag the caller explicitly set.
-    if (args.limit) {
-      warn("-n/--limit is not honored by campaign lead enrollment yet (platform-side gap, see GODMODE-PLAN.md) — it enrolls every valid match.");
+
+  if (args.list || args.csv) {
+    const body = { include_catch_all: !!args.includeCatchAll };
+    if (args.list) body.list_id = parseLimit(args.list, "--list");
+    else {
+      let text;
+      try { text = fs.readFileSync(args.csv, "utf8"); } catch { die(`cannot read file: ${args.csv}`); }
+      const lines = text.split(/\r?\n/).filter((l) => l.trim());
+      if (lines.length < 2) die(`file has no rows: ${args.csv}`);
+      const head = lines.shift().split(",").map((h) => h.trim().toLowerCase().replace(/\s+/g, "_"));
+      if (!head.includes("email")) die("the CSV needs an email column");
+      body.rows = lines.map((ln) => {
+        const cells = ln.split(",");
+        const row = {};
+        head.forEach((h, i) => { if (h) row[h] = (cells[i] || "").trim(); });
+        return row;
+      });
     }
-    body.filters = filters;
+    const res = await request("POST", args.base, `/api/v1/campaigns/${campaignId}/leads`, { key, body });
+    const r = need(res, "campaigns leads add");
+    if (args.json) return console.log(JSON.stringify(r, null, 2));
+    const v = r.verification_counts || {};
+    console.log(green("✓") + ` Enrolled ${Number(r.inserted || 0).toLocaleString()} of ${Number(r.input_rows || 0).toLocaleString()}`);
+    console.log(dim(`  duplicates ${r.duplicates_skipped || 0} · not valid ${r.skipped_not_valid || 0} (invalid ${v.invalid || 0}, catch-all ${v.catch_all || 0}) · checking in background ${r.queued_for_verification || 0}`));
+    return;
   }
+
+  // Filter enrollment straight from the database: operator keys.
+  const filters = {};
+  for (const field of Object.values(CAMPAIGN_FILTER_VALUE_FLAGS)) if (args[field]) filters[field] = args[field];
+  for (const field of Object.values(CAMPAIGN_FILTER_BOOL_FLAGS)) if (args[field]) filters[field] = "true";
+  if (!Object.keys(filters).length) die(usage);
+  const body = { filters };
+  if (args.limit) body.limit = parseLimit(args.limit, "-n");
   const res = await request("POST", args.base, `/api/sequencer/campaigns/${campaignId}/leads/import`, { key, body });
   const r = need(res, "campaigns leads add");
   if (args.json) return console.log(JSON.stringify(r, null, 2));
-  console.log(
-    green("✓") +
-      ` ${bold(r.inserted || 0)} lead(s) added` +
-      (r.duplicates_skipped ? dim(` (${r.duplicates_skipped} duplicate already in campaign)`) : "")
-  );
-  if (r.queued_for_verification) {
-    console.log(dim(`  ${r.queued_for_verification} queued for verification — will join once confirmed deliverable`));
-  }
-  if (r.skipped_not_valid) console.log(dim(`  ${r.skipped_not_valid} skipped (not deliverable)`));
-  if (r.invalid_email_rows) console.log(dim(`  ${r.invalid_email_rows} row(s) had no usable email`));
+  console.log(green("✓") + ` Imported ${Number(r.inserted || 0).toLocaleString()} lead(s)` + dim(`  (skipped ${r.duplicates_skipped || 0} duplicates, ${r.invalid_rows || 0} invalid)`));
 }
 
-async function campaignsSetStatus(argv, status, verb) {
+async function campaignsSetStatus(argv, action) {
   const key = requireKey();
-  const args = readFlags(argv, {});
+  const args = readFlags(argv);
   const identifier = args._[0];
-  if (!identifier) die(`usage: argorant campaigns ${verb} <campaign>`);
+  if (!identifier) die(`usage: argorant campaigns ${action} <campaign>`);
   const campaignId = await resolveCampaign(args.base, key, identifier);
-  const res = await request("PATCH", args.base, `/api/sequencer/campaigns/${campaignId}`, { key, body: { status } });
-  if (res.status === 400 && res.json && res.json.detail && typeof res.json.detail === "object") {
-    const d = res.json.detail;
-    const blockers = d.blockers || [];
-    die(
-      `cannot ${verb} campaign: ${d.message || "blocked"}` +
-        (blockers.length ? "\n" + blockers.map((b) => `  - ${b}`).join("\n") : "")
-    );
+  if (action === "launch" && !args.yes) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const ok = await new Promise((r) => rl.question(`Launch ${campaignId} and start sending real email? [y/N] `, (a) => { rl.close(); r(/^y/i.test(a)); }));
+    if (!ok) return console.log(dim("aborted"));
   }
-  const r = need(res, `campaigns ${verb}`);
+  const res = await request("POST", args.base, `/api/v1/campaigns/${campaignId}/${action}`, { key, body: {} });
+  const r = need(res, `campaigns ${action}`);
   if (args.json) return console.log(JSON.stringify(r, null, 2));
   const c = r.campaign || {};
-  console.log(green("✓") + ` Campaign ${bold(c.name || campaignId)} is now ${bold(c.status || status)}`);
+  console.log(green("✓") + ` ${bold(c.name || campaignId)} is now ${bold(c.status || action)}`);
 }
 
 async function campaignsStatus(argv) {
   const key = requireKey();
-  const args = readFlags(argv, {});
+  const args = readFlags(argv);
   const identifier = args._[0];
   if (!identifier) die("usage: argorant campaigns status <campaign>");
   const campaignId = await resolveCampaign(args.base, key, identifier);
-  const res = await request("GET", args.base, `/api/sequencer/campaigns/${campaignId}`, { key });
-  const r = need(res, "campaigns status");
+  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 || {};
-  if (args.json) return console.log(JSON.stringify(c, null, 2));
-  const stepsOk = Number(c.approved_step_count || 0) > 0;
-  const inboxesOk = Number(c.inbox_count || 0) > 0;
-  const leadsOk = Number(c.queued_count || 0) > 0 || Number(c.lead_count || 0) > 0;
-  const mark = (ok) => (ok ? green("✓") : red("✗"));
-  console.log(`${bold(c.name || "—")}  ${dim(c.id)}  ${dim(c.status)}`);
-  console.log(`  ${mark(stepsOk)} steps approved      ${dim(`${c.approved_step_count || 0}/${c.step_count || 0}`)}`);
-  console.log(`  ${mark(inboxesOk)} inboxes attached    ${dim(String(c.inbox_count || 0))}`);
-  console.log(
-    `  ${mark(leadsOk)} leads queued        ${dim(`${c.queued_count || 0} queued / ${c.lead_count || 0} total`)}`
-  );
-  const blockers = c.launch_blockers || [];
-  if (blockers.length) {
-    console.log(bold("\nLaunch blockers:"));
-    for (const b of blockers) console.log(`  - ${b}`);
-  } else {
-    console.log(green("\n✓ Ready to launch") + dim(`  —  argorant campaigns start ${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}  ·  ${c.daily_limit || "?"} a day  ·  ${c.default_timezone || ""}`);
+  for (const e of r.emails || []) console.log(dim(`    ${e.step}. ${e.subject || "(same thread)"}${e.step > 1 ? ` · +${e.delay_days || 0} days` : ""}`));
+  if (r.launch_blockers && r.launch_blockers.length) {
+    console.log(yellow("  before launch:"));
+    for (const b of r.launch_blockers) console.log(yellow(`    · ${b}`));
   }
+  if (c.url) console.log(dim(`  ${c.url}`));
 }
 
 function campaignsHelp() {
   const p = bold("argorant campaigns");
   console.log(`
-${bold("Argorant Campaigns")} — god-mode outbound campaign control  ${dim("(operator keys only)")}
+${bold("Argorant Campaigns")} — email outreach from the terminal
 
-Drives the internal Argorant Sequencer (${dim("/api/sequencer/*")}) — a live campaign
-in about two minutes from the terminal. Requires an ag_live_ key belonging to
-an owner/admin account with the ${bold("argorant:operator")} scope; any other key gets
-a 401/403, same as it would in a browser without outbound access.
+Works with any Argorant API key. Nothing is sent until you launch.
 
 ${bold("USAGE")}
-  ${p} list [--brand <key>]
-  ${p} create --name "<name>" [--brand <key>] [--timezone <tz>] [--window HH:MM-HH:MM] [--skip-weekends]
-  ${p} steps set <campaign> --step <n> --subject "..." (--body-file <path> | --body <text|->) [--approve]
-  ${p} inboxes attach <campaign> --count <n> [--pool <brand>]
-  ${p} leads add <campaign> --csv <file>
-  ${p} leads add <campaign> --query "..." [filters]
-  ${p} start <campaign>
+  ${p} list
+  ${p} create --name "<name>" [--daily-limit 100] [--timezone <tz>] [--gap 60-120] [--start YYYY-MM-DD]
+  ${p} emails set <campaign> --file emails.json
+  ${p} emails set <campaign> --step <n> --subject "..." (--body-file <path> | --body <text|->) [--delay-days <d>]
+  ${p} leads add <campaign> --list <list-id> | --csv <file> [--include-catch-all]
+  ${p} senders set <campaign> --emails a@x.com,b@y.com | --all
+  ${p} launch <campaign> [-y]      ${dim("asks for confirmation; sends real email")}
   ${p} pause <campaign>
+  ${p} stop <campaign>
   ${p} status <campaign>
 
-${dim("<campaign> accepts a raw id or an unambiguous case-insensitive name prefix.")}
-${dim("The CLI never writes copy for you — steps set only upserts what you give it.")}
+  ${bold("argorant inboxes")} list
+  ${bold("argorant inboxes")} connect-google --admin <admin@yourdomain.com> [--emails a,b | --all]
+
+${dim("<campaign> accepts an id or an unambiguous case-insensitive name prefix.")}
+${dim("Variables in emails: {{first_name}} {{last_name}} {{company}} {{title}}. Spintax {a|b} varies phrasing.")}
+${dim("Every address is verified before it is enrolled; only valid ones send unless --include-catch-all.")}
 
-${bold("EXAMPLE — live in two minutes")}
-  ${p} create --name "Q3 CFO outreach" --brand argorant --timezone America/New_York --window 08:00-17:00 --skip-weekends
-  ${p} steps set "Q3 CFO outreach" --step 1 --subject "Quick question" --body-file ./copy/step1.txt --approve
-  ${p} inboxes attach "Q3 CFO outreach" --count 5 --pool argorant
-  ${p} leads add "Q3 CFO outreach" --query "CFO" --industry fintech --country Germany
-  ${p} start "Q3 CFO outreach"
+${bold("EXAMPLE")}
+  ${p} create --name "Q4 CFO outreach" --daily-limit 40
+  ${p} emails set "Q4 CFO" --step 1 --subject "Quick question, {{first_name}}" --body-file ./step1.txt
+  ${p} emails set "Q4 CFO" --step 2 --body "Bumping this up." --delay-days 3
+  ${p} leads add "Q4 CFO" --list 1240
+  ${p} senders set "Q4 CFO" --all
+  ${p} launch "Q4 CFO"
 
 ${bold("OPTIONS")}
   --json         Raw JSON output      --base <url>   Override API base
 
-  Docs: ${cyan("https://argorant.com/docs/cli")}   ·   Gap notes: cli/GODMODE-PLAN.md
+  Docs: ${cyan("https://argorant.com/docs/cli")}
 `);
 }
 
@@ -1322,18 +1463,65 @@ async function cmdCampaigns(argv) {
   const table = {
     list: campaignsList,
     create: campaignsCreate,
+    emails: campaignsEmails,
     steps: campaignsSteps,
+    senders: campaignsSenders,
     inboxes: campaignsInboxes,
     leads: campaignsLeads,
-    start: (a) => campaignsSetStatus(a, "active", "start"),
-    pause: (a) => campaignsSetStatus(a, "paused", "pause"),
+    launch: (a) => campaignsSetStatus(a, "launch"),
+    start: (a) => campaignsSetStatus(a, "launch"),
+    pause: (a) => campaignsSetStatus(a, "pause"),
+    stop: (a) => campaignsSetStatus(a, "stop"),
     status: campaignsStatus,
+    get: campaignsStatus,
   };
   const fn = table[sub];
   if (!fn) die(`unknown campaigns subcommand: ${sub}\nRun \`argorant campaigns help\` for usage.`);
   await fn(rest);
 }
 
+async function cmdInboxes(argv) {
+  const sub = argv[0] || "list";
+  const key = requireKey();
+  if (sub === "list") {
+    const args = readFlags(argv.slice(1));
+    const r = need(await request("GET", args.base, "/api/v1/inboxes", { key }), "inboxes list");
+    if (args.json) return console.log(JSON.stringify(r, null, 2));
+    const rows = r.inboxes || [];
+    if (!rows.length) return console.log(dim("No mailboxes connected yet. Connect Google Workspace with `argorant inboxes connect-google --admin ...` or Microsoft 365 in the app."));
+    for (const i of rows) {
+      console.log(`${bold(i.email)}  ${dim(i.name || "")}`);
+      console.log(dim(`  ${i.provider} · ${i.status}${i.health ? ` · ${i.health}` : ""} · today ${i.sent_today || 0}/${i.daily_limit || "?"}`));
+    }
+    return;
+  }
+  if (sub === "connect-google") {
+    const args = readFlags(argv.slice(1), { "--admin": "admin", "--emails": "emails" }, { "--all": "all" });
+    if (!args.admin) die("usage: argorant inboxes connect-google --admin admin@yourdomain.com [--emails a@x.com,b@x.com | --all]");
+    const body = { admin_email: args.admin };
+    if (args.all) body.emails = [];
+    else if (args.emails) body.emails = String(args.emails).split(",").map((x) => x.trim()).filter(Boolean);
+    const r = need(await request("POST", args.base, "/api/v1/inboxes/google-workspace", { key, body }), "inboxes connect-google");
+    if (args.json) return console.log(JSON.stringify(r, null, 2));
+    if (r.ok === false && r.setup) {
+      console.log(yellow("Delegation is not active yet.") + ` ${r.reason || ""}`);
+      console.log(`In Google Admin > Security > API controls > Domain-wide delegation add:\n  Client ID: ${bold(r.setup.client_id)}\n  Scopes:    ${r.setup.scopes_csv || (r.setup.scopes || []).join(",")}`);
+      if (r.setup.delegation_url) console.log(dim(`  ${r.setup.delegation_url}`));
+      console.log(dim("Then run this command again."));
+      return;
+    }
+    if (r.mailboxes) {
+      for (const m of r.mailboxes) console.log(`${m.connected ? green("✓") : " "} ${m.email}  ${dim(m.name || "")}${m.alias ? dim("  alias") : ""}`);
+      console.log(dim("\nconnect with:  --emails a@x.com,b@x.com   or   --all"));
+      return;
+    }
+    console.log(green("✓") + ` Connected ${(r.connected || []).length} mailbox(es)`);
+    for (const c of r.connected || []) console.log(dim(`  ${c.email} · ${c.health || "ok"}`));
+    return;
+  }
+  die(`unknown inboxes subcommand: ${sub} (list, connect-google)`);
+}
+
 function help() {
   const p = bold("argorant");
   console.log(`
@@ -1351,6 +1539,9 @@ ${bold("COMMANDS")}
   ${cyan("search")} "<query>" -n 10     Preview matches, details redacted ${dim("(0 contact credits)")}
   ${cyan("sample")} <company.com>        Build 25 distinct, live-valid company leads ${dim("(free sample)")}
   ${cyan("reveal")} "<query>" -n 25     Reveal full contact details    ${dim("(uses credits; live-verified, pay only for deliverable)")}
+  ${cyan("enrich")} --email <a@b.com>   One address → the full person profile ${dim("(1 credit per match; miss = free)")}
+  ${cyan("enrich")} --name "<n>" --domain <d>   Find that person + reveal a verified email ${dim("(1 credit per match)")}
+  ${cyan("enrich")} --domain <d>        Company profile                ${dim("(0 contact credits)")}
   ${cyan("export")} "<query>" -n 1000 -o leads.csv   Verified CSV export ${dim("(uses credits)")}
   ${cyan("export status")} <job_id>     Status of an existing export  ${dim("(free; add --batch for >50k)")}
   ${cyan("export download")} <job_id> -o leads.csv   Re-download a finished export ${dim("(free)")}
@@ -1358,7 +1549,8 @@ ${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("campaigns")} ...                Live outbound campaigns from the terminal ${dim("(operator keys only — argorant campaigns help)")}
+  ${cyan("campaigns")} ...                Email outreach: create, write, enroll, launch ${dim("(argorant campaigns help)")}
+  ${cyan("inboxes")} list | connect-google  Connected mailboxes; connect a Google Workspace
 
 ${bold("FILTERS")}
   --keywords <k>     Comma = OR. The widest, most reliable filter - prefer it
@@ -1390,6 +1582,7 @@ ${bold("NON-INTERACTIVE USE")} ${dim("(agents, CI, pipes)")}
 ${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.")}
 
 ${bold("EXAMPLES")}
   ${p} count "fintech CFOs in germany"
@@ -1397,6 +1590,9 @@ ${bold("EXAMPLES")}
   ${p} search "heads of procurement" --country Germany -n 10
   ${p} sample recruitcrm.io -o sample.csv
   ${p} export --industry fintech --title CFO --country Germany -n 500 -o cfos.csv
+  ${p} enrich --email patrick@stripe.com --json
+  ${p} enrich --name "Patrick Collison" --domain stripe.com
+  ${p} enrich --domain stripe.com
   ${p} verify ceo@stripe.com
   ${p} verify --file my-list.csv -o verified.csv
 
@@ -1412,9 +1608,10 @@ async function main() {
   // `campaigns` has its own flag vocabulary (--step, --count, --pool, --csv, ...)
   // handled by readFlags — it never goes through the generic filter parser
   // below, which would reject those flags as unknown.
-  if (cmd === "campaigns") {
+  if (cmd === "campaigns" || cmd === "campaign" || cmd === "inboxes" || cmd === "inbox") {
     try {
-      await cmdCampaigns(argv.slice(1));
+      if (cmd.startsWith("campaign")) await cmdCampaigns(argv.slice(1));
+      else await cmdInboxes(argv.slice(1));
     } catch (e) {
       die(e && e.message ? e.message : String(e));
     }
@@ -1430,6 +1627,7 @@ async function main() {
     search: cmdSearch,
     sample: cmdSample,
     reveal: cmdReveal,
+    enrich: cmdEnrich,
     export: cmdExport,
     list: cmdList,
     verify: cmdVerify,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "argorant",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Search, count, reveal, export, and verify B2B contacts from the Argorant database — from your terminal, scripts, or coding agent.",
   "bin": {
     "argorant": "bin/argorant.js"