groundmail-cli 0.43.0 → 0.44.0

package/README.md

@@ -147,6 +147,16 @@ groundmail suppressions list --type category_opt_out --tenant cus_123
 groundmail suppressions remove --type category_opt_out --email reader@example.com --category newsletter --tenant cus_123
 ```
 
+## Updating
+
+The CLI tells you when a newer version is out, at most once a day and never in CI or a pipe. To update:
+
+```bash
+npm install -g groundmail-cli@latest
+```
+
+Set `GROUNDMAIL_NO_UPDATE_NOTIFIER=1` to turn the notice off.
+
 ## Docs
 
 - CLI: https://docs.groundmail.dev/cli

package/dist/cli.js

@@ -39,10 +39,10 @@ function idLike(token) {
 }
 function shortenReply(reply, max) {
   if (reply.length <= LABEL_WIDTH) return reply;
-  const parts = reply.split(/(\s+)/);
+  const parts2 = reply.split(/(\s+)/);
   const out = [];
   let inRun = false;
-  for (const part of parts) {
+  for (const part of parts2) {
     if (/^\s+$/.test(part)) {
       if (!inRun) out.push(part);
       continue;
@@ -2089,6 +2089,213 @@ async function runListKeysCommandWithClient(args, env = process.env) {
   }
 }
 
+// package.json
+var version = "0.44.0";
+
+// src/help.ts
+var USAGE_LINES = [
+  "  groundmail login [--scope <scopes>] [--workspace <name>]   sign in through the browser (OAuth; no key to copy)",
+  "  groundmail logout [--workspace <name>|--all]   revokes the sign-in server-side",
+  "  groundmail whoami",
+  "  groundmail auth token [--scope <scopes>]   print a short-lived access token (for agents and scripts)",
+  "  groundmail workspaces list",
+  "  groundmail workspaces use <name|id>",
+  "  groundmail domains add example.com [--tenant <tenant>]",
+  "  groundmail domains apply example.com --provider cloudflare",
+  "  groundmail domains apply example.com --provider vercel",
+  "  groundmail domains apply example.com --provider godaddy",
+  "  groundmail domains list [--tenant <tenant>]",
+  "  groundmail domains get example.com",
+  "  groundmail domains update example.com --inbound true",
+  "  groundmail domains verify example.com",
+  "  groundmail domains delete example.com",
+  "  groundmail dmarc status example.com [--json]   DMARC monitoring: sources, pass rates, readiness",
+  "  groundmail dmarc enable example.com [--apply cloudflare|vercel|godaddy|netlify|digitalocean|dnsimple]   report address and the record to publish",
+  "  groundmail dmarc digest example.com --on|--off   weekly digest email",
+  "  groundmail dmarc disable example.com",
+  "  groundmail received-emails list [--domain inbound.example.com] [--in-reply-to-email msg_...]",
+  "  groundmail received-emails get inb_...",
+  "  groundmail test-inbox address [--prefix signup]   a fresh address on your team's test domain (mail there is caught, never delivered)",
+  "  groundmail test-inbox wait --to <address> [--timeout 30] [--since <iso>] [--json]   wait for an email; prints its code and links (exit 2 on timeout)",
+  "  groundmail test-inbox list [--to <address>] [--since <iso>] [--json]",
+  "  groundmail mailboxes create --instant [--owner-email you@example.com]   no account or key needed",
+  "  groundmail mailboxes owner <mailbox> --owner-email you@example.com   send your person a code",
+  "  groundmail mailboxes verify <mailbox> --code 482913   unlock sending",
+  "  groundmail mailboxes create [--local-part signup-bot] [--domain agents.example.com] [--display-name \u2026] [--external-id \u2026] [--tenant <tenant>] [--retention-days 7] [--spam-threshold 5] [--metadata JSON] [--forward-from <mailbox>] [--json]   a real address your agent reads and sends from; no --domain: a hosted address, which can only reply; --forward-from: a hosted mailbox this one replaces",
+  "  groundmail mailboxes list [--tenant <tenant>] [--limit 25] [--cursor \u2026] [--json]",
+  "  groundmail mailboxes get <mailbox> [--json]",
+  "  groundmail mailboxes delete <mailbox> --yes   the mailbox and all its mail; a hosted address is never given out again",
+  "  groundmail mailboxes forward <mailbox> --to <new mailbox> --yes   move a hosted address to a mailbox on your own domain, for 30 days; it can't send meanwhile",
+  "  groundmail mailboxes threads <mailbox> [--label \u2026] [--participant \u2026] [--unread] [--archived] [--since <iso>] [--include-held] [--limit 25] [--cursor \u2026] [--json]",
+  "  groundmail mailboxes read <mailbox> [mbm_\u2026|thd_\u2026] [--search \u2026] [--from \u2026] [--thread thd_\u2026] [--label \u2026] [--unread] [--since <iso>] [--include-held] [--limit 25] [--cursor \u2026] [--json]   one message or thread; with no id, list or search messages",
+  "  groundmail mailboxes wait <mailbox> [--from \u2026] [--thread thd_\u2026] [--since <iso>] [--timeout 30] [--json]   wait for the next message; prints its code and links (exit 2 on timeout)",
+  "  groundmail mailboxes send <mailbox> --to a@example.com,b@example.com [--cc \u2026] --subject \u2026 (--text \u2026 | --html \u2026) [--idempotency-key \u2026] [--json]   email someone first, from a mailbox on your own domain",
+  "  groundmail mailboxes reply <mailbox> mbm_\u2026 (--text \u2026 | --html \u2026) [--reply-all] [--idempotency-key \u2026] [--json]   reply in the thread",
+  `  groundmail emails send [--from you@domain.com | --sender billing] --to user@example.com --subject "Hello" --html "<p>Hi</p>" [--category transactional|product|newsletter] [--unsubscribe] [--tenant <tenant>] [--watch [--timeout 60] [--json]]   --sender: a saved sender's handle; no --from or --sender: the sandbox sender (to your account email only)`,
+  '  groundmail emails send --to you@example.com --subject "Hello" --text "Hi" --watch   watch it land: the receiving server, its reply and the time',
+  "  groundmail emails batch --file ./emails.json [--tenant <tenant>]",
+  "  groundmail emails list [--limit 25] [--cursor \u2026] [--test | --live] [--tenant <tenant>] [--stream transactional|product|newsletter]",
+  "  groundmail emails insights [--window 7d|30d]",
+  "  groundmail emails get --id msg_\u2026 [--watch [--timeout 60] [--json]]   --watch: follow an email you already sent until it lands",
+  "  groundmail emails cancel --id msg_\u2026",
+  "  groundmail batches get <batch_id>   an emails batch's status counts (the batch_id `emails batch` returned)",
+  "  groundmail batches cancel <batch_id>   cancel the batch's emails that are still scheduled; safe to repeat",
+  "  groundmail emails resend --id msg_\u2026",
+  `  groundmail events send --name user.created --email user@example.com --data '{"name":"Ada"}'`,
+  "  groundmail automations list",
+  "  groundmail automations create --file ./welcome.json",
+  `  groundmail automations create --name Welcome --trigger user.created --steps '[{"type":"send_email","email":{"from":"you@yourdomain.com","to":"{{event.email}}","template":{"id":"welcome","variables":{"name":"{{event.data.name}}"}}}}]'   each email step sends a published template`,
+  "  groundmail automations create --file ./otp-sms.json",
+  "  groundmail automations get --id <automation-id>",
+  "  groundmail automations update --id <automation-id> --file ./welcome.json",
+  '  groundmail automations update --id <automation-id> --folder Onboarding   (--folder "" takes it out of any folder)',
+  "  groundmail automations activate --id <automation-id>",
+  "  groundmail automations pause --id <automation-id>",
+  "  groundmail automations delete --id <automation-id>",
+  "  groundmail webhooks list",
+  "  groundmail webhooks create --url https://yourapp.com/hooks [--tenants a,b] [--mailboxes mbx_a,mbx_b]   --tenants: only these tenants' email events; --mailboxes: only these mailboxes' events",
+  "  groundmail webhooks get --id wh_\u2026",
+  "  groundmail webhooks update --id wh_\u2026 [--url \u2026] [--event email.sent] [--enabled true|false] [--tenants a,b|all] [--mailboxes mbx_a,mbx_b|all]",
+  "  groundmail webhooks delete --id <webhook-id>",
+  "  groundmail webhooks deliveries list --webhook <webhook-id> [--status failed] [--event email.delivered] [--email-id msg_\u2026] [--q \u2026] [--test true|false] [--limit 25] [--cursor \u2026]",
+  "  groundmail webhooks deliveries get --webhook <webhook-id> --id <delivery-id>",
+  "  groundmail webhooks deliveries resend --webhook <webhook-id> --id <delivery-id>",
+  "  groundmail validate user@example.com   Groundmail validation: verdict, reasons, typo suggestion (exit 2 when invalid)",
+  "  groundmail burrowguard sites   the forms BurrowGuard protects",
+  '  groundmail burrowguard sites create --name "Sign-up form" --hostname app.example.com [--hostname localhost] [--block-free-webmail] [--allow-data-center-ips] [--email-checks-only] [--watch-only]   prints the secret once',
+  "  groundmail burrowguard sites update <id> --watch-only | --no-watch-only   show what would be blocked without blocking anyone, or start blocking",
+  "  groundmail burrowguard sites roll-secret <id> --yes   the old secret stops working at once",
+  "  groundmail burrowguard sites delete <id> --yes",
+  "  groundmail burrowguard checks [--site <id>] [--result passed|blocked|would_block|no_token] [--range 24h|7d|30d] [--limit 25]",
+  "  groundmail suppressions list [--tenant <tenant>]",
+  "  groundmail suppressions add --email user@example.com [--reason \u2026] [--tenant <tenant>]",
+  "  groundmail suppressions remove --id <id> | --email user@example.com [--tenant <tenant>]",
+  "  groundmail suppressions list --type category_opt_out [--category product|newsletter] [--tenant <tenant> | --include-tenants]   one-click category unsubscribes",
+  "  groundmail suppressions remove --type category_opt_out --email user@example.com [--category newsletter] [--tenant <tenant>]   re-subscribe to a category",
+  "  groundmail templates list [--status draft|published]",
+  "  groundmail templates starters",
+  "  groundmail templates from-starter password-reset",
+  '  groundmail templates create --name Welcome --subject "Hi" --html "<p>Hi</p>" [--category transactional|product] [--unsubscribe-enabled] [--folder Onboarding] [--sender billing]',
+  "  groundmail templates get --id tpl_\u2026",
+  "  groundmail templates update --id tpl_\u2026 [--name \u2026] [--subject \u2026] [--html \u2026] [--text \u2026] [--set-alias \u2026] [--category transactional|product] [--unsubscribe-enabled|--no-unsubscribe-enabled] [--folder \u2026] [--sender billing|none]",
+  "  groundmail templates publish --id tpl_\u2026",
+  `  groundmail templates push ./emails/welcome.tsx --alias welcome [--subject "Welcome"] [--props '{"name":"Ada"}'] [--publish]`,
+  "  groundmail templates versions --id tpl_\u2026",
+  "  groundmail templates restore --id tpl_\u2026 --version 2",
+  "  groundmail templates test-send --id tpl_\u2026 --to you@domain.com [--from you@domain.com | --sender billing]   neither: the template's sender, else your default sender",
+  '  groundmail templates duplicate --id tpl_\u2026 [--name "Copy"]',
+  "  groundmail templates delete --id tpl_\u2026   refused while an automation step sends it (the error names them)",
+  "  groundmail tenants list [--status active|paused] [--limit 25] [--cursor \u2026]   your customers, each with its own domains, suppressions and limits",
+  `  groundmail tenants create <external-id> [--name \u2026] [--default-from-domain \u2026] [--stream-policy all|transactional_only] [--daily-limit N] [--metadata '{"plan":"pro"}']`,
+  "  groundmail tenants get <tenant>",
+  "  groundmail tenants update <tenant> [--name \u2026] [--default-from-domain \u2026|none] [--stream-policy \u2026] [--daily-limit N|none] [--metadata JSON|null]",
+  "  groundmail tenants pause <tenant> [--reason \u2026]   stops the tenant's new sends",
+  "  groundmail tenants resume <tenant>",
+  "  groundmail tenants delete <tenant> --yes",
+  "  groundmail tenants stats <tenant> [--days 7]",
+  "  groundmail tenants domains list <tenant>",
+  "  groundmail tenants domains add <tenant> example.com   only this tenant can then send from it",
+  "  groundmail tenants domains remove <tenant> example.com   gives the domain back to the account",
+  "  groundmail brand get   your logo, colors and footer, which templates follow",
+  '  groundmail brand set [--logo-url <https url>|none] [--logo-align left|center] [--logo-width 120] [--color #2f6feb] [--company "Acme Inc"|none] [--address "\u2026"|none] [--website acme.com|none] [--settings-file brand.json]   --color: buttons, links and the line across the top',
+  "  groundmail senders list   the names and addresses your email goes out as",
+  '  groundmail senders create --name "Acme Billing" --address billing@mail.acme.com [--reply-to billing@acme.com] [--handle billing] [--default]   address on a verified domain',
+  "  groundmail senders get <id|handle>",
+  "  groundmail senders update <id|handle> [--name \u2026] [--address \u2026] [--reply-to \u2026|none] [--handle \u2026] [--default|--no-default]",
+  "  groundmail senders delete <id|handle> --yes   refused while an automation or template uses it",
+  "  groundmail keys list",
+  "  groundmail keys create [--name Default] [--scopes emails:send,domains:read] [--allowed-domains example.com] [--test] [--tenant <tenant>] [--mailboxes mbx_a,mbx_b]   --test: a gm_test_ key, sends are simulated; --tenant: a key limited to one tenant; --mailboxes: a key for one agent, limited to its mailboxes",
+  "  groundmail keys delete --id <api-key-id>",
+  "  groundmail migrate sendgrid [--dry-run] [--only templates,suppressions,domains,webhooks] [--region eu]   import from SendGrid (Beta)",
+  "  groundmail migrate postmark [--dry-run] [--only \u2026]   import from Postmark (Beta)",
+  "  groundmail migrate mailgun [--dry-run] [--only \u2026] [--region eu]   import from Mailgun (Beta)",
+  "  groundmail migrate resend [--dry-run] [--only \u2026]   import from Resend (Beta; a Full access key)",
+  "  groundmail migrate ses --region us-east-1 [--dry-run] [--only \u2026]   import one Amazon SES region (Beta)",
+  "  groundmail migrate list                          your recent imports",
+  "  groundmail migrate report <id> [--csv]           an import report (JSON, or CSV to stdout)",
+  "  groundmail integrations twilio status",
+  "  groundmail integrations twilio connect --account-sid AC\u2026 --auth-token \u2026 --from +15551234567",
+  "  groundmail integrations twilio disconnect"
+];
+var FOOTER_LINES = [
+  "Environment:",
+  "  GROUNDMAIL_API_KEY=gm_\u2026   optional (CI): wins over the `groundmail login` sign-in",
+  "  GROUNDMAIL_NO_KEYCHAIN=1  keep the refresh token in the config file (0600) instead of the OS keychain",
+  "  GROUNDMAIL_NO_UPDATE_NOTIFIER=1  turn off the update notice",
+  "  TWILIO_ACCOUNT_SID=AC\u2026 TWILIO_AUTH_TOKEN=\u2026 TWILIO_DEFAULT_FROM=+1\u2026  (integrations twilio connect)",
+  "  CLOUDFLARE_API_TOKEN=\u2026            (optional local apply; else uses dashboard Integrations)",
+  "  VERCEL_API_TOKEN=\u2026 VERCEL_TEAM_ID=\u2026  (optional local apply; else uses dashboard Integrations)",
+  "  GODADDY_PAT=\u2026  or GODADDY_API_KEY=\u2026 GODADDY_API_SECRET=\u2026  (domains apply --provider godaddy)",
+  "  SENDGRID_API_KEY / POSTMARK_SERVER_TOKEN (+ POSTMARK_ACCOUNT_TOKEN) / MAILGUN_API_KEY / RESEND_API_KEY  (migrate; used once, never stored)",
+  "  AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY (+ AWS_SESSION_TOKEN, AWS_REGION)  (migrate ses; used once, never stored)",
+  "",
+  "Scopes: full, emails:send, emails:read, domains:read, domains:write, webhooks:write, templates:write,",
+  "        suppressions:write, account:read, mailboxes:read, mailboxes:write, mailboxes:send",
+  "",
+  "<tenant>: the tenant's external id (your id for that customer) or its Groundmail id.",
+  "<mailbox>: the mailbox's mbx_ id, its address or your external id.",
+  "",
+  "--watch exit codes: 0 delivered, 1 error, 3 bounced or failed, 4 still on its way at --timeout, 5 test send (never delivered).",
+  "",
+  "Add --help to any command for just its usage. --version prints the CLI version."
+];
+var CLI_VERSION = version;
+var ALIASES = {
+  workspace: { "": "workspaces" },
+  domains: { create: "add", remove: "delete" },
+  events: { trigger: "send" },
+  automations: { add: "create", remove: "delete" },
+  suppressions: { create: "add", delete: "remove" },
+  templates: { add: "create", remove: "delete" },
+  tenants: { add: "create", remove: "delete" },
+  mailboxes: { add: "create", remove: "delete" },
+  senders: { add: "create", remove: "delete" },
+  brand: { update: "set" }
+};
+function words(line) {
+  return line.trim().split(/\s+/);
+}
+function fullUsage() {
+  return ["Usage:", ...USAGE_LINES, "", ...FOOTER_LINES].join("\n");
+}
+function unknownCommandMessage(argv) {
+  const typed = argv.filter((arg) => !arg.startsWith("-")).slice(0, 2).join(" ");
+  return `Unknown command: groundmail ${typed}
+${outdatedHint()}`;
+}
+function outdatedHint() {
+  return `You're on groundmail-cli ${CLI_VERSION}. If the docs show this, your version may be out of date: npm install -g groundmail-cli@latest`;
+}
+function usageFor(command, subcommand) {
+  if (!command) return fullUsage();
+  const name = ALIASES[command]?.[""] ?? command;
+  const forCommand = USAGE_LINES.filter((line) => words(line)[1] === name);
+  if (!forCommand.length) return null;
+  const sub = subcommand && !subcommand.startsWith("-") ? ALIASES[name]?.[subcommand] ?? subcommand : void 0;
+  const forSub = sub ? forCommand.filter((line) => words(line)[2] === sub) : [];
+  return ["Usage:", ...forSub.length ? forSub : forCommand].join("\n");
+}
+function isHelpFlag(arg) {
+  return arg === "--help" || arg === "-h";
+}
+function isVersionFlag(arg) {
+  return arg === "--version" || arg === "-v" || arg === "-V";
+}
+function resolveMetaRequest(argv) {
+  const [command, subcommand] = argv;
+  if (isVersionFlag(command) || command === "version") return { kind: "version", text: CLI_VERSION };
+  if (!command) return null;
+  if (isHelpFlag(command)) return { kind: "help", text: fullUsage() };
+  if (command === "help") {
+    return { kind: "help", text: usageFor(argv[1], argv[2]) ?? fullUsage() };
+  }
+  if (argv.some(isHelpFlag)) {
+    const sub = isHelpFlag(subcommand) ? void 0 : subcommand;
+    return { kind: "help", text: usageFor(command, sub) ?? fullUsage() };
+  }
+  return null;
+}
+
 // src/session/brand.ts
 var GROUNDMAIL = {
   bin: "groundmail",
@@ -2112,9 +2319,6 @@ function trimUrl(value) {
   return (value ?? "").trim().replace(/\/+$/, "");
 }
 
-// package.json
-var version = "0.43.0";
-
 // src/user-agent.ts
 var AGENT_ENV = [
   ["claude-code", ["CLAUDECODE", "CLAUDE_CODE"]],
@@ -2993,7 +3197,23 @@ function readFlag17(args, flag) {
   if (index === -1) return void 0;
   return args[index + 1];
 }
+var KNOWN_FLAGS = /* @__PURE__ */ new Set([
+  "--api-key",
+  "--base-url",
+  "--name",
+  "--scope",
+  "--scopes",
+  "--allowed-domains",
+  "--test",
+  "--tenant",
+  "--mailboxes"
+]);
 async function runCreateKeyCommandWithClient(args, env = process.env) {
+  const unknown = args.find((arg) => arg.startsWith("--") && !KNOWN_FLAGS.has(arg.split("=")[0]));
+  if (unknown) {
+    return { exitCode: 1, error: `Unknown option ${unknown}. No key was created.
+${outdatedHint()}` };
+  }
   const apiKey = readFlag17(args, "--api-key") || env.GROUNDMAIL_API_KEY;
   const baseUrl = readFlag17(args, "--base-url") || defaultApiUrl(env);
   if (!apiKey) {
@@ -5056,8 +5276,8 @@ function formatMessage(message) {
 }
 function formatThread(thread) {
   const head = [`Thread:  ${thread.id}`, `Subject: ${oneLine(thread.subject)}`, `With:    ${oneLine(thread.participants.join(", "))}`];
-  const parts = thread.messages.map((message) => [...messageHeader(message), "", plain(message.reply_text ?? message.visible_text) || "(no visible text)"].join("\n"));
-  return [UNTRUSTED_LINE, ...head, ...parts.flatMap((part) => ["", "---", part])].join("\n");
+  const parts2 = thread.messages.map((message) => [...messageHeader(message), "", plain(message.reply_text ?? message.visible_text) || "(no visible text)"].join("\n"));
+  return [UNTRUSTED_LINE, ...head, ...parts2.flatMap((part) => ["", "---", part])].join("\n");
 }
 function threadRow(thread) {
   const unread = thread.unread_count ? `  ${thread.unread_count} unread` : "";
@@ -5289,199 +5509,81 @@ async function runMailboxesCommand(subcommand, argv, env = process.env) {
   }
 }
 
-// src/help.ts
-var USAGE_LINES = [
-  "  groundmail login [--scope <scopes>] [--workspace <name>]   sign in through the browser (OAuth; no key to copy)",
-  "  groundmail logout [--workspace <name>|--all]   revokes the sign-in server-side",
-  "  groundmail whoami",
-  "  groundmail auth token [--scope <scopes>]   print a short-lived access token (for agents and scripts)",
-  "  groundmail workspaces list",
-  "  groundmail workspaces use <name|id>",
-  "  groundmail domains add example.com [--tenant <tenant>]",
-  "  groundmail domains apply example.com --provider cloudflare",
-  "  groundmail domains apply example.com --provider vercel",
-  "  groundmail domains apply example.com --provider godaddy",
-  "  groundmail domains list [--tenant <tenant>]",
-  "  groundmail domains get example.com",
-  "  groundmail domains update example.com --inbound true",
-  "  groundmail domains verify example.com",
-  "  groundmail domains delete example.com",
-  "  groundmail dmarc status example.com [--json]   DMARC monitoring: sources, pass rates, readiness",
-  "  groundmail dmarc enable example.com [--apply cloudflare|vercel|godaddy|netlify|digitalocean|dnsimple]   report address and the record to publish",
-  "  groundmail dmarc digest example.com --on|--off   weekly digest email",
-  "  groundmail dmarc disable example.com",
-  "  groundmail received-emails list [--domain inbound.example.com] [--in-reply-to-email msg_...]",
-  "  groundmail received-emails get inb_...",
-  "  groundmail test-inbox address [--prefix signup]   a fresh address on your team's test domain (mail there is caught, never delivered)",
-  "  groundmail test-inbox wait --to <address> [--timeout 30] [--since <iso>] [--json]   wait for an email; prints its code and links (exit 2 on timeout)",
-  "  groundmail test-inbox list [--to <address>] [--since <iso>] [--json]",
-  "  groundmail mailboxes create --instant [--owner-email you@example.com]   no account or key needed",
-  "  groundmail mailboxes owner <mailbox> --owner-email you@example.com   send your person a code",
-  "  groundmail mailboxes verify <mailbox> --code 482913   unlock sending",
-  "  groundmail mailboxes create [--local-part signup-bot] [--domain agents.example.com] [--display-name \u2026] [--external-id \u2026] [--tenant <tenant>] [--retention-days 7] [--spam-threshold 5] [--metadata JSON] [--forward-from <mailbox>] [--json]   a real address your agent reads and sends from; no --domain: a hosted address, which can only reply; --forward-from: a hosted mailbox this one replaces",
-  "  groundmail mailboxes list [--tenant <tenant>] [--limit 25] [--cursor \u2026] [--json]",
-  "  groundmail mailboxes get <mailbox> [--json]",
-  "  groundmail mailboxes delete <mailbox> --yes   the mailbox and all its mail; a hosted address is never given out again",
-  "  groundmail mailboxes forward <mailbox> --to <new mailbox> --yes   move a hosted address to a mailbox on your own domain, for 30 days; it can't send meanwhile",
-  "  groundmail mailboxes threads <mailbox> [--label \u2026] [--participant \u2026] [--unread] [--archived] [--since <iso>] [--include-held] [--limit 25] [--cursor \u2026] [--json]",
-  "  groundmail mailboxes read <mailbox> [mbm_\u2026|thd_\u2026] [--search \u2026] [--from \u2026] [--thread thd_\u2026] [--label \u2026] [--unread] [--since <iso>] [--include-held] [--limit 25] [--cursor \u2026] [--json]   one message or thread; with no id, list or search messages",
-  "  groundmail mailboxes wait <mailbox> [--from \u2026] [--thread thd_\u2026] [--since <iso>] [--timeout 30] [--json]   wait for the next message; prints its code and links (exit 2 on timeout)",
-  "  groundmail mailboxes send <mailbox> --to a@example.com,b@example.com [--cc \u2026] --subject \u2026 (--text \u2026 | --html \u2026) [--idempotency-key \u2026] [--json]   email someone first, from a mailbox on your own domain",
-  "  groundmail mailboxes reply <mailbox> mbm_\u2026 (--text \u2026 | --html \u2026) [--reply-all] [--idempotency-key \u2026] [--json]   reply in the thread",
-  `  groundmail emails send [--from you@domain.com | --sender billing] --to user@example.com --subject "Hello" --html "<p>Hi</p>" [--category transactional|product|newsletter] [--unsubscribe] [--tenant <tenant>] [--watch [--timeout 60] [--json]]   --sender: a saved sender's handle; no --from or --sender: the sandbox sender (to your account email only)`,
-  '  groundmail emails send --to you@example.com --subject "Hello" --text "Hi" --watch   watch it land: the receiving server, its reply and the time',
-  "  groundmail emails batch --file ./emails.json [--tenant <tenant>]",
-  "  groundmail emails list [--limit 25] [--cursor \u2026] [--test | --live] [--tenant <tenant>] [--stream transactional|product|newsletter]",
-  "  groundmail emails insights [--window 7d|30d]",
-  "  groundmail emails get --id msg_\u2026 [--watch [--timeout 60] [--json]]   --watch: follow an email you already sent until it lands",
-  "  groundmail emails cancel --id msg_\u2026",
-  "  groundmail batches get <batch_id>   an emails batch's status counts (the batch_id `emails batch` returned)",
-  "  groundmail batches cancel <batch_id>   cancel the batch's emails that are still scheduled; safe to repeat",
-  "  groundmail emails resend --id msg_\u2026",
-  `  groundmail events send --name user.created --email user@example.com --data '{"name":"Ada"}'`,
-  "  groundmail automations list",
-  "  groundmail automations create --file ./welcome.json",
-  `  groundmail automations create --name Welcome --trigger user.created --steps '[{"type":"send_email","email":{"from":"you@yourdomain.com","to":"{{event.email}}","template":{"id":"welcome","variables":{"name":"{{event.data.name}}"}}}}]'   each email step sends a published template`,
-  "  groundmail automations create --file ./otp-sms.json",
-  "  groundmail automations get --id <automation-id>",
-  "  groundmail automations update --id <automation-id> --file ./welcome.json",
-  '  groundmail automations update --id <automation-id> --folder Onboarding   (--folder "" takes it out of any folder)',
-  "  groundmail automations activate --id <automation-id>",
-  "  groundmail automations pause --id <automation-id>",
-  "  groundmail automations delete --id <automation-id>",
-  "  groundmail webhooks list",
-  "  groundmail webhooks create --url https://yourapp.com/hooks [--tenants a,b] [--mailboxes mbx_a,mbx_b]   --tenants: only these tenants' email events; --mailboxes: only these mailboxes' events",
-  "  groundmail webhooks get --id wh_\u2026",
-  "  groundmail webhooks update --id wh_\u2026 [--url \u2026] [--event email.sent] [--enabled true|false] [--tenants a,b|all] [--mailboxes mbx_a,mbx_b|all]",
-  "  groundmail webhooks delete --id <webhook-id>",
-  "  groundmail webhooks deliveries list --webhook <webhook-id> [--status failed] [--event email.delivered] [--email-id msg_\u2026] [--q \u2026] [--test true|false] [--limit 25] [--cursor \u2026]",
-  "  groundmail webhooks deliveries get --webhook <webhook-id> --id <delivery-id>",
-  "  groundmail webhooks deliveries resend --webhook <webhook-id> --id <delivery-id>",
-  "  groundmail validate user@example.com   Groundmail validation: verdict, reasons, typo suggestion (exit 2 when invalid)",
-  "  groundmail burrowguard sites   the forms BurrowGuard protects",
-  '  groundmail burrowguard sites create --name "Sign-up form" --hostname app.example.com [--hostname localhost] [--block-free-webmail] [--allow-data-center-ips] [--email-checks-only] [--watch-only]   prints the secret once',
-  "  groundmail burrowguard sites update <id> --watch-only | --no-watch-only   show what would be blocked without blocking anyone, or start blocking",
-  "  groundmail burrowguard sites roll-secret <id> --yes   the old secret stops working at once",
-  "  groundmail burrowguard sites delete <id> --yes",
-  "  groundmail burrowguard checks [--site <id>] [--result passed|blocked|would_block|no_token] [--range 24h|7d|30d] [--limit 25]",
-  "  groundmail suppressions list [--tenant <tenant>]",
-  "  groundmail suppressions add --email user@example.com [--reason \u2026] [--tenant <tenant>]",
-  "  groundmail suppressions remove --id <id> | --email user@example.com [--tenant <tenant>]",
-  "  groundmail suppressions list --type category_opt_out [--category product|newsletter] [--tenant <tenant> | --include-tenants]   one-click category unsubscribes",
-  "  groundmail suppressions remove --type category_opt_out --email user@example.com [--category newsletter] [--tenant <tenant>]   re-subscribe to a category",
-  "  groundmail templates list [--status draft|published]",
-  "  groundmail templates starters",
-  "  groundmail templates from-starter password-reset",
-  '  groundmail templates create --name Welcome --subject "Hi" --html "<p>Hi</p>" [--category transactional|product] [--unsubscribe-enabled] [--folder Onboarding] [--sender billing]',
-  "  groundmail templates get --id tpl_\u2026",
-  "  groundmail templates update --id tpl_\u2026 [--name \u2026] [--subject \u2026] [--html \u2026] [--text \u2026] [--set-alias \u2026] [--category transactional|product] [--unsubscribe-enabled|--no-unsubscribe-enabled] [--folder \u2026] [--sender billing|none]",
-  "  groundmail templates publish --id tpl_\u2026",
-  `  groundmail templates push ./emails/welcome.tsx --alias welcome [--subject "Welcome"] [--props '{"name":"Ada"}'] [--publish]`,
-  "  groundmail templates versions --id tpl_\u2026",
-  "  groundmail templates restore --id tpl_\u2026 --version 2",
-  "  groundmail templates test-send --id tpl_\u2026 --to you@domain.com [--from you@domain.com | --sender billing]   neither: the template's sender, else your default sender",
-  '  groundmail templates duplicate --id tpl_\u2026 [--name "Copy"]',
-  "  groundmail templates delete --id tpl_\u2026   refused while an automation step sends it (the error names them)",
-  "  groundmail tenants list [--status active|paused] [--limit 25] [--cursor \u2026]   your customers, each with its own domains, suppressions and limits",
-  `  groundmail tenants create <external-id> [--name \u2026] [--default-from-domain \u2026] [--stream-policy all|transactional_only] [--daily-limit N] [--metadata '{"plan":"pro"}']`,
-  "  groundmail tenants get <tenant>",
-  "  groundmail tenants update <tenant> [--name \u2026] [--default-from-domain \u2026|none] [--stream-policy \u2026] [--daily-limit N|none] [--metadata JSON|null]",
-  "  groundmail tenants pause <tenant> [--reason \u2026]   stops the tenant's new sends",
-  "  groundmail tenants resume <tenant>",
-  "  groundmail tenants delete <tenant> --yes",
-  "  groundmail tenants stats <tenant> [--days 7]",
-  "  groundmail tenants domains list <tenant>",
-  "  groundmail tenants domains add <tenant> example.com   only this tenant can then send from it",
-  "  groundmail tenants domains remove <tenant> example.com   gives the domain back to the account",
-  "  groundmail brand get   your logo, colors and footer, which templates follow",
-  '  groundmail brand set [--logo-url <https url>|none] [--logo-align left|center] [--logo-width 120] [--color #2f6feb] [--company "Acme Inc"|none] [--address "\u2026"|none] [--website acme.com|none] [--settings-file brand.json]   --color: buttons, links and the line across the top',
-  "  groundmail senders list   the names and addresses your email goes out as",
-  '  groundmail senders create --name "Acme Billing" --address billing@mail.acme.com [--reply-to billing@acme.com] [--handle billing] [--default]   address on a verified domain',
-  "  groundmail senders get <id|handle>",
-  "  groundmail senders update <id|handle> [--name \u2026] [--address \u2026] [--reply-to \u2026|none] [--handle \u2026] [--default|--no-default]",
-  "  groundmail senders delete <id|handle> --yes   refused while an automation or template uses it",
-  "  groundmail keys list",
-  "  groundmail keys create [--name Default] [--scopes emails:send,domains:read] [--allowed-domains example.com] [--test] [--tenant <tenant>] [--mailboxes mbx_a,mbx_b]   --test: a gm_test_ key, sends are simulated; --tenant: a key limited to one tenant; --mailboxes: a key for one agent, limited to its mailboxes",
-  "  groundmail keys delete --id <api-key-id>",
-  "  groundmail migrate sendgrid [--dry-run] [--only templates,suppressions,domains,webhooks] [--region eu]   import from SendGrid (Beta)",
-  "  groundmail migrate postmark [--dry-run] [--only \u2026]   import from Postmark (Beta)",
-  "  groundmail migrate mailgun [--dry-run] [--only \u2026] [--region eu]   import from Mailgun (Beta)",
-  "  groundmail migrate resend [--dry-run] [--only \u2026]   import from Resend (Beta; a Full access key)",
-  "  groundmail migrate ses --region us-east-1 [--dry-run] [--only \u2026]   import one Amazon SES region (Beta)",
-  "  groundmail migrate list                          your recent imports",
-  "  groundmail migrate report <id> [--csv]           an import report (JSON, or CSV to stdout)",
-  "  groundmail integrations twilio status",
-  "  groundmail integrations twilio connect --account-sid AC\u2026 --auth-token \u2026 --from +15551234567",
-  "  groundmail integrations twilio disconnect"
-];
-var FOOTER_LINES = [
-  "Environment:",
-  "  GROUNDMAIL_API_KEY=gm_\u2026   optional (CI): wins over the `groundmail login` sign-in",
-  "  GROUNDMAIL_NO_KEYCHAIN=1  keep the refresh token in the config file (0600) instead of the OS keychain",
-  "  TWILIO_ACCOUNT_SID=AC\u2026 TWILIO_AUTH_TOKEN=\u2026 TWILIO_DEFAULT_FROM=+1\u2026  (integrations twilio connect)",
-  "  CLOUDFLARE_API_TOKEN=\u2026            (optional local apply; else uses dashboard Integrations)",
-  "  VERCEL_API_TOKEN=\u2026 VERCEL_TEAM_ID=\u2026  (optional local apply; else uses dashboard Integrations)",
-  "  GODADDY_PAT=\u2026  or GODADDY_API_KEY=\u2026 GODADDY_API_SECRET=\u2026  (domains apply --provider godaddy)",
-  "  SENDGRID_API_KEY / POSTMARK_SERVER_TOKEN (+ POSTMARK_ACCOUNT_TOKEN) / MAILGUN_API_KEY / RESEND_API_KEY  (migrate; used once, never stored)",
-  "  AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY (+ AWS_SESSION_TOKEN, AWS_REGION)  (migrate ses; used once, never stored)",
-  "",
-  "Scopes: full, emails:send, emails:read, domains:read, domains:write, webhooks:write, templates:write,",
-  "        suppressions:write, account:read, mailboxes:read, mailboxes:write, mailboxes:send",
-  "",
-  "<tenant>: the tenant's external id (your id for that customer) or its Groundmail id.",
-  "<mailbox>: the mailbox's mbx_ id, its address or your external id.",
-  "",
-  "--watch exit codes: 0 delivered, 1 error, 3 bounced or failed, 4 still on its way at --timeout, 5 test send (never delivered).",
-  "",
-  "Add --help to any command for just its usage. --version prints the CLI version."
-];
-var CLI_VERSION = version;
-var ALIASES = {
-  workspace: { "": "workspaces" },
-  domains: { create: "add", remove: "delete" },
-  events: { trigger: "send" },
-  automations: { add: "create", remove: "delete" },
-  suppressions: { create: "add", delete: "remove" },
-  templates: { add: "create", remove: "delete" },
-  tenants: { add: "create", remove: "delete" },
-  mailboxes: { add: "create", remove: "delete" },
-  senders: { add: "create", remove: "delete" },
-  brand: { update: "set" }
-};
-function words(line) {
-  return line.trim().split(/\s+/);
-}
-function fullUsage() {
-  return ["Usage:", ...USAGE_LINES, "", ...FOOTER_LINES].join("\n");
+// src/update-check.ts
+import { spawn as spawn2 } from "child_process";
+import { mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "fs";
+import { join as join2 } from "path";
+var UPDATE_COMMAND = "npm install -g groundmail-cli@latest";
+var REFRESH_COMMAND = "__refresh-update-check";
+var REGISTRY_URL = "https://registry.npmjs.org/groundmail-cli/latest";
+var CHECK_EVERY_MS = 24 * 60 * 60 * 1e3;
+var REGISTRY_TIMEOUT_MS = 3e3;
+function cachePath(env) {
+  return join2(configDir(env), "update-check.json");
+}
+function parts(version2) {
+  const match = /^(\d+)\.(\d+)\.(\d+)$/.exec(version2.trim());
+  return match ? match.slice(1).map(Number) : null;
+}
+function isNewerVersion(latest, current) {
+  const next = parts(latest);
+  const now = parts(current);
+  if (!next || !now) return false;
+  for (let index = 0; index < 3; index += 1) {
+    if (next[index] !== now[index]) return next[index] > now[index];
+  }
+  return false;
 }
-function usageFor(command, subcommand) {
-  if (!command) return fullUsage();
-  const name = ALIASES[command]?.[""] ?? command;
-  const forCommand = USAGE_LINES.filter((line) => words(line)[1] === name);
-  if (!forCommand.length) return null;
-  const sub = subcommand && !subcommand.startsWith("-") ? ALIASES[name]?.[subcommand] ?? subcommand : void 0;
-  const forSub = sub ? forCommand.filter((line) => words(line)[2] === sub) : [];
-  return ["Usage:", ...forSub.length ? forSub : forCommand].join("\n");
+function updateNotice(latest, current = CLI_VERSION) {
+  return `Update available: ${current} \u2192 ${latest}. Run: ${UPDATE_COMMAND}`;
 }
-function isHelpFlag(arg) {
-  return arg === "--help" || arg === "-h";
+function updateCheckEnabled(env, stderrIsTty) {
+  if (!stderrIsTty) return false;
+  return !env.CI && !env.GROUNDMAIL_NO_UPDATE_NOTIFIER && !env.NO_UPDATE_NOTIFIER;
 }
-function isVersionFlag(arg) {
-  return arg === "--version" || arg === "-v" || arg === "-V";
+function readUpdateCache(env) {
+  try {
+    const value = JSON.parse(readFileSync2(cachePath(env), "utf8"));
+    if (typeof value.checkedAt !== "number") return null;
+    return { checkedAt: value.checkedAt, latest: typeof value.latest === "string" ? value.latest : null };
+  } catch {
+    return null;
+  }
 }
-function resolveMetaRequest(argv) {
-  const [command, subcommand] = argv;
-  if (isVersionFlag(command) || command === "version") return { kind: "version", text: CLI_VERSION };
-  if (!command) return null;
-  if (isHelpFlag(command)) return { kind: "help", text: fullUsage() };
-  if (command === "help") {
-    return { kind: "help", text: usageFor(argv[1], argv[2]) ?? fullUsage() };
+async function refreshUpdateCache(env = process.env, fetchImpl = fetch, now = Date.now()) {
+  let latest = readUpdateCache(env)?.latest ?? null;
+  try {
+    const response = await fetchImpl(REGISTRY_URL, { signal: AbortSignal.timeout(REGISTRY_TIMEOUT_MS) });
+    if (response.ok) {
+      const body = await response.json();
+      if (typeof body.version === "string") latest = body.version;
+    }
+  } catch {
   }
-  if (argv.some(isHelpFlag)) {
-    const sub = isHelpFlag(subcommand) ? void 0 : subcommand;
-    return { kind: "help", text: usageFor(command, sub) ?? fullUsage() };
+  try {
+    mkdirSync2(configDir(env), { recursive: true });
+    writeFileSync2(cachePath(env), JSON.stringify({ checkedAt: now, latest }));
+  } catch {
+  }
+}
+function startUpdateCheck(env = process.env, now = Date.now()) {
+  try {
+    if (!updateCheckEnabled(env, Boolean(process.stderr.isTTY))) return;
+    const cache = readUpdateCache(env);
+    if (!cache || now - cache.checkedAt >= CHECK_EVERY_MS) {
+      const script = process.argv[1];
+      if (script) {
+        spawn2(process.execPath, [script, REFRESH_COMMAND], { detached: true, env, stdio: "ignore" }).unref();
+      }
+    }
+    const latest = cache?.latest;
+    if (latest && isNewerVersion(latest, CLI_VERSION)) {
+      process.once("exit", () => process.stderr.write(`
+${updateNotice(latest)}
+`));
+    }
+  } catch {
   }
-  return null;
 }
 
 // src/cli.ts
@@ -5490,11 +5592,17 @@ function printUsage() {
 }
 async function finish(result) {
   if (result.error) console.error(result.error);
+  if (result.exitCode && result.error?.startsWith("Usage:")) console.error(outdatedHint());
   process.exit(result.exitCode);
 }
 async function main() {
   const [, , command, subcommand] = process.argv;
   const args = process.argv.slice(3);
+  if (command === REFRESH_COMMAND) {
+    await refreshUpdateCache();
+    process.exit(0);
+  }
+  startUpdateCheck();
   const meta = resolveMetaRequest(process.argv.slice(2));
   if (meta) {
     console.log(meta.text);
@@ -5826,6 +5934,8 @@ async function main() {
     }
   }
   printUsage();
+  if (command) console.error(`
+${unknownCommandMessage(process.argv.slice(2))}`);
   process.exit(1);
 }
 main().catch((error) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "groundmail-cli",
-  "version": "0.43.0",
+  "version": "0.44.0",
   "description": "Groundmail CLI — send transactional email from the terminal",
   "license": "MIT",
   "type": "module",