resend-cli 1.0.2 → 1.1.0

package/.claude/settings.local.json

@@ -0,0 +1,14 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(git config:*)",
+      "Bash(find /Users/zeno/Projects/resend/resend-cli/src -name \"index.ts\" -path \"*/commands/index.ts\" -o -path \"*/cli.ts\" | xargs ls -la 2>/dev/null)",
+      "Bash(bun run:*)",
+      "Bash(./dist/resend --help 2>&1 | head -30)",
+      "Bash(./dist/resend whoami:*)",
+      "Bash(npx tsc:*)",
+      "Bash(npx vitest:*)",
+      "Bash(bun test:*)"
+    ]
+  }
+}

package/.github/scripts/pr-title-check.js

@@ -0,0 +1,34 @@
+import fs from 'node:fs';
+
+const eventPath = process.env.GITHUB_EVENT_PATH;
+if (!eventPath) {
+  console.error(
+    'GITHUB_EVENT_PATH is not set. This script must run inside GitHub Actions.',
+  );
+  process.exit(1);
+}
+
+const eventJson = JSON.parse(fs.readFileSync(eventPath, 'utf8'));
+const prTitle = eventJson.pull_request?.title;
+if (!prTitle) {
+  console.error('Could not read pull_request.title from event payload.');
+  process.exit(1);
+}
+
+const isValidType = (title) =>
+  /^(feat|fix|chore|refactor)(\([a-zA-Z0-9-]+\))?:\s[a-z0-9].*$/.test(title);
+
+const validateTitle = (title) => {
+  if (!isValidType(title)) {
+    console.error(
+      `PR title does not follow the required format "[type]: [description]"
+  Examples: "feat: add --cc flag"  |  "fix: domain fetch timeout"
+  Types:    feat · fix · chore · refactor
+  Rules:    lowercase after the colon`,
+    );
+    process.exit(1);
+  }
+  console.info(`PR title valid: "${title}"`);
+};
+
+validateTitle(prTitle);

package/.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+jobs:
+  lint:
+    runs-on: blacksmith-2vcpu-ubuntu-2204
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+      - run: bun install --frozen-lockfile
+      - run: bun run lint
+
+  typecheck:
+    runs-on: blacksmith-2vcpu-ubuntu-2204
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+      - run: bun install --frozen-lockfile
+      - run: bun run typecheck
+
+  test:
+    runs-on: blacksmith-2vcpu-ubuntu-2204
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+      - run: bun install --frozen-lockfile
+      - run: bun run test

package/.github/workflows/pr-title-check.yml

@@ -0,0 +1,13 @@
+name: PR Title Check
+on:
+  pull_request:
+    types: [opened, edited, synchronize, reopened]
+permissions:
+  contents: read
+  pull-requests: read
+jobs:
+  pr-title-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: node .github/scripts/pr-title-check.js

package/.github/workflows/release.yml

@@ -0,0 +1,93 @@
+name: Release
+on:
+  push:
+    tags:
+      - 'v*'
+permissions:
+  contents: write
+concurrency:
+  group: release
+  cancel-in-progress: false
+jobs:
+  release:
+    runs-on: blacksmith-2vcpu-ubuntu-2204
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: oven-sh/setup-bun@v2
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Build binaries
+        run: |
+          bun build --compile --minify --sourcemap --bytecode src/cli.ts --target=bun-darwin-arm64  --outfile dist/resend-darwin-arm64
+          bun build --compile --minify --sourcemap --bytecode src/cli.ts --target=bun-darwin-x64    --outfile dist/resend-darwin-x64
+          bun build --compile --minify --sourcemap --bytecode src/cli.ts --target=bun-linux-x64     --outfile dist/resend-linux-x64
+          bun build --compile --minify --sourcemap --bytecode src/cli.ts --target=bun-linux-arm64   --outfile dist/resend-linux-arm64
+          bun build --compile --minify --sourcemap --bytecode src/cli.ts --target=bun-windows-x64   --outfile dist/resend-windows-x64.exe
+
+      - name: Verify binaries
+        run: |
+          for f in dist/resend-darwin-arm64 dist/resend-darwin-x64 \
+                    dist/resend-linux-x64 dist/resend-linux-arm64 \
+                    dist/resend-windows-x64.exe; do
+            [ -s "$f" ] || { echo "Missing or empty: $f"; exit 1; }
+          done
+
+      - name: Package archives
+        run: |
+          cd dist
+          for bin in resend-darwin-arm64 resend-darwin-x64 resend-linux-x64 resend-linux-arm64; do
+            cp "$bin" resend
+            chmod +x resend
+            tar -czf "${bin}.tar.gz" resend
+            rm resend
+          done
+          cp resend-windows-x64.exe resend.exe
+          zip resend-windows-x64.zip resend.exe
+          rm resend.exe
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+          body: |
+            ## Install
+
+            **macOS / Linux**
+            ```sh
+            curl -fsSL https://resend.com/install.sh | bash
+            ```
+
+            **Windows (PowerShell)**
+            ```pwsh
+            irm https://resend.com/install.ps1 | iex
+            ```
+
+            **GitHub CLI** _(use while repo is private)_
+            ```sh
+            gh release download --repo resend/resend-cli --pattern "resend-darwin-arm64.tar.gz"
+            tar -xzf resend-darwin-arm64.tar.gz && sudo mv resend /usr/local/bin/ && rm resend-darwin-arm64.tar.gz
+            ```
+          files: |
+            dist/resend-darwin-arm64.tar.gz
+            dist/resend-darwin-x64.tar.gz
+            dist/resend-linux-x64.tar.gz
+            dist/resend-linux-arm64.tar.gz
+            dist/resend-windows-x64.zip
+
+  notify-tap:
+    name: Trigger Homebrew Tap Update
+    needs: release
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Dispatch publish-release workflow on tap
+        env:
+          GH_TOKEN: ${{ secrets.RELEASE_CLI_ON_HOMEBREW }}
+        run: |
+          gh workflow run publish-release.yml \
+            --repo resend/homebrew-cli \
+            --field version="${GITHUB_REF_NAME}"

package/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+## [0.2.0] - 2026-02-18
+
+### Added
+
+- `resend domains` — create, verify, get, list, update, delete sending domains
+- `resend api-keys` — create, list, delete API keys
+- `resend broadcasts` — full broadcast lifecycle (create, send, get, list, update, delete)
+- `resend contacts` — manage contacts, segments, and topics across all CRUD operations
+- `resend emails batch` — send up to 100 emails in a single request from a JSON file
+- Shared pagination (`--limit`, `--after`, `--before`) on all list commands
+- `--html-file` flag on `emails send` and `broadcasts create` to read body from a file
+
+### Fixed
+
+- `isInteractive()` now checks both `stdin` and `stdout` TTY — CI environments are correctly detected as non-interactive
+- `domains delete` now returns a consistent `{ id, deleted: true }` object instead of an empty `{}`
+
+### Changed
+
+- All delete commands return a uniform `{ object, id, deleted: true }` response
+- `--help` improved across all commands with output shape, error codes, and usage examples
+
+---
+
+## [0.1.0] - 2026-02-18
+
+- Initial release: `auth login`, `emails send`, `doctor`
+- Auto JSON output when stdout is not a TTY (`--json`)
+- Cross-platform binaries for macOS, Linux, and Windows via GitHub Actions

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2024 stretch
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2025 Resend
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,19 +1,416 @@
-# resend-cli
-Simple, pretty command-line based tool for sending emails, managing audiences, etc via [Resend](https://resend.com).
-
-## install
-Install resend-cli by running `npm i -g resend-cli`.  
-Do not install resend-cli locally, without the `-g` flag, since it does not make sense for it to be a project dependency.
-
-## usage
-resend-cli does not require any arguments. If you are running resend-cli for the first time, the command-line will prompt you for an API key.
-API keys must have full access for all features of the CLI to work properly. You may create an API key from the [dashboard](https://resend.com/api-keys).
-
-After this, the API key will be saved in plain text (!) at ~/.resend_config.json. For this reason, avoid installing resend-cli on public or shared computers.  
-
-To exit resend-cli, use the Ctrl+C keyboard shortcut.
-
-## misc
-visit the [project page](https://pablogracia.net/projects/resend-cli) to learn more about this project.  
-
-Contributions welcome. Stars encouraged.
+# Resend CLI
+
+Command-line interface for the [Resend](https://resend.com) email API. Works for humans, AI agents, and CI/CD pipelines.
+
+## Install
+
+```bash
+curl -fsSL https://resend.com/install.sh | bash
+```
+
+## Local development
+
+Use this when you want to change the CLI and run your build locally.
+
+### Prerequisites
+
+- [Bun](https://bun.sh) (runtime and package manager)
+
+### Setup
+
+1. **Clone the repo**
+
+   ```bash
+   git clone https://github.com/resend/resend-cli.git
+   cd resend-cli
+   ```
+
+2. **Install dependencies**
+
+   ```bash
+   bun install
+   ```
+
+3. **Build locally**
+
+   ```bash
+   bun run build
+   ```
+
+   Output: `./dist/resend`
+
+### Running the CLI locally
+
+Use the built binary directly:
+
+```bash
+./dist/resend --version
+```
+
+Or add the project to your `PATH`:
+
+```bash
+export PATH="$(pwd)/dist:$PATH"
+resend doctor
+```
+
+### Making changes
+
+After editing source files, rebuild:
+
+```bash
+bun run build
+```
+
+## Quick start
+
+```bash
+# Authenticate
+resend login
+
+# Send an email
+resend emails send \
+  --from "you@yourdomain.com" \
+  --to recipient@example.com \
+  --subject "Hello from Resend CLI" \
+  --text "Sent from my terminal."
+
+# Check your environment
+resend doctor
+```
+
+---
+
+## Authentication
+
+The CLI resolves your API key using the following priority chain:
+
+| Priority | Source | How to set |
+|----------|--------|------------|
+| 1 (highest) | `--api-key` flag | `resend --api-key re_xxx emails send ...` |
+| 2 | `RESEND_API_KEY` env var | `export RESEND_API_KEY=re_xxx` |
+| 3 (lowest) | Config file | `resend login` |
+
+If no key is found from any source, the CLI errors with code `auth_error`.
+
+---
+
+## Commands
+
+### `resend login`
+
+Authenticate by storing your API key locally. The key is validated against the Resend API before being saved.
+
+```bash
+resend login
+```
+
+#### Interactive mode (default in terminals)
+
+When run in a terminal, the command checks for an existing key:
+
+- **No key found** — Offers to open the [Resend API keys dashboard](https://resend.com/api-keys) in your browser so you can create one, then prompts for the key.
+- **Existing key found** — Shows the key source (`env`, `config`) and prompts for a new key to replace it.
+
+The key is entered via a masked password input and must start with `re_`.
+
+#### Non-interactive mode (CI, pipes, scripts)
+
+When stdin is not a TTY, the `--key` flag is required:
+
+```bash
+resend login --key re_xxxxxxxxxxxxx
+```
+
+Omitting `--key` in non-interactive mode exits with error code `missing_key`.
+
+#### Options
+
+| Flag | Description |
+|------|-------------|
+| `--key <key>` | API key to store (required in non-interactive mode) |
+
+#### Output
+
+On success, credentials are saved to `~/.config/resend/credentials.json` with `0600` permissions (owner read/write only). The config directory is created with `0700` permissions.
+
+```bash
+# JSON output
+resend login --key re_xxx --json
+# => {"success":true,"config_path":"/Users/you/.config/resend/credentials.json"}
+```
+
+#### Error codes
+
+| Code | Cause |
+|------|-------|
+| `missing_key` | No `--key` provided in non-interactive mode |
+| `invalid_key_format` | Key does not start with `re_` |
+| `validation_failed` | Resend API rejected the key |
+
+---
+
+### `resend emails send`
+
+Send an email via the Resend API. Provide all options via flags for scripting, or let the CLI prompt interactively for missing fields.
+
+```bash
+resend emails send \
+  --from "Name <sender@yourdomain.com>" \
+  --to recipient@example.com \
+  --subject "Subject line" \
+  --text "Plain text body"
+```
+
+#### Options
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--from <address>` | Yes | Sender email address (must be from a verified domain) |
+| `--to <addresses...>` | Yes | One or more recipient email addresses (space-separated) |
+| `--subject <subject>` | Yes | Email subject line |
+| `--text <text>` | One of text/html/html-file | Plain text body |
+| `--html <html>` | One of text/html/html-file | HTML body as a string |
+| `--html-file <path>` | One of text/html/html-file | Path to an HTML file to use as body |
+| `--cc <addresses...>` | No | CC recipients (space-separated) |
+| `--bcc <addresses...>` | No | BCC recipients (space-separated) |
+| `--reply-to <address>` | No | Reply-to email address |
+
+#### Interactive mode
+
+When run in a terminal without all required flags, the CLI prompts for missing fields:
+
+```bash
+# prompts for from, to, subject, and body
+resend emails send
+
+# prompts only for missing fields
+resend emails send --from "you@yourdomain.com"
+```
+
+#### Non-interactive mode
+
+When piped or run in CI, all required flags must be provided. Missing flags cause an error listing what's needed:
+
+```bash
+echo "" | resend emails send --from "you@yourdomain.com"
+# Error: Missing required flags: --to, --subject
+```
+
+A body (`--text`, `--html`, or `--html-file`) is also required — omitting all three exits with code `missing_body`.
+
+#### Examples
+
+**Multiple recipients:**
+
+```bash
+resend emails send \
+  --from "you@yourdomain.com" \
+  --to alice@example.com bob@example.com \
+  --subject "Team update" \
+  --text "Hello everyone"
+```
+
+**HTML from a file:**
+
+```bash
+resend emails send \
+  --from "you@yourdomain.com" \
+  --to recipient@example.com \
+  --subject "Newsletter" \
+  --html-file ./newsletter.html
+```
+
+**With CC, BCC, and reply-to:**
+
+```bash
+resend emails send \
+  --from "you@yourdomain.com" \
+  --to recipient@example.com \
+  --subject "Meeting notes" \
+  --text "See attached." \
+  --cc manager@example.com \
+  --bcc archive@example.com \
+  --reply-to noreply@example.com
+```
+
+**Overriding the API key for one send:**
+
+```bash
+resend --api-key re_other_key emails send \
+  --from "you@yourdomain.com" \
+  --to recipient@example.com \
+  --subject "Test" \
+  --text "Using a different key"
+```
+
+#### Output
+
+Returns the email ID on success:
+
+```json
+{ "id": "49a3999c-0ce1-4ea6-ab68-afcd6dc2e794" }
+```
+
+#### Error codes
+
+| Code | Cause |
+|------|-------|
+| `auth_error` | No API key found or client creation failed |
+| `missing_body` | No `--text`, `--html`, or `--html-file` provided |
+| `file_read_error` | Could not read the file passed to `--html-file` |
+| `send_error` | Resend API returned an error |
+
+---
+
+### `resend doctor`
+
+Run environment diagnostics. Verifies your CLI version, API key, domains, and detects AI agent integrations.
+
+```bash
+resend doctor
+```
+
+#### Checks performed
+
+| Check | Pass | Warn | Fail |
+|-------|------|------|------|
+| **CLI Version** | Running latest | Update available or registry unreachable | — |
+| **API Key** | Key found (shows masked key + source) | — | No key found |
+| **Domains** | Verified domains exist | No domains or all pending verification | API key invalid |
+| **AI Agents** | Lists detected agents (or none) | — | — |
+
+The API key is always masked in output (e.g. `re_...xxxx`).
+
+#### Interactive mode
+
+In a terminal, shows animated spinners for each check with colored status icons:
+
+```
+  Resend Doctor
+
+  ✔ CLI Version: v0.1.0 (latest)
+  ✔ API Key: re_...xxxx (source: env)
+  ✔ Domains: 2 verified, 0 pending
+  ✔ AI Agents: Detected: Cursor, Claude Desktop
+```
+
+#### JSON mode
+
+```bash
+resend doctor --json
+```
+
+```json
+{
+  "ok": true,
+  "checks": [
+    { "name": "CLI Version", "status": "pass", "message": "v0.1.0 (latest)" },
+    { "name": "API Key", "status": "pass", "message": "re_...xxxx (source: env)" },
+    { "name": "Domains", "status": "pass", "message": "2 verified, 0 pending" },
+    { "name": "AI Agents", "status": "pass", "message": "Detected: Cursor" }
+  ]
+}
+```
+
+Each check has a `status` of `pass`, `warn`, or `fail`. The top-level `ok` is `false` if any check is `fail`.
+
+#### Detected AI agents
+
+| Agent | Detection method |
+|-------|-----------------|
+| OpenClaw | `~/clawd/skills` directory exists |
+| Cursor | `~/.cursor` directory exists |
+| Claude Desktop | Platform-specific config file exists |
+| VS Code | `.vscode/mcp.json` in current directory |
+
+#### Exit code
+
+Exits `0` when all checks pass or warn. Exits `1` if any check fails.
+
+---
+
+## Global options
+
+These flags work on every command and are passed before the subcommand:
+
+```bash
+resend [global options] <command> [command options]
+```
+
+| Flag | Description |
+|------|-------------|
+| `--api-key <key>` | Override API key for this invocation (takes highest priority) |
+| `--json` | Force JSON output even in interactive terminals |
+| `--version` | Print version and exit |
+| `--help` | Show help text |
+
+---
+
+## Output behavior
+
+The CLI has two output modes:
+
+| Mode | When | Stdout | Stderr |
+|------|------|--------|--------|
+| **Interactive** | Terminal (TTY) | Formatted text | Spinners, prompts |
+| **Machine** | Piped, CI, or `--json` | JSON | Nothing |
+
+Switching is automatic — pipe to another command and JSON output activates:
+
+```bash
+resend doctor | jq '.checks[].name'
+resend emails send --from ... --to ... --subject ... --text ... | jq '.id'
+```
+
+### Error output
+
+Errors always exit with code `1` and output structured JSON to stdout:
+
+```json
+{ "error": { "message": "No API key found", "code": "auth_error" } }
+```
+
+---
+
+## Agent & CI/CD usage
+
+### CI/CD
+
+Set `RESEND_API_KEY` as an environment variable — no `resend login` needed:
+
+```yaml
+# GitHub Actions
+env:
+  RESEND_API_KEY: ${{ secrets.RESEND_API_KEY }}
+steps:
+  - run: |
+      resend emails send \
+        --from "deploy@yourdomain.com" \
+        --to "team@yourdomain.com" \
+        --subject "Deploy complete" \
+        --text "Version ${{ github.sha }} deployed."
+```
+
+### AI agents
+
+Agents calling the CLI as a subprocess automatically get JSON output (non-TTY detection). The contract:
+
+- **Input:** All required flags must be provided (no interactive prompts)
+- **Output:** JSON to stdout, nothing to stderr
+- **Exit code:** `0` success, `1` error
+- **Errors:** Always include `message` and `code` fields
+
+---
+
+## Configuration
+
+| Item | Path | Notes |
+|------|------|-------|
+| Config directory | `~/.config/resend/` | Respects `$XDG_CONFIG_HOME` on Linux, `%APPDATA%` on Windows |
+| Credentials | `~/.config/resend/credentials.json` | `0600` permissions (owner read/write) |
+| Install directory | `~/.resend/bin/` | Respects `$RESEND_INSTALL` |
+
+## License
+
+MIT