resend-cli 1.0.3 → 1.2.0

package/.github/workflows/test-build-windows.yml

@@ -0,0 +1,44 @@
+name: Test Windows Build
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    paths:
+      - src/**
+      - .github/workflows/test-build-windows.yml
+      - .github/workflows/release.yml
+      - bun.lock
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: oven-sh/setup-bun@v2
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Build Windows binary
+        run: bun build --compile --minify --sourcemap src/cli.ts --target=bun-windows-x64 --outfile dist/resend-windows-x64.exe
+
+      - name: Verify binary exists
+        shell: pwsh
+        run: |
+          if (-not (Test-Path dist\resend-windows-x64.exe)) {
+            Write-Error "Binary not found"
+            exit 1
+          }
+
+      - name: Verify binary runs
+        shell: pwsh
+        run: |
+          & dist\resend-windows-x64.exe --version
+          if ($LASTEXITCODE -ne 0) {
+            Write-Error "resend --version failed"
+            exit 1
+          }

package/.github/workflows/test-install-windows.yml

@@ -0,0 +1,48 @@
+name: Test Windows Installer
+
+on:
+  pull_request:
+    paths:
+      - install.ps1
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Run install.ps1 from repo
+        shell: pwsh
+        run: .\install.ps1
+
+      - name: Verify binary exists
+        shell: pwsh
+        run: |
+          $exe = "$env:USERPROFILE\.resend\bin\resend.exe"
+          if (-not (Test-Path $exe)) {
+            Write-Error "Binary not found at $exe"
+            exit 1
+          }
+          Write-Host "Found binary at $exe"
+
+      - name: Verify binary runs
+        shell: pwsh
+        run: |
+          $exe = "$env:USERPROFILE\.resend\bin\resend.exe"
+          & $exe --version
+          if ($LASTEXITCODE -ne 0) {
+            Write-Error "resend --version failed"
+            exit 1
+          }
+
+      - name: Verify PATH was updated
+        shell: pwsh
+        run: |
+          $binDir = "$env:USERPROFILE\.resend\bin"
+          $path = [Environment]::GetEnvironmentVariable("PATH", "User")
+          if ($path -notlike "*$binDir*") {
+            Write-Error "$binDir was not added to PATH"
+            exit 1
+          }
+          Write-Host "PATH correctly updated"

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,424 @@
-# 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
+
+### Homebrew (macOS)
+
+```bash
+brew install resend/cli/resend
+```
+
+### Shell script (macOS and Linux)
+
+```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

package/biome.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://biomejs.dev/schemas/2.4.6/schema.json",
+  "assist": {
+    "actions": {
+      "source": {
+        "organizeImports": "on"
+      }
+    }
+  },
+  "formatter": {
+    "indentStyle": "space",
+    "indentWidth": 2,
+    "lineWidth": 80
+  },
+  "javascript": {
+    "formatter": {
+      "quoteStyle": "single"
+    }
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "recommended": true,
+      "correctness": {
+        "noUnusedImports": "error",
+        "noUnusedVariables": "error"
+      },
+      "style": {
+        "useBlockStatements": "error"
+      }
+    }
+  },
+  "files": {
+    "includes": ["**", "!**/dist", "!**/bun.lock"]
+  }
+}