resend-cli 1.2.2 → 1.3.0

package/docs/missing-commands.md

@@ -1,58 +0,0 @@
-# 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

@@ -1,99 +0,0 @@
-# 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

@@ -1,174 +0,0 @@
-# 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

package/install.ps1

@@ -1,141 +0,0 @@
-#!/usr/bin/env pwsh
-# Resend CLI installer for Windows
-#
-# Usage (PowerShell):
-#   irm https://resend.com/install.ps1 | iex
-#
-# Pin a version:
-#   $env:RESEND_VERSION = 'v0.1.0'; irm https://resend.com/install.ps1 | iex
-#
-# Environment variables:
-#   RESEND_INSTALL  - Custom install directory (default: $HOME\.resend)
-#   RESEND_VERSION  - Version to install (default: latest)
-
-param(
-  [string]$Version = $env:RESEND_VERSION
-)
-
-Set-StrictMode -Version Latest
-$ErrorActionPreference = 'Stop'
-
-# ─── Helpers ─────────────────────────────────────────────────────────────────
-
-function Write-Info { param($msg) Write-Host "  $msg" -ForegroundColor DarkGray }
-function Write-Ok   { param($msg) Write-Host "  $msg" -ForegroundColor Green }
-
-function Write-Fail {
-  param($msg)
-  Write-Host "  error: $msg" -ForegroundColor Red
-  exit 1
-}
-
-# ─── Architecture detection ───────────────────────────────────────────────────
-
-if ($env:PROCESSOR_ARCHITECTURE -notin @('AMD64', 'EM64T')) {
-  Write-Fail "Unsupported architecture: $env:PROCESSOR_ARCHITECTURE`n`n  Resend CLI currently supports Windows x64 only."
-}
-
-# ─── Version + Download URL ───────────────────────────────────────────────────
-
-$repo = 'https://github.com/resend/resend-cli'
-$target = 'windows-x64'
-
-if ($Version) {
-  $Version = $Version.TrimStart('v')
-  if ($Version -notmatch '^\d+\.\d+\.\d+(-[a-zA-Z0-9.]+)?$') {
-    Write-Fail "Invalid version format: $Version`n`n  Expected: semantic version like 0.1.0 or 1.2.3-beta.1`n  Usage:    `$env:RESEND_VERSION = 'v0.1.0'; irm https://resend.com/install.ps1 | iex"
-  }
-  $url = "$repo/releases/download/v$Version/resend-$target.zip"
-} else {
-  $url = "$repo/releases/latest/download/resend-$target.zip"
-}
-
-# ─── Install directory ────────────────────────────────────────────────────────
-
-$installDir = if ($env:RESEND_INSTALL) { $env:RESEND_INSTALL } else { Join-Path $HOME '.resend' }
-$binDir     = Join-Path $installDir 'bin'
-$exe        = Join-Path $binDir 'resend.exe'
-
-if (-not (Test-Path $binDir)) {
-  New-Item -ItemType Directory -Path $binDir -Force | Out-Null
-}
-
-# ─── Download + Extract ───────────────────────────────────────────────────────
-
-Write-Host ""
-Write-Host "  Installing Resend CLI..." -ForegroundColor White
-Write-Host ""
-Write-Info "Downloading from $url"
-Write-Host ""
-
-$tmpDir = Join-Path ([System.IO.Path]::GetTempPath()) "resend-$([System.Guid]::NewGuid())"
-New-Item -ItemType Directory -Path $tmpDir -Force | Out-Null
-$tmpZip = Join-Path $tmpDir 'resend.zip'
-
-try {
-  try {
-    # Force TLS 1.2 for Windows PowerShell 5.1 (no-op on PowerShell 7+ where it is the default)
-    [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
-    $ProgressPreference = 'SilentlyContinue'  # Invoke-WebRequest is ~10x faster without progress bar
-    Invoke-WebRequest -Uri $url -OutFile $tmpZip -UseBasicParsing
-  } catch {
-    Write-Fail "Download failed.`n`n  Possible causes:`n    - No internet connection`n    - The version does not exist: $(if ($Version) { $Version } else { 'latest' })`n    - GitHub is unreachable`n`n  URL: $url"
-  }
-
-  try {
-    Expand-Archive -Path $tmpZip -DestinationPath $binDir -Force
-  } catch {
-    Write-Fail "Failed to extract archive: $_"
-  }
-}
-finally {
-  Remove-Item -Recurse -Force $tmpDir -ErrorAction SilentlyContinue
-}
-
-if (-not (Test-Path $exe)) {
-  Write-Fail "Binary not found after extraction. The download may be corrupted — try again."
-}
-
-# ─── Verify installation ──────────────────────────────────────────────────────
-
-try {
-  $installedVersion = (& $exe --version 2>$null).Trim()
-} catch {
-  $installedVersion = 'unknown'
-}
-
-Write-Host ""
-Write-Ok "Resend CLI $installedVersion installed successfully!"
-Write-Host ""
-Write-Info "Binary:  $exe"
-
-# ─── PATH setup ───────────────────────────────────────────────────────────────
-
-$userPath    = [Environment]::GetEnvironmentVariable('PATH', 'User') ?? ''
-$pathEntries = $userPath -split ';' | Where-Object { $_ -ne '' }
-
-if ($pathEntries -contains $binDir) {
-  # Already on PATH — just print the getting-started line
-  Write-Host ""
-  Write-Host "  Run " -NoNewline
-  Write-Host "resend --help" -ForegroundColor Cyan -NoNewline
-  Write-Host " to get started"
-  Write-Host ""
-  exit 0
-}
-
-# Add to user PATH (persists across sessions — no admin rights needed)
-$newPath = ($pathEntries + $binDir) -join ';'
-[Environment]::SetEnvironmentVariable('PATH', $newPath, 'User')
-$env:PATH = "$env:PATH;$binDir"  # Also update the current session
-
-Write-Info "Added $binDir to PATH (User scope)"
-Write-Host ""
-Write-Info "Restart your terminal, then:"
-Write-Host ""
-Write-Info "Next steps:"
-Write-Host ""
-Write-Host "    `$env:RESEND_API_KEY = 're_...'" -ForegroundColor Cyan
-Write-Host "    resend --help" -ForegroundColor Cyan
-Write-Host ""
-exit 0