resend-cli 1.0.3 → 1.2.0

package/bun.lock

@@ -0,0 +1,76 @@
+{
+  "lockfileVersion": 1,
+  "configVersion": 0,
+  "workspaces": {
+    "": {
+      "name": "resend-cli",
+      "dependencies": {
+        "@clack/prompts": "1.1.0",
+        "@commander-js/extra-typings": "14.0.0",
+        "commander": "14.0.3",
+        "resend": "6.9.3",
+        "unicode-animations": "1.0.3",
+      },
+      "devDependencies": {
+        "@biomejs/biome": "2.4.6",
+        "@types/bun": "1.3.10",
+        "typescript": "5.9.3",
+      },
+    },
+  },
+  "packages": {
+    "@biomejs/biome": ["@biomejs/biome@2.4.6", "", { "optionalDependencies": { "@biomejs/cli-darwin-arm64": "2.4.6", "@biomejs/cli-darwin-x64": "2.4.6", "@biomejs/cli-linux-arm64": "2.4.6", "@biomejs/cli-linux-arm64-musl": "2.4.6", "@biomejs/cli-linux-x64": "2.4.6", "@biomejs/cli-linux-x64-musl": "2.4.6", "@biomejs/cli-win32-arm64": "2.4.6", "@biomejs/cli-win32-x64": "2.4.6" }, "bin": { "biome": "bin/biome" } }, "sha512-QnHe81PMslpy3mnpL8DnO2M4S4ZnYPkjlGCLWBZT/3R9M6b5daArWMMtEfP52/n174RKnwRIf3oT8+wc9ihSfQ=="],
+
+    "@biomejs/cli-darwin-arm64": ["@biomejs/cli-darwin-arm64@2.4.6", "", { "os": "darwin", "cpu": "arm64" }, "sha512-NW18GSyxr+8sJIqgoGwVp5Zqm4SALH4b4gftIA0n62PTuBs6G2tHlwNAOj0Vq0KKSs7Sf88VjjmHh0O36EnzrQ=="],
+
+    "@biomejs/cli-darwin-x64": ["@biomejs/cli-darwin-x64@2.4.6", "", { "os": "darwin", "cpu": "x64" }, "sha512-4uiE/9tuI7cnjtY9b07RgS7gGyYOAfIAGeVJWEfeCnAarOAS7qVmuRyX6d7JTKw28/mt+rUzMasYeZ+0R/U1Mw=="],
+
+    "@biomejs/cli-linux-arm64": ["@biomejs/cli-linux-arm64@2.4.6", "", { "os": "linux", "cpu": "arm64" }, "sha512-kMLaI7OF5GN1Q8Doymjro1P8rVEoy7BKQALNz6fiR8IC1WKduoNyteBtJlHT7ASIL0Cx2jR6VUOBIbcB1B8pew=="],
+
+    "@biomejs/cli-linux-arm64-musl": ["@biomejs/cli-linux-arm64-musl@2.4.6", "", { "os": "linux", "cpu": "arm64" }, "sha512-F/JdB7eN22txiTqHM5KhIVt0jVkzZwVYrdTR1O3Y4auBOQcXxHK4dxULf4z43QyZI5tsnQJrRBHZy7wwtL+B3A=="],
+
+    "@biomejs/cli-linux-x64": ["@biomejs/cli-linux-x64@2.4.6", "", { "os": "linux", "cpu": "x64" }, "sha512-oHXmUFEoH8Lql1xfc3QkFLiC1hGR7qedv5eKNlC185or+o4/4HiaU7vYODAH3peRCfsuLr1g6v2fK9dFFOYdyw=="],
+
+    "@biomejs/cli-linux-x64-musl": ["@biomejs/cli-linux-x64-musl@2.4.6", "", { "os": "linux", "cpu": "x64" }, "sha512-C9s98IPDu7DYarjlZNuzJKTjVHN03RUnmHV5htvqsx6vEUXCDSJ59DNwjKVD5XYoSS4N+BYhq3RTBAL8X6svEg=="],
+
+    "@biomejs/cli-win32-arm64": ["@biomejs/cli-win32-arm64@2.4.6", "", { "os": "win32", "cpu": "arm64" }, "sha512-xzThn87Pf3YrOGTEODFGONmqXpTwUNxovQb72iaUOdcw8sBSY3+3WD8Hm9IhMYLnPi0n32s3L3NWU6+eSjfqFg=="],
+
+    "@biomejs/cli-win32-x64": ["@biomejs/cli-win32-x64@2.4.6", "", { "os": "win32", "cpu": "x64" }, "sha512-7++XhnsPlr1HDbor5amovPjOH6vsrFOCdp93iKXhFn6bcMUI6soodj3WWKfgEO6JosKU1W5n3uky3WW9RlRjTg=="],
+
+    "@clack/core": ["@clack/core@1.1.0", "", { "dependencies": { "sisteransi": "^1.0.5" } }, "sha512-SVcm4Dqm2ukn64/8Gub2wnlA5nS2iWJyCkdNHcvNHPIeBTGojpdJ+9cZKwLfmqy7irD4N5qLteSilJlE0WLAtA=="],
+
+    "@clack/prompts": ["@clack/prompts@1.1.0", "", { "dependencies": { "@clack/core": "1.1.0", "sisteransi": "^1.0.5" } }, "sha512-pkqbPGtohJAvm4Dphs2M8xE29ggupihHdy1x84HNojZuMtFsHiUlRvqD24tM2+XmI+61LlfNceM3Wr7U5QES5g=="],
+
+    "@commander-js/extra-typings": ["@commander-js/extra-typings@14.0.0", "", { "peerDependencies": { "commander": "~14.0.0" } }, "sha512-hIn0ncNaJRLkZrxBIp5AsW/eXEHNKYQBh0aPdoUqNgD+Io3NIykQqpKFyKcuasZhicGaEZJX/JBSIkZ4e5x8Dg=="],
+
+    "@stablelib/base64": ["@stablelib/base64@1.0.1", "", {}, "sha512-1bnPQqSxSuc3Ii6MhBysoWCg58j97aUjuCSZrGSmDxNqtytIi0k8utUenAwTZN4V5mXXYGsVUI9zeBqy+jBOSQ=="],
+
+    "@types/bun": ["@types/bun@1.3.10", "", { "dependencies": { "bun-types": "1.3.10" } }, "sha512-0+rlrUrOrTSskibryHbvQkDOWRJwJZqZlxrUs1u4oOoTln8+WIXBPmAuCF35SWB2z4Zl3E84Nl/D0P7803nigQ=="],
+
+    "@types/node": ["@types/node@25.2.3", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-m0jEgYlYz+mDJZ2+F4v8D1AyQb+QzsNqRuI7xg1VQX/KlKS0qT9r1Mo16yo5F/MtifXFgaofIFsdFMox2SxIbQ=="],
+
+    "bun-types": ["bun-types@1.3.10", "", { "dependencies": { "@types/node": "*" } }, "sha512-tcpfCCl6XWo6nCVnpcVrxQ+9AYN1iqMIzgrSKYMB/fjLtV2eyAVEg7AxQJuCq/26R6HpKWykQXuSOq/21RYcbg=="],
+
+    "commander": ["commander@14.0.3", "", {}, "sha512-H+y0Jo/T1RZ9qPP4Eh1pkcQcLRglraJaSLoyOtHxu6AapkjWVCy2Sit1QQ4x3Dng8qDlSsZEet7g5Pq06MvTgw=="],
+
+    "fast-sha256": ["fast-sha256@1.3.0", "", {}, "sha512-n11RGP/lrWEFI/bWdygLxhI+pVeo1ZYIVwvvPkW7azl/rOy+F3HYRZ2K5zeE9mmkhQppyv9sQFx0JM9UabnpPQ=="],
+
+    "postal-mime": ["postal-mime@2.7.3", "", {}, "sha512-MjhXadAJaWgYzevi46+3kLak8y6gbg0ku14O1gO/LNOuay8dO+1PtcSGvAdgDR0DoIsSaiIA8y/Ddw6MnrO0Tw=="],
+
+    "resend": ["resend@6.9.3", "", { "dependencies": { "postal-mime": "2.7.3", "svix": "1.84.1" }, "peerDependencies": { "@react-email/render": "*" }, "optionalPeers": ["@react-email/render"] }, "sha512-GRXjH9XZBJA+daH7bBVDuTShr22iWCxXA8P7t495G4dM/RC+d+3gHBK/6bz9K6Vpcq11zRQKmD+B+jECwQlyGQ=="],
+
+    "sisteransi": ["sisteransi@1.0.5", "", {}, "sha512-bLGGlR1QxBcynn2d5YmDX4MGjlZvy2MRBDRNHLJ8VI6l6+9FUiyTFNJ0IveOSP0bcXgVDPRcfGqA0pjaqUpfVg=="],
+
+    "standardwebhooks": ["standardwebhooks@1.0.0", "", { "dependencies": { "@stablelib/base64": "^1.0.0", "fast-sha256": "^1.3.0" } }, "sha512-BbHGOQK9olHPMvQNHWul6MYlrRTAOKn03rOe4A8O3CLWhNf4YHBqq2HJKKC+sfqpxiBY52pNeesD6jIiLDz8jg=="],
+
+    "svix": ["svix@1.84.1", "", { "dependencies": { "standardwebhooks": "1.0.0", "uuid": "^10.0.0" } }, "sha512-K8DPPSZaW/XqXiz1kEyzSHYgmGLnhB43nQCMeKjWGCUpLIpAMMM8kx3rVVOSm6Bo6EHyK1RQLPT4R06skM/MlQ=="],
+
+    "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
+
+    "undici-types": ["undici-types@7.16.0", "", {}, "sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw=="],
+
+    "unicode-animations": ["unicode-animations@1.0.3", "", { "dependencies": { "unicode-animations": "^1.0.1" }, "bin": { "unicode-animations": "scripts/demo.cjs" } }, "sha512-+klB2oWwcYZjYWhwP4Pr8UZffWDFVx6jKeIahE6z0QYyM2dwDeDPyn5nevCYbyotxvtT9lh21cVURO1RX0+YMg=="],
+
+    "uuid": ["uuid@10.0.0", "", { "bin": { "uuid": "dist/bin/uuid" } }, "sha512-8XkAphELsDnEGrDxUOHB3RGvXz6TeuYSGEZBOjtTtPm2lwhGBjLgOzLHB63IUWfBpNucQjND6d3AOudO+H3RWQ=="],
+  }
+}

package/bunfig.toml

@@ -0,0 +1,2 @@
+[install]
+peer = false

package/docs/agent-dx-gaps.md

@@ -0,0 +1,167 @@
+# Agent DX Gap Analysis
+
+Gap analysis of the Resend CLI against the 7 dimensions from
+["You Need to Rewrite Your CLI for AI Agents"](https://justinpoehnelt.com/rewrite-your-cli-for-agents/)
+by Justin Poehnelt (Google).
+
+---
+
+## 1. Structured Output
+
+> Agents need machine-readable output — JSON by default when piped.
+
+### Strengths
+
+- **Auto-JSON when piped.** `shouldOutputJson()` returns `true` when `!process.stdout.isTTY` (`src/lib/output.ts:14`). Every command goes through `outputResult` / `outputError`, so piped output is always JSON with zero flags required.
+- **Consistent error envelope.** `outputError` emits `{"error":{"message":"…","code":"…"}}` with exit code 1 (`src/lib/output.ts:35-54`).
+- **Help text documents the JSON shape.** `buildHelpText` includes an `output` section and `errorCodes` list (`src/lib/help-text.ts:1-34`).
+
+### Gaps
+
+| Gap | Details | Recommendation |
+|-----|---------|----------------|
+| No `--output` format flag | Only `--json` exists. No `--output=yaml`, `--output=csv`, or `--output=table`. | Low priority — JSON is sufficient for agents. Consider adding `--output` only if human table formatting is needed. |
+| No JSON-Lines streaming | List endpoints return a single JSON blob. For large result sets an agent can't stream-process rows. | Add optional `--jsonl` or newline-delimited mode to `runList`. |
+
+---
+
+## 2. Deterministic, Non-Interactive Behavior
+
+> When piped, CLIs must never prompt — they should fail fast with an actionable error.
+
+### Strengths
+
+- **TTY detection is solid.** `isInteractive()` checks `stdin.isTTY`, `stdout.isTTY`, `CI`, `GITHUB_ACTIONS`, and `TERM=dumb` (`src/lib/tty.ts:1-15`).
+- **Missing flags → structured error.** `promptForMissing` exits with `missing_flags` code and lists which flags are needed (`src/lib/prompts.ts:55-61`).
+- **Delete confirmation → structured error.** `confirmDelete` exits with `confirmation_required` and tells the agent to pass `--yes` (`src/lib/prompts.ts:28-36`).
+- **Spinner is a no-op.** `createSpinner` returns stub methods in non-interactive mode (`src/lib/spinner.ts:48-55`).
+
+### Gaps
+
+| Gap | Details | Recommendation |
+|-----|---------|----------------|
+| `setup` command has no non-interactive default | Bare `resend setup` errors with `missing_target` when piped — the agent must already know the valid targets (`src/commands/setup/index.ts:70-79`). | Consider an `--all` flag or `resend setup --target cursor,vscode` to let agents configure multiple targets in one call. |
+| `skills install` shells out to `npx skills` in TTY | Interactive path delegates to an external process (`src/commands/skills/install.ts:231-246`). If TTY detection is wrong, the agent gets an interactive subprocess. | The non-interactive path already exists and works — just ensure the interactive branch can never trigger when `--json` is passed (currently it can't, but worth a guard). |
+
+---
+
+## 3. Meaningful Exit Codes
+
+> Agents rely on exit codes to branch logic. 0 = success, non-zero = specific failure category.
+
+### Strengths
+
+- **Errors exit 1.** `outputError` defaults to exit code 1 (`src/lib/output.ts:39`).
+- **Error codes in JSON.** The `code` field (`missing_flags`, `auth_error`, `fetch_error`, etc.) lets agents distinguish failure types without parsing messages.
+
+### Gaps
+
+| Gap | Details | Recommendation |
+|-----|---------|----------------|
+| Single exit code for all errors | Everything exits 1. Auth failures, validation errors, network errors, and 404s are indistinguishable by exit code alone. | Define a small set of exit codes: `1` = general, `2` = usage/validation, `3` = auth, `4` = network/API, `78` = config. Map `outputError` codes to exit codes. |
+| `process.exit(0)` on cancel | `cancelAndExit` exits 0 (`src/lib/prompts.ts:14-17`). A cancelled operation should exit non-zero so agents don't interpret it as success. | Exit 130 (standard SIGINT convention) or a dedicated code on cancellation. |
+
+---
+
+## 4. Stderr vs Stdout Separation
+
+> Machines read stdout. Humans read stderr. Progress, spinners, and status go to stderr.
+
+### Strengths
+
+- **Spinners write to stderr.** All spinner output uses `process.stderr.write` (`src/lib/spinner.ts:62-80`).
+- **Error JSON goes to stderr.** `outputError` uses `console.error` for JSON errors (`src/lib/output.ts:42`).
+
+### Gaps
+
+| Gap | Details | Recommendation |
+|-----|---------|----------------|
+| Interactive success messages go to stdout | `console.log(config.successMsg)` in `runDelete`, `runWrite`, and setup commands writes human text to stdout (`src/lib/actions.ts:67,124`). If an agent accidentally gets the interactive branch, it mixes human text with machine output. | Route all non-JSON human messages through `console.error` (stderr) so stdout is always machine-parseable. |
+| `skills install` interactive output on stdout | `console.log('  ✔ ...')` in `installSkills` goes to stdout (`src/commands/skills/install.ts:173-178`). | Move to stderr. |
+
+---
+
+## 5. Discoverability & Self-Documentation
+
+> Agents need to understand what a CLI can do from the CLI itself — not from docs websites.
+
+### Strengths
+
+- **Rich help text.** `buildHelpText` adds output shape, error codes, and examples to every command (`src/lib/help-text.ts`).
+- **Examples are runnable.** Help text examples use real `$ resend ...` invocations.
+- **MCP setup exists.** `resend setup` configures the CLI as an MCP server for 5 agents (`src/commands/setup/index.ts`).
+
+### Gaps
+
+| Gap | Details | Recommendation |
+|-----|---------|----------------|
+| No machine-readable command tree | `--help` outputs human-formatted text. There's no `resend --help --json` or `resend commands --json` that returns a structured list of all commands, flags, and types. | Add a hidden `resend commands` (or `--help --json`) that outputs the full command tree as JSON — subcommands, flags, types, defaults, required/optional. This is the single highest-impact improvement for agent discoverability. |
+| No schema per command | Agents guess at flag types and constraints. | Emit JSON Schema for each command's input (flags + args) and output shape. Could be auto-generated from Commander metadata. |
+| No version/capability negotiation | No `resend capabilities` or feature flags. An agent can't check if a subcommand exists without running it. | Add `resend capabilities --json` returning supported commands and API version. |
+
+---
+
+## 6. Auth & Configuration
+
+> Agents need non-interactive auth: env vars, config files, or flags — never browser OAuth flows.
+
+### Strengths
+
+- **Three-tier key resolution.** `resolveApiKey` checks `--api-key` flag → `RESEND_API_KEY` env → `~/.config/resend/credentials.json` (`src/lib/config.ts:24-45`). All three work without interaction.
+- **Config file is secure.** Written with `0o600` permissions (`src/lib/config.ts:52-59`).
+- **XDG-compliant.** Respects `XDG_CONFIG_HOME` and `APPDATA` (`src/lib/config.ts:14-22`).
+
+### Gaps
+
+| Gap | Details | Recommendation |
+|-----|---------|----------------|
+| No auth status command | There's no way to verify auth works without making an API call. | Add `resend auth status --json` → `{"authenticated":true,"source":"env","key_prefix":"re_..."}`. Useful for agents to pre-flight check credentials. |
+| No key scoping info | The CLI doesn't surface whether the key is a full-access or sending-only key. | Return key metadata (permissions, team) from a status endpoint if the API supports it. |
+| `resend login` is interactive-only | If `resend login` exists and requires TTY input, agents can't use it. | Ensure `resend login --api-key <key>` works non-interactively (just stores the key). |
+
+---
+
+## 7. Idempotency & Safety
+
+> Agent retries are inevitable. Commands should be safe to re-run.
+
+### Strengths
+
+- **Setup commands are idempotent.** `mergeJsonConfig` reads existing config and merges — running twice produces the same result (`src/commands/setup/utils.ts:14-33`). Help text documents this.
+- **Skills install is idempotent.** Files are overwritten with the same content.
+- **Delete requires `--yes`.** Prevents accidental destructive actions in non-interactive mode (`src/lib/prompts.ts:28-36`).
+
+### Gaps
+
+| Gap | Details | Recommendation |
+|-----|---------|----------------|
+| No idempotency keys for create operations | `resend emails send` or `resend domains create` with the same args may create duplicates. | Support `--idempotency-key <key>` passed through to the API's `Idempotency-Key` header. Critical for agent retry loops. |
+| No dry-run mode | No `--dry-run` flag to preview what a command would do. | Add `--dry-run` that validates inputs, resolves auth, and returns the request that *would* be made — without executing it. |
+| File reads have no path validation | `readFile` in `src/lib/files.ts` reads any path the process can access. An agent could be tricked into reading sensitive files. | Validate paths against an allowlist or working-directory scope. Low priority if the CLI is always invoked by a trusted agent. |
+
+---
+
+## Implementation Priority
+
+Ordered by impact on agent usability:
+
+| # | Item | Dimension | Effort |
+|---|------|-----------|--------|
+| 1 | `resend commands --json` — machine-readable command tree | Discoverability | Medium |
+| 2 | Differentiated exit codes (2/3/4 by error category) | Exit Codes | Small |
+| 3 | Route all human messages to stderr | Stderr/Stdout | Small |
+| 4 | `resend auth status --json` | Auth | Small |
+| 5 | `--idempotency-key` flag for create/send commands | Idempotency | Small |
+| 6 | `--dry-run` flag | Idempotency | Medium |
+| 7 | JSON Schema per command (input + output) | Discoverability | Large |
+| 8 | `resend capabilities --json` | Discoverability | Medium |
+| 9 | Cancel exits non-zero (130) | Exit Codes | Tiny |
+| 10 | `--jsonl` streaming for list commands | Structured Output | Medium |
+
+---
+
+## Summary
+
+The Resend CLI already handles the two most common agent pitfalls well: **structured output is automatic when piped**, and **interactive prompts fail fast with actionable errors**. The spinner, auth, and setup systems are agent-friendly out of the box.
+
+The biggest gaps are in **discoverability** (no way for an agent to introspect available commands as JSON) and **exit code granularity** (everything is exit 1). Fixing items 1-4 above would cover ~80% of the agent DX surface with relatively small changes.

package/docs/missing-commands.md

@@ -0,0 +1,58 @@
+# Missing CLI Commands
+
+Commands supported by the SDK (`resend` npm package) that have no CLI equivalent yet.
+
+Source comparison: `resend-node/src/` resource classes vs `resend-cli/src/commands/`.
+
+## Templates (7 commands)
+
+The entire `templates` namespace is missing from the CLI.
+
+| Command | SDK method | Notes |
+|---|---|---|
+| `resend templates create` | `templates.create(payload)` | `--name`, `--subject`, `--html`, `--text` |
+| `resend templates list` | `templates.list(opts)` | Pagination support |
+| `resend templates get <id>` | `templates.get(id)` | Also supports alias lookup |
+| `resend templates update <id>` | `templates.update(id, payload)` | `--name`, `--subject`, `--html`, `--text` |
+| `resend templates delete <id>` | `templates.remove(id)` | Confirmation prompt |
+| `resend templates duplicate <id>` | `templates.duplicate(id)` | |
+| `resend templates publish <id>` | `templates.publish(id)` | |
+
+## Sent Emails (4 commands)
+
+The `emails` namespace only has `send` and `batch`. These read/manage operations are missing:
+
+| Command | SDK method | Notes |
+|---|---|---|
+| `resend emails list` | `emails.list(opts)` | Pagination support |
+| `resend emails get <id>` | `emails.get(id)` | Retrieve a sent email by ID |
+| `resend emails update <id>` | `emails.update(payload)` | Reschedule a scheduled email (`--scheduled-at`) |
+| `resend emails cancel <id>` | `emails.cancel(id)` | Cancel a scheduled email |
+
+## Not planned
+
+These SDK methods don't map cleanly to CLI commands:
+
+| SDK method | Reason |
+|---|---|
+| `emails.receiving.forward(opts)` | Convenience wrapper that calls `emails.send` internally, not a distinct API endpoint |
+| `webhooks.verify(payload)` | Signature verification utility using Svix. Used in server-side webhook handlers, not useful as a CLI command |
+
+## Coverage summary
+
+| Namespace | SDK methods | CLI commands | Coverage |
+|---|---|---|---|
+| emails (send/batch) | 6 | 2 | 33% |
+| emails.receiving | 5 | 4 | 80% |
+| domains | 6 | 6 | 100% |
+| api-keys | 3 | 3 | 100% |
+| contacts | 5 | 5 | 100% |
+| contacts.segments | 3 | 3 | 100% |
+| contacts.topics | 2 | 2 | 100% |
+| broadcasts | 6 | 6 | 100% |
+| contact-properties | 5 | 5 | 100% |
+| segments | 4 | 4 | 100% |
+| topics | 5 | 5 | 100% |
+| templates | 7 | 0 | 0% |
+| webhooks | 5 | 5 | 100% |
+| **Total** | **62** | **51** | **82%** |

package/docs/production-readiness.md

@@ -0,0 +1,99 @@
+# Production Readiness Gaps
+
+Tracked gaps identified during full CLI review. Items are ordered by severity.
+
+---
+
+## Blockers
+
+### `removeApiKey()` crashes when no credentials file exists
+
+`src/lib/config.ts` — `unlinkSync()` called without try-catch. Running `resend auth logout` when not logged in throws an unhandled exception instead of a graceful error.
+
+### `emails send` missing attachment support
+
+The Resend API supports `attachments` on send but the CLI does not expose an `--attach <path>` flag. This is a core email feature users will expect before adopting the CLI.
+
+### `emails send` missing `--scheduled-at`
+
+The API supports scheduled sending and broadcasts already expose `--scheduled-at`, but single email send does not.
+
+### Distribution: Homebrew tap and additional package managers
+
+The release pipeline builds binaries and publishes GitHub Releases, but there is no official Homebrew tap under the `resend` org. The previous reference to a personal tap (`rafa-thayto/homebrew-tap`) was removed. Before launch, set up:
+
+- **Homebrew** — Create `resend/homebrew-tap` with a formula that downloads the correct binary from GitHub Releases. Wire the release workflow to auto-update the formula on new tags.
+- **npm** — The package defines a `bin` entry but is not currently published to npm. `npm install -g @resend/cli` would be the expected install path for Node.js users.
+- **AUR / Scoop / winget** — Consider community packages for Linux and Windows users who don't use the shell installer.
+
+---
+
+## High Priority
+
+### No shell completions
+
+No bash, zsh, or fish completion support exists. With 50+ commands and deeply nested subcommands, tab completion is essential for discoverability and usability.
+
+### Inconsistent pagination on list commands
+
+`api-keys list` and `topics list` lack the `--limit`, `--after`, and `--before` options that every other list command provides. This creates an inconsistent scripting surface.
+
+**Files:** `src/commands/api-keys/list.ts`, `src/commands/topics/list.ts`
+
+### No tests for `actions.ts` and `pagination.ts`
+
+These are core shared modules (reusable action builders and pagination logic) used by nearly every command, yet they have zero test coverage.
+
+**Files:** `src/lib/actions.ts`, `src/lib/pagination.ts`
+
+### Batch >100 emails warns but does not error in non-interactive mode
+
+`src/commands/emails/batch.ts` uses `console.warn()` when the batch exceeds 100 emails but continues execution. In CI or scripted mode this should hard-error since the API will reject the request.
+
+---
+
+## Medium Priority
+
+### No output format options beyond JSON and table
+
+List commands support `--json` or interactive tables only. Missing `--format csv` and `--format tsv` for data export workflows.
+
+### No filter or search on list commands
+
+No ability to filter results server-side (e.g. `--status verified` on domains, `--segment-id` on contacts). Users must fetch all pages and filter locally.
+
+### No `resend update` or auto-update mechanism
+
+Version check exists in `resend doctor` but there is no way to update the CLI from within it. Users must re-run the install script manually.
+
+### `setup --uninstall` and `setup --dry-run` missing
+
+The setup command can configure AI agent integrations but cannot undo or preview changes before applying them.
+
+### No CLI-level retry logic for transient failures
+
+The CLI relies entirely on the SDK's internal retries which are opaque. For batch and bulk operations, CLI-level retry with exponential backoff would be more robust and give users visibility into retries.
+
+---
+
+## Low Priority
+
+### Table rendering does not truncate long values
+
+Very long emails, domain names, or property values can break table alignment in narrow terminals.
+
+### No `--silent` or `--quiet` flag
+
+No way to suppress all non-essential output (spinners, hints, pagination messages) for scripting use cases.
+
+### Contact email-vs-ID detection is fragile
+
+`src/commands/contacts/utils.ts` uses `includes('@')` to decide whether a string is an email address or a contact ID. Edge cases could cause misidentification.
+
+### No client-side input validation for domains and emails
+
+Domain names and email addresses are accepted as-is and forwarded to the API. Client-side validation would provide faster, clearer error messages.
+
+### Hardcoded API URLs prevent staging usage
+
+No `--base-url` flag or `RESEND_BASE_URL` environment variable for pointing the CLI at non-production environments.

package/docs/secure-key-storage.md

@@ -0,0 +1,174 @@
+# Secure API Key Storage via macOS Keychain
+
+## Context
+
+API keys are currently stored as **plain text** in `~/.config/resend/credentials.json` (with `0o600` file permissions). The CLI already supports **multi-team profiles** — the credentials file has this structure:
+
+```json
+{ "active_team": "production", "teams": { "production": { "api_key": "re_..." }, "staging": { "api_key": "re_..." } } }
+```
+
+The keychain integration must preserve this multi-team model: each team's API key gets its own keychain entry, and team metadata (active team, team list) stays in the config file.
+
+**Goal:** Move API key secrets into macOS Keychain while keeping team management metadata in the config file.
+
+## Approach: Shell out to `/usr/bin/security`
+
+Use macOS's built-in `security` CLI to interact with Keychain. Zero dependencies, works with Bun compiled binaries.
+
+Each team gets its own keychain entry using the team name as the `account` field:
+- `security add-generic-password -s resend-cli -a <team> -w <key> -U` (store/update)
+- `security find-generic-password -s resend-cli -a <team> -w` (retrieve)
+- `security delete-generic-password -s resend-cli -a <team>` (delete)
+
+**Why not keytar (the prototype's approach):**
+`bun build --compile` produces a self-contained binary with embedded JS bytecode. Native N-API addons (`.node` files) cannot be embedded — they require OS-level dynamic library loading at runtime. The release workflow (`.github/workflows/release.yml`) cross-compiles to 5 platform targets from a single Ubuntu runner, which further rules out native modules needing per-platform node-gyp compilation. The prototype uses keytar because it's a standard Node.js/oclif package where native modules compile during `npm install`.
+
+**Why not other approaches:**
+- **Bun FFI**: Hundreds of lines of C-interop for CoreFoundation/Security.framework — not worth it
+- **Pure-JS wrappers**: Most just shell out to `security` internally anyway
+
+## Key resolution priority (updated)
+
+1. `--api-key` flag → source: `'flag'`
+2. `RESEND_API_KEY` env var → source: `'env'`
+3. **macOS Keychain** (for resolved team name) → source: `'keychain'` *(new)*
+4. `credentials.json` teams → source: `'config'` *(kept as fallback)*
+
+Team resolution is unchanged: `--team` flag > `RESEND_TEAM` env > `active_team` in config > `"default"`
+
+## Storage model
+
+**Keychain** stores secrets only:
+- Service: `resend-cli`, Account: `<team-name>`, Password: `<api-key>`
+- One entry per team
+
+**Config file** (`credentials.json`) stores non-secret metadata:
+- `active_team`: which team is currently active
+- `teams`: record of team names (but **no more `api_key` fields** when keychain is available)
+
+When keychain is available, the config file looks like:
+```json
+{ "active_team": "production", "teams": { "production": {}, "staging": {} } }
+```
+
+When keychain is unavailable (fallback), `api_key` is stored in the teams record as before.
+
+## Migration strategy
+
+No automatic migration. Both backends coexist:
+- New `resend login` writes key to keychain + team metadata to config (no `api_key` in config)
+- Old config files with `api_key` fields still work at lower priority
+- `resend logout` / `resend teams remove` clean up both keychain entry and config
+- Users naturally migrate when they next run `resend login`
+
+## Files to change
+
+### New: `src/lib/keychain.ts` (~60 lines)
+
+Keychain abstraction wrapping `/usr/bin/security` via `child_process.execFile` (arg array, no shell — safe from injection).
+
+```
+keychainStore(team: string, apiKey: string): Promise<void>
+keychainGet(team: string): Promise<string | null>       // null on not-found (exit code 44)
+keychainDelete(team: string): Promise<boolean>
+keychainAvailable(): boolean                             // process.platform === 'darwin' && existsSync('/usr/bin/security')
+```
+
+Constants: `SERVICE = 'resend-cli'`
+
+### Modify: `src/lib/config.ts`
+
+Current functions and how they change:
+
+- `ApiKeySource` type: add `'keychain'`
+- `TeamProfile` type: make `api_key` optional (`{ api_key?: string }`) — empty when key is in keychain
+- `resolveApiKey(flagValue?, teamName?)` → **async**: after env check, try `keychainGet(team)` before falling back to config file's `api_key`
+- `storeApiKey(apiKey, teamName?)` → **async**: if `keychainAvailable()`, store key in keychain and write team to config without `api_key`; otherwise write `api_key` to config as fallback
+- `removeApiKey(teamName?)` → **async**: delete from keychain + remove team from config
+- `removeTeam(teamName)` → **async**: delete from keychain + existing config cleanup
+- `resolveTeamName`, `readCredentials`, `writeCredentials`, `setActiveTeam`, `listTeams`: unchanged (they don't touch API keys directly)
+
+### Modify: `src/lib/client.ts`
+
+- `createClient` and `requireClient` → **async** (add `await` to `resolveApiKey`)
+
+### Modify: `src/commands/auth/login.ts`
+
+- `await storeApiKey(apiKey, teamName)` (line 151)
+- Update success message: "API key stored in macOS Keychain" vs "API key stored at {path}"
+- `await resolveApiKey()` (line 71)
+
+### Modify: `src/commands/auth/logout.ts`
+
+- Check keychain + config to determine if logged in (not just file existence)
+- `await removeApiKey()`
+- Update confirmation message for keychain
+
+### Modify: `src/commands/teams/remove.ts`
+
+- `await removeTeam(name)` — needs to delete keychain entry too
+
+### Modify: `src/commands/doctor.ts`
+
+- `checkApiKeyPresence` → **async**: `await resolveApiKey()`
+- `checkApiValidationAndDomains` → `await resolveApiKey()`
+- Show `(source: keychain)` when applicable
+- When source is `'config'`, hint: "run `resend login` to migrate to Keychain"
+
+### Modify: `src/commands/setup/utils.ts` and `src/commands/setup/claude-code.ts`
+
+- Add `await` to `resolveApiKey()` calls
+
+### Update help text in: `src/cli.ts`, `login.ts`, `logout.ts`
+
+- Reflect new priority chain mentioning Keychain
+
+### New: `tests/lib/keychain.test.ts`
+
+- Mock `execFile` to test store/get/delete without touching real keychain
+- Test per-team accounts work correctly
+- Test `keychainGet` returns `null` on exit code 44
+- Test `keychainAvailable` returns `false` on non-darwin
+
+### Update: existing tests
+
+- Mock keychain module in config/auth tests
+
+## File-based fallback hardening
+
+When keychain is unavailable (headless Linux, CI, containers), the file-based backend is used with hardening:
+
+1. **Warn on fallback**: When `storeApiKey` writes to file instead of keychain, print:
+   `"⚠ No system keychain available. API key stored in plain text at {path}. Consider using RESEND_API_KEY env var instead."`
+
+2. **Permission check on read**: When `resolveApiKey` reads from the config file, verify permissions are still `0o600`. If loosened, warn:
+   `"⚠ Credentials file {path} has loose permissions. Run: chmod 600 {path}"`
+
+3. **Doctor check**: Show storage backend and warn if using file-based storage on a platform that supports keychain.
+
+**Industry context**: Plain text storage is common (AWS CLI, Stripe CLI, Heroku) but increasingly criticized. GitHub CLI now supports keychain (becoming default). Google Cloud uses encrypted SQLite. The trend is toward OS-level secure storage. The file fallback exists for environments where no keychain daemon is available.
+
+## Future: Linux & Windows support
+
+The `keychain.ts` module abstracts the backend per platform:
+
+| Platform | System | CLI tool |
+|----------|--------|----------|
+| **macOS** | Keychain Access | `/usr/bin/security` |
+| **Linux** | libsecret / GNOME Keyring | `secret-tool` (`libsecret-tools`) |
+| **Windows** | Credential Manager | `cmdkey` or PowerShell |
+
+To add a platform: add platform-specific functions in `keychain.ts` and extend `keychainAvailable()`. The file-based fallback always remains for headless/CI environments.
+
+## Verification
+
+1. `bun run build` — ensure compiled binary works
+2. `resend login --key re_test` — stores in keychain, verify in Keychain Access.app under service "resend-cli"
+3. `resend login --key re_staging` with `--team staging` — second keychain entry
+4. `resend teams list` — shows both teams
+5. `resend teams switch staging` → `resend doctor` — shows staging key from keychain
+6. `resend teams remove staging` — deletes keychain entry
+7. `resend logout` — removes active team's keychain entry
+8. `RESEND_API_KEY=re_env resend doctor` — env override still works
+9. Test with old `credentials.json` containing `api_key` fields — falls back to file