resend-cli 1.4.1 → 1.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "resend-cli",
-  "version": "1.4.1",
+  "version": "1.5.0",
   "description": "The official CLI for Resend",
   "license": "MIT",
   "repository": {
@@ -12,51 +12,47 @@
     "cli",
     "resend",
     "email",
-    "api"
+    "api",
+    "tanstack-intent"
   ],
   "engines": {
     "node": ">=20"
   },
-  "packageManager": "pnpm@10.32.1",
   "files": [
-    "dist/cli.cjs"
+    "dist/cli.cjs",
+    "skills/"
   ],
   "type": "module",
   "bin": {
     "resend": "./dist/cli.cjs"
   },
-  "scripts": {
-    "dev": "tsx src/cli.ts",
-    "dev:watch": "tsx --watch src/cli.ts",
-    "build": "esbuild src/cli.ts --bundle --platform=node --format=cjs --minify --outfile=dist/cli.cjs",
-    "build:bin": "pnpm build && pkg dist/cli.cjs --compress Brotli --target node24 --output dist/resend",
-    "lint": "biome check .",
-    "lint:fix": "biome check --write .",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "test:e2e": "vitest run --config vitest.config.e2e.ts",
-    "prepack": "pnpm build"
-  },
   "dependencies": {
     "@clack/prompts": "1.1.0",
     "@commander-js/extra-typings": "14.0.0",
     "commander": "14.0.3",
-    "picocolors": "^1.1.1",
-    "resend": "6.9.3"
-  },
-  "pnpm": {
-    "onlyBuiltDependencies": [
-      "esbuild",
-      "@biomejs/biome"
-    ]
+    "picocolors": "1.1.1",
+    "resend": "6.9.4"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.4.6",
+    "@biomejs/biome": "2.4.7",
     "@types/node": "24.12.0",
     "esbuild": "0.27.4",
     "tsx": "4.21.0",
     "typescript": "5.9.3",
-    "vitest": "3.2.4",
+    "vitest": "4.1.0",
     "@yao-pkg/pkg": "6.14.1"
+  },
+  "scripts": {
+    "dev": "tsx src/cli.ts",
+    "dev:watch": "tsx --watch src/cli.ts",
+    "build": "esbuild src/cli.ts --bundle --platform=node --format=cjs --minify --outfile=dist/cli.cjs",
+    "build:bin": "pnpm build && pkg dist/cli.cjs --compress Brotli --target node24 --output dist/resend",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:e2e": "vitest run --config vitest.config.e2e.ts",
+    "sync-skill-version": "node scripts/sync-skill-version.mjs",
+    "version": "pnpm run sync-skill-version && git add skills/resend-cli/SKILL.md"
   }
-}
+}

package/skills/resend-cli/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: resend-cli
+description: >
+  Operate the Resend platform from the terminal — send emails, manage domains,
+  contacts, broadcasts, templates, webhooks, and API keys via the `resend` CLI.
+  Use when the user wants to run Resend commands in the shell, scripts, or CI/CD
+  pipelines. Always load this skill before running `resend` commands — it contains
+  the non-interactive flag contract and gotchas that prevent silent failures.
+license: MIT
+metadata:
+  author: resend
+  version: "1.5.0"
+  homepage: https://resend.com
+  source: https://github.com/resend/resend-cli
+inputs:
+  - name: RESEND_API_KEY
+    description: Resend API key for authenticating CLI commands. Get yours at https://resend.com/api-keys
+    required: true
+references:
+  - references/emails.md
+  - references/domains.md
+  - references/api-keys.md
+  - references/broadcasts.md
+  - references/contacts.md
+  - references/contact-properties.md
+  - references/segments.md
+  - references/templates.md
+  - references/topics.md
+  - references/webhooks.md
+  - references/auth.md
+  - references/workflows.md
+  - references/error-codes.md
+---
+
+# Resend CLI
+
+## Agent Protocol
+
+The CLI auto-detects non-TTY environments and outputs JSON — no `--json` flag needed.
+
+**Rules for agents:**
+- Supply ALL required flags. The CLI will NOT prompt when stdin is not a TTY.
+- Pass `--quiet` (or `-q`) to suppress spinners and status messages.
+- Exit `0` = success, `1` = error.
+- Error JSON goes to stderr, success JSON goes to stdout:
+  ```json
+  {"error":{"message":"...","code":"..."}}
+  ```
+- Use `--api-key` or `RESEND_API_KEY` env var. Never rely on interactive login.
+- All `delete`/`rm` commands require `--yes` in non-interactive mode.
+
+## Authentication
+
+Auth resolves: `--api-key` flag > `RESEND_API_KEY` env > config file (`resend login --key`). Use `--profile` or `RESEND_PROFILE` for multi-profile.
+
+## Global Flags
+
+| Flag | Description |
+|------|-------------|
+| `--api-key <key>` | Override API key for this invocation |
+| `-p, --profile <name>` | Select stored profile |
+| `--json` | Force JSON output (auto in non-TTY) |
+| `-q, --quiet` | Suppress spinners/status (implies `--json`) |
+
+## Available Commands
+
+| Command Group | What it does |
+|--------------|-------------|
+| `emails` | send, get, list, batch, cancel, update |
+| `emails receiving` | list, get, attachments, forward, listen |
+| `domains` | create, verify, update, delete, list |
+| `api-keys` | create, list, delete |
+| `broadcasts` | create, send, update, delete, list |
+| `contacts` | create, update, delete, segments, topics |
+| `contact-properties` | create, update, delete, list |
+| `segments` | create, get, list, delete |
+| `templates` | create, publish, duplicate, delete, list |
+| `topics` | create, update, delete, list |
+| `webhooks` | create, update, listen, delete, list |
+| `auth` | login, logout, switch, rename, remove |
+| `whoami` / `doctor` / `update` / `open` | Utility commands |
+
+Read the matching reference file for detailed flags and output shapes.
+
+## Common Mistakes
+
+| # | Mistake | Fix |
+|---|---------|-----|
+| 1 | **Forgetting `--yes` on delete commands** | All `delete`/`rm` subcommands require `--yes` in non-interactive mode — otherwise the CLI exits with an error |
+| 2 | **Not saving webhook `signing_secret`** | `webhooks create` shows the secret once only — it cannot be retrieved later. Capture it from command output immediately |
+| 3 | **Omitting `--quiet` in CI** | Without `-q`, spinners and status text leak into stdout. Use `-q` to get clean JSON only |
+| 4 | **Using `--scheduled-at` with batch** | Batch sending does not support `scheduled_at` — use single `emails send` instead |
+| 5 | **Expecting `domains list` to include DNS records** | List returns summaries only — use `domains get <id>` for the full `records[]` array |
+| 6 | **Sending a dashboard-created broadcast via CLI** | Only API-created broadcasts can be sent with `broadcasts send` — dashboard broadcasts must be sent from the dashboard |
+| 7 | **Passing `--events` to `webhooks update` expecting additive behavior** | `--events` replaces the entire subscription list — always pass the complete set |
+
+## Common Patterns
+
+**Send an email:**
+```bash
+resend emails send --from "you@domain.com" --to user@example.com --subject "Hello" --text "Body"
+```
+
+**Domain setup flow:**
+```bash
+resend domains create --name example.com --region us-east-1
+# Configure DNS records from output, then:
+resend domains verify <domain-id>
+resend domains get <domain-id>  # check status
+```
+
+**Create and send a broadcast:**
+```bash
+resend broadcasts create --from "news@domain.com" --subject "Update" --segment-id <id> --html "<h1>Hi</h1>" --send
+```
+
+**CI/CD (no login needed):**
+```bash
+RESEND_API_KEY=re_xxx resend emails send --from ... --to ... --subject ... --text ...
+```
+
+**Check environment health:**
+```bash
+resend doctor -q
+```
+
+## When to Load References
+
+- **Sending or reading emails** → [references/emails.md](references/emails.md)
+- **Setting up or verifying a domain** → [references/domains.md](references/domains.md)
+- **Managing API keys** → [references/api-keys.md](references/api-keys.md)
+- **Creating or sending broadcasts** → [references/broadcasts.md](references/broadcasts.md)
+- **Managing contacts, segments, or topics** → [references/contacts.md](references/contacts.md), [references/segments.md](references/segments.md), [references/topics.md](references/topics.md)
+- **Defining contact properties** → [references/contact-properties.md](references/contact-properties.md)
+- **Working with templates** → [references/templates.md](references/templates.md)
+- **Setting up webhooks or listening for events** → [references/webhooks.md](references/webhooks.md)
+- **Auth, profiles, or health checks** → [references/auth.md](references/auth.md)
+- **Multi-step recipes** (setup, CI/CD, broadcast workflow) → [references/workflows.md](references/workflows.md)
+- **Command failed with an error** → [references/error-codes.md](references/error-codes.md)
+- **Resend SDK integration** (Node.js, Python, Go, etc.) → Install the [`resend`](https://github.com/resend/resend-skills) skill
+- **AI agent email inbox** → Install the [`agent-email-inbox`](https://github.com/resend/resend-skills) skill

package/skills/resend-cli/references/api-keys.md

@@ -0,0 +1,33 @@
+# api-keys
+
+Detailed flag specifications for `resend api-keys` commands.
+
+---
+
+## api-keys list
+
+List all API keys (IDs, names, and `created_at` only — tokens never included).
+
+---
+
+## api-keys create
+
+| Flag | Type | Required | Description |
+|------|------|----------|-------------|
+| `--name <name>` | string | Yes (non-interactive) | Key name (max 50 chars) |
+| `--permission <perm>` | string | No | `full_access` (default) \| `sending_access` |
+| `--domain-id <id>` | string | No | Restrict `sending_access` to one domain |
+
+**Output:** `{"id":"...","token":"re_..."}` — token shown once only.
+
+---
+
+## api-keys delete
+
+**Argument:** `<id>` — API key ID
+
+| Flag | Type | Required | Description |
+|------|------|----------|-------------|
+| `--yes` | boolean | Yes (non-interactive) | Skip confirmation |
+
+**Alias:** `rm`

package/skills/resend-cli/references/auth.md

@@ -0,0 +1,67 @@
+# auth & utility
+
+Detailed flag specifications for `resend auth` and utility commands.
+
+---
+
+## auth login
+
+| Flag | Type | Required | Description |
+|------|------|----------|-------------|
+| `--key <key>` | string | Yes (non-interactive) | API key (must start with `re_`) |
+
+---
+
+## auth logout
+
+Removes the active profile's credentials (or all profiles if no `--profile`).
+
+---
+
+## auth list
+
+Lists all profiles with active marker.
+
+---
+
+## auth switch
+
+**Argument:** `[name]` — Profile name (prompts in interactive if omitted)
+
+---
+
+## auth rename
+
+**Arguments:** `[old-name]` `[new-name]` — Prompts in interactive if omitted
+
+---
+
+## auth remove
+
+**Argument:** `[name]` — Profile name (prompts in interactive if omitted)
+
+---
+
+## whoami
+
+No flags. Shows authentication status (local only, no network calls).
+
+---
+
+## doctor
+
+Checks: CLI Version, API Key, Domains, AI Agents.
+
+Exits `0` if all pass/warn, `1` if any fail.
+
+---
+
+## update
+
+Checks GitHub releases for newer version. Shows upgrade command.
+
+---
+
+## open
+
+Opens `https://resend.com/emails` in the default browser.

package/skills/resend-cli/references/broadcasts.md

@@ -0,0 +1,81 @@
+# broadcasts
+
+Detailed flag specifications for `resend broadcasts` commands.
+
+---
+
+## broadcasts list
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--limit <n>` | number | 10 | Max results (1-100) |
+| `--after <cursor>` | string | — | Forward pagination |
+| `--before <cursor>` | string | — | Backward pagination |
+
+---
+
+## broadcasts create
+
+| Flag | Type | Required | Description |
+|------|------|----------|-------------|
+| `--from <address>` | string | Yes | Sender address |
+| `--subject <subject>` | string | Yes | Email subject |
+| `--segment-id <id>` | string | Yes | Target segment |
+| `--html <html>` | string | At least one body flag | HTML body (supports `{{{PROPERTY\|fallback}}}`) |
+| `--html-file <path>` | string | At least one body flag | Path to HTML file |
+| `--text <text>` | string | At least one body flag | Plain-text body |
+| `--name <name>` | string | No | Internal label |
+| `--reply-to <address>` | string | No | Reply-to address |
+| `--preview-text <text>` | string | No | Preview text |
+| `--topic-id <id>` | string | No | Topic for subscription filtering |
+| `--send` | boolean | No | Send immediately (default: save as draft) |
+| `--scheduled-at <datetime>` | string | No | Schedule delivery (only with `--send`) |
+
+---
+
+## broadcasts get
+
+**Argument:** `<id>` — Broadcast ID
+
+Returns full object with html/text, from, subject, status (`draft`|`queued`|`sent`), timestamps.
+
+---
+
+## broadcasts send
+
+Send a draft broadcast.
+
+**Argument:** `<id>` — Broadcast ID
+
+| Flag | Type | Required | Description |
+|------|------|----------|-------------|
+| `--scheduled-at <datetime>` | string | No | Schedule instead of immediate send |
+
+**Note:** Dashboard-created broadcasts cannot be sent via API.
+
+---
+
+## broadcasts update
+
+**Argument:** `<id>` — Broadcast ID (must be draft)
+
+| Flag | Type | Description |
+|------|------|-------------|
+| `--from <address>` | string | Update sender |
+| `--subject <subject>` | string | Update subject |
+| `--html <html>` | string | Update HTML body |
+| `--html-file <path>` | string | Path to HTML file |
+| `--text <text>` | string | Update plain-text body |
+| `--name <name>` | string | Update internal label |
+
+---
+
+## broadcasts delete
+
+**Argument:** `<id>` — Broadcast ID
+
+| Flag | Type | Required | Description |
+|------|------|----------|-------------|
+| `--yes` | boolean | Yes (non-interactive) | Skip confirmation |
+
+**Alias:** `rm`

package/skills/resend-cli/references/contact-properties.md

@@ -0,0 +1,56 @@
+# contact-properties
+
+Detailed flag specifications for `resend contact-properties` commands.
+
+---
+
+## contact-properties list
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--limit <n>` | number | 10 | Max results (1-100) |
+| `--after <cursor>` | string | — | Forward pagination |
+| `--before <cursor>` | string | — | Backward pagination |
+
+---
+
+## contact-properties create
+
+| Flag | Type | Required | Description |
+|------|------|----------|-------------|
+| `--key <key>` | string | Yes (non-interactive) | Property key name |
+| `--type <type>` | string | Yes (non-interactive) | `string` \| `number` |
+| `--fallback-value <value>` | string \| number | No | Default in templates (parsed as number when `--type number`) |
+
+Reserved keys: `FIRST_NAME`, `LAST_NAME`, `EMAIL`, `UNSUBSCRIBE_URL`
+
+---
+
+## contact-properties get
+
+**Argument:** `<id>` — Property UUID
+
+---
+
+## contact-properties update
+
+**Argument:** `<id>` — Property UUID
+
+| Flag | Type | Description |
+|------|------|-------------|
+| `--fallback-value <value>` | string | New fallback |
+| `--clear-fallback-value` | boolean | Remove fallback (mutually exclusive with above) |
+
+Key and type are immutable after creation.
+
+---
+
+## contact-properties delete
+
+**Argument:** `<id>` — Property UUID
+
+| Flag | Type | Required | Description |
+|------|------|----------|-------------|
+| `--yes` | boolean | Yes (non-interactive) | Skip confirmation |
+
+**Warning:** Removes property from ALL contacts permanently.

package/skills/resend-cli/references/contacts.md

@@ -0,0 +1,100 @@
+# contacts
+
+Detailed flag specifications for `resend contacts` commands.
+
+---
+
+## contacts list
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--limit <n>` | number | 10 | Max results (1-100) |
+| `--after <cursor>` | string | — | Forward pagination |
+| `--before <cursor>` | string | — | Backward pagination |
+
+---
+
+## contacts create
+
+| Flag | Type | Required | Description |
+|------|------|----------|-------------|
+| `--email <email>` | string | Yes | Contact email |
+| `--first-name <name>` | string | No | First name |
+| `--last-name <name>` | string | No | Last name |
+| `--unsubscribed` | boolean | No | Globally unsubscribe |
+| `--properties <json>` | string | No | Custom properties JSON |
+| `--segment-id <id...>` | string[] | No | Add to segment(s) |
+
+---
+
+## contacts get
+
+**Argument:** `<id|email>` — Contact UUID or email address (both accepted)
+
+---
+
+## contacts update
+
+**Argument:** `<id|email>` — Contact UUID or email address
+
+| Flag | Type | Description |
+|------|------|-------------|
+| `--unsubscribed` | boolean | Set unsubscribed |
+| `--no-unsubscribed` | boolean | Re-subscribe |
+| `--properties <json>` | string | Merge properties (set key to `null` to clear) |
+
+---
+
+## contacts delete
+
+**Argument:** `<id|email>` — Contact UUID or email address
+
+| Flag | Type | Required | Description |
+|------|------|----------|-------------|
+| `--yes` | boolean | Yes (non-interactive) | Skip confirmation |
+
+**Alias:** `rm`
+
+---
+
+## contacts segments
+
+List segments a contact belongs to.
+
+**Argument:** `<id|email>` — Contact UUID or email
+
+---
+
+## contacts add-segment
+
+**Argument:** `<contactId>` — Contact UUID or email
+
+| Flag | Type | Required | Description |
+|------|------|----------|-------------|
+| `--segment-id <id>` | string | Yes (non-interactive) | Segment ID to add to |
+
+---
+
+## contacts remove-segment
+
+**Arguments:** `<id|email>` `<segmentId>`
+
+---
+
+## contacts topics
+
+List contact's topic subscriptions.
+
+**Argument:** `<id|email>` — Contact UUID or email
+
+---
+
+## contacts update-topics
+
+**Argument:** `<id|email>` — Contact UUID or email
+
+| Flag | Type | Required | Description |
+|------|------|----------|-------------|
+| `--topics <json>` | string | Yes (non-interactive) | JSON array: `[{"id":"topic-uuid","subscription":"opt_in"}]` |
+
+Subscription values: `opt_in` | `opt_out`

package/skills/resend-cli/references/domains.md

@@ -0,0 +1,79 @@
+# domains
+
+Detailed flag specifications for `resend domains` commands.
+
+---
+
+## domains list
+
+List all domains.
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--limit <n>` | number | 10 | Max results (1-100) |
+| `--after <cursor>` | string | — | Forward pagination |
+| `--before <cursor>` | string | — | Backward pagination |
+
+**Note:** List does NOT include DNS records. Use `domains get` for full details.
+
+---
+
+## domains create
+
+Create a new domain and receive DNS records to configure.
+
+| Flag | Type | Required | Description |
+|------|------|----------|-------------|
+| `--name <domain>` | string | Yes (non-interactive) | Domain name (e.g., `example.com`) |
+| `--region <region>` | string | No | `us-east-1` \| `eu-west-1` \| `sa-east-1` \| `ap-northeast-1` |
+| `--tls <mode>` | string | No | `opportunistic` (default) \| `enforced` |
+| `--sending` | boolean | No | Enable sending (default: enabled) |
+| `--receiving` | boolean | No | Enable receiving (default: disabled) |
+
+**Output:** Domain object with `records[]` array of DNS records to configure.
+
+---
+
+## domains get
+
+**Argument:** `<id>` — Domain ID
+
+Returns full domain with `records[]`, `status` (`not_started`|`pending`|`verified`|`failed`|`temporary_failure`), `capabilities`, `region`.
+
+---
+
+## domains verify
+
+Trigger async DNS verification.
+
+**Argument:** `<id>` — Domain ID
+
+**Output:** `{"object":"domain","id":"..."}`
+
+---
+
+## domains update
+
+**Argument:** `<id>` — Domain ID
+
+| Flag | Type | Description |
+|------|------|-------------|
+| `--tls <mode>` | string | `opportunistic` \| `enforced` |
+| `--open-tracking` | boolean | Enable open tracking |
+| `--no-open-tracking` | boolean | Disable open tracking |
+| `--click-tracking` | boolean | Enable click tracking |
+| `--no-click-tracking` | boolean | Disable click tracking |
+
+At least one option required.
+
+---
+
+## domains delete
+
+**Argument:** `<id>` — Domain ID
+
+| Flag | Type | Required | Description |
+|------|------|----------|-------------|
+| `--yes` | boolean | Yes (non-interactive) | Skip confirmation |
+
+**Alias:** `rm`