resend-cli 1.0.2 → 1.1.0

package/src/commands/doctor.ts

@@ -0,0 +1,298 @@
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { Command } from '@commander-js/extra-typings';
+import { Resend } from 'resend';
+import type { GlobalOpts } from '../lib/client';
+import { maskKey, resolveApiKey } from '../lib/config';
+import { buildHelpText } from '../lib/help-text';
+import { errorMessage, outputResult } from '../lib/output';
+import { createSpinner } from '../lib/spinner';
+import { isInteractive } from '../lib/tty';
+import { PACKAGE_NAME, VERSION } from '../lib/version';
+
+type CheckStatus = 'pass' | 'warn' | 'fail';
+
+type CheckResult = {
+  name: string;
+  status: CheckStatus;
+  message: string;
+  detail?: string;
+};
+
+const statusIcons: Record<CheckStatus, string> = {
+  pass: '\x1B[32m✔\x1B[0m',
+  warn: '\x1B[33m!\x1B[0m',
+  fail: '\x1B[31m✗\x1B[0m',
+};
+
+async function checkCliVersion(): Promise<CheckResult> {
+  try {
+    const encodedName = encodeURIComponent(PACKAGE_NAME);
+    const res = await fetch(
+      `https://registry.npmjs.org/${encodedName}/latest`,
+      {
+        signal: AbortSignal.timeout(5000),
+      },
+    );
+    if (!res.ok) {
+      return {
+        name: 'CLI Version',
+        status: 'warn',
+        message: `v${VERSION} (could not check for updates)`,
+      };
+    }
+    const data = (await res.json()) as { version?: string };
+    const latest = data.version ?? 'unknown';
+    if (latest === VERSION) {
+      return {
+        name: 'CLI Version',
+        status: 'pass',
+        message: `v${VERSION} (latest)`,
+      };
+    }
+    return {
+      name: 'CLI Version',
+      status: 'warn',
+      message: `v${VERSION} (latest: v${latest})`,
+      detail: 'Update available',
+    };
+  } catch {
+    return {
+      name: 'CLI Version',
+      status: 'warn',
+      message: `v${VERSION} (could not check for updates)`,
+    };
+  }
+}
+
+function checkApiKeyPresence(): CheckResult {
+  const resolved = resolveApiKey();
+  if (!resolved) {
+    return {
+      name: 'API Key',
+      status: 'fail',
+      message: 'No API key found',
+      detail: 'Run: resend login',
+    };
+  }
+  const teamInfo = resolved.team ? `, team: ${resolved.team}` : '';
+  return {
+    name: 'API Key',
+    status: 'pass',
+    message: `${maskKey(resolved.key)} (source: ${resolved.source}${teamInfo})`,
+  };
+}
+
+async function checkApiValidationAndDomains(): Promise<CheckResult> {
+  const resolved = resolveApiKey();
+  if (!resolved) {
+    return {
+      name: 'API Validation',
+      status: 'fail',
+      message: 'Skipped — no API key',
+    };
+  }
+
+  try {
+    const resend = new Resend(resolved.key);
+    const { data, error } = await resend.domains.list();
+
+    if (error) {
+      return {
+        name: 'API Validation',
+        status: 'fail',
+        message: `API key invalid: ${error.message}`,
+      };
+    }
+
+    const domains = data?.data ?? [];
+    const verified = domains.filter((d) => d.status === 'verified');
+    const pending = domains.filter((d) => d.status !== 'verified');
+
+    if (domains.length === 0) {
+      return {
+        name: 'Domains',
+        status: 'warn',
+        message: 'No domains configured',
+        detail: 'Add a domain at https://resend.com/domains',
+      };
+    }
+
+    if (verified.length === 0) {
+      return {
+        name: 'Domains',
+        status: 'warn',
+        message: `${pending.length} domain(s) pending verification`,
+        detail: domains.map((d) => `${d.name} (${d.status})`).join(', '),
+      };
+    }
+
+    return {
+      name: 'Domains',
+      status: 'pass',
+      message: `${verified.length} verified, ${pending.length} pending`,
+      detail: domains.map((d) => `${d.name} (${d.status})`).join(', '),
+    };
+  } catch (err) {
+    return {
+      name: 'API Validation',
+      status: 'fail',
+      message: errorMessage(err, 'Failed to validate API key'),
+    };
+  }
+}
+
+function checkAgentDetection(): CheckResult {
+  const home = homedir();
+  const agents: { name: string; found: boolean }[] = [];
+
+  // OpenClaw
+  agents.push({
+    name: 'OpenClaw',
+    found: existsSync(join(home, 'clawd', 'skills')),
+  });
+
+  // Cursor
+  agents.push({ name: 'Cursor', found: existsSync(join(home, '.cursor')) });
+
+  // Claude Desktop
+  const claudeConfigPaths =
+    process.platform === 'darwin'
+      ? [
+          join(
+            home,
+            'Library',
+            'Application Support',
+            'Claude',
+            'claude_desktop_config.json',
+          ),
+        ]
+      : process.platform === 'win32'
+        ? [
+            join(
+              process.env.APPDATA ?? '',
+              'Claude',
+              'claude_desktop_config.json',
+            ),
+          ]
+        : [join(home, '.config', 'Claude', 'claude_desktop_config.json')];
+  agents.push({
+    name: 'Claude Desktop',
+    found: claudeConfigPaths.some(existsSync),
+  });
+
+  // VS Code MCP
+  agents.push({
+    name: 'VS Code',
+    found: existsSync(join(process.cwd(), '.vscode', 'mcp.json')),
+  });
+
+  const detected = agents.filter((a) => a.found);
+
+  if (detected.length === 0) {
+    return {
+      name: 'AI Agents',
+      status: 'pass',
+      message: 'No AI agents detected',
+    };
+  }
+
+  return {
+    name: 'AI Agents',
+    status: 'pass',
+    message: `Detected: ${detected.map((a) => a.name).join(', ')}`,
+    detail: 'Future: run `resend setup <agent>` to configure integration',
+  };
+}
+
+export const doctorCommand = new Command('doctor')
+  .description(
+    'Check CLI version, API key, domain status, and AI agent detection',
+  )
+  .addHelpText(
+    'after',
+    buildHelpText({
+      setup: true,
+      context: `Checks performed:
+  CLI Version    Is the installed version up to date?
+  API Key        Is a key present (--api-key, RESEND_API_KEY, or credentials file)?
+  API Validation Is the key valid and accepted by the Resend API?
+  AI Agents      Detected: Claude Desktop, Cursor, VS Code MCP, OpenClaw`,
+      output: `  {\n    "ok": true,\n    "checks": [\n      {"name":"CLI Version","status":"pass","message":"v0.1.0 (latest)"},\n      {"name":"API Key","status":"pass","message":"re_...abcd (source: env)"},\n      {"name":"Domains","status":"pass","message":"1 verified, 0 pending"},\n      {"name":"AI Agents","status":"pass","message":"Detected: Claude Desktop"}\n    ]\n  }\n  status values: "pass" | "warn" | "fail"\n  Exit code 1 if any check has status "fail"`,
+      examples: ['resend doctor', 'resend doctor --json'],
+    }),
+  )
+  .action(async (_opts, cmd) => {
+    const globalOpts = cmd.optsWithGlobals() as GlobalOpts;
+    const checks: CheckResult[] = [];
+    const interactive = isInteractive() && !globalOpts.json;
+
+    if (interactive) {
+      console.log('\n  Resend Doctor\n');
+    }
+
+    // Check 1: CLI Version
+    let spinner = interactive
+      ? createSpinner('Checking CLI version...', 'orbit')
+      : null;
+    const versionCheck = await checkCliVersion();
+    checks.push(versionCheck);
+    if (versionCheck.status === 'warn') {
+      spinner?.warn(versionCheck.message);
+    } else {
+      spinner?.stop(versionCheck.message);
+    }
+
+    // Check 2: API Key
+    spinner = interactive ? createSpinner('Checking API key...', 'scan') : null;
+    const keyCheck = checkApiKeyPresence();
+    checks.push(keyCheck);
+    if (keyCheck.status === 'fail') {
+      spinner?.fail(keyCheck.message);
+    } else {
+      spinner?.stop(keyCheck.message);
+    }
+
+    // Check 3: API Validation + Domains
+    spinner = interactive
+      ? createSpinner('Validating API key & domains...', 'scan')
+      : null;
+    const domainCheck = await checkApiValidationAndDomains();
+    checks.push(domainCheck);
+    if (domainCheck.status === 'fail') {
+      spinner?.fail(domainCheck.message);
+    } else if (domainCheck.status === 'warn') {
+      spinner?.warn(domainCheck.message);
+    } else {
+      spinner?.stop(domainCheck.message);
+    }
+
+    // Check 4: Agent Detection
+    spinner = interactive
+      ? createSpinner('Detecting AI agents...', 'scan')
+      : null;
+    const agentCheck = checkAgentDetection();
+    checks.push(agentCheck);
+    spinner?.stop(agentCheck.message);
+
+    const hasFails = checks.some((c) => c.status === 'fail');
+
+    if (!globalOpts.json && isInteractive()) {
+      console.log('');
+      for (const check of checks) {
+        const icon = statusIcons[check.status];
+        console.log(`  ${icon} ${check.name}: ${check.message}`);
+        if (check.detail) {
+          console.log(`    ${check.detail}`);
+        }
+      }
+      console.log('');
+    } else {
+      outputResult({ ok: !hasFails, checks }, { json: globalOpts.json });
+    }
+
+    if (hasFails) {
+      process.exit(1);
+    }
+  });

package/src/commands/domains/create.ts

@@ -0,0 +1,83 @@
+import { Command, Option } from '@commander-js/extra-typings';
+import { runCreate } from '../../lib/actions';
+import type { GlobalOpts } from '../../lib/client';
+import { buildHelpText } from '../../lib/help-text';
+import { requireText } from '../../lib/prompts';
+import { renderDnsRecordsTable } from './utils';
+
+export const createDomainCommand = new Command('create')
+  .description('Create a new domain and receive DNS records to configure')
+  .option('--name <domain>', 'Domain name (e.g. example.com)')
+  .addOption(
+    new Option('--region <region>', 'Sending region').choices([
+      'us-east-1',
+      'eu-west-1',
+      'sa-east-1',
+      'ap-northeast-1',
+    ] as const),
+  )
+  .addOption(
+    new Option('--tls <mode>', 'TLS mode (default: opportunistic)').choices([
+      'opportunistic',
+      'enforced',
+    ] as const),
+  )
+  .option('--sending', 'Enable sending capability (default: enabled)')
+  .option('--receiving', 'Enable receiving capability (default: disabled)')
+  .addHelpText(
+    'after',
+    buildHelpText({
+      context:
+        'Non-interactive: --name is required (no prompts when stdin/stdout is not a TTY)',
+      output:
+        '  Full domain object with DNS records array to configure in your DNS provider.',
+      errorCodes: ['auth_error', 'missing_name', 'create_error'],
+      examples: [
+        'resend domains create --name example.com',
+        'resend domains create --name example.com --region eu-west-1 --tls enforced',
+        'resend domains create --name example.com --receiving --json',
+        'resend domains create --name example.com --sending --receiving --json',
+      ],
+    }),
+  )
+  .action(async (opts, cmd) => {
+    const globalOpts = cmd.optsWithGlobals() as GlobalOpts;
+
+    const name = await requireText(
+      opts.name,
+      { message: 'Domain name', placeholder: 'example.com' },
+      { message: 'Missing --name flag.', code: 'missing_name' },
+      globalOpts,
+    );
+
+    await runCreate(
+      {
+        spinner: {
+          loading: 'Creating domain...',
+          success: 'Domain created',
+          fail: 'Failed to create domain',
+        },
+        sdkCall: (resend) =>
+          resend.domains.create({
+            name,
+            ...(opts.region && { region: opts.region }),
+            ...(opts.tls && { tls: opts.tls }),
+            ...((opts.sending || opts.receiving) && {
+              capabilities: {
+                ...(opts.sending && { sending: 'enabled' as const }),
+                ...(opts.receiving && { receiving: 'enabled' as const }),
+              },
+            }),
+          }),
+        onInteractive: (d) => {
+          console.log(`\nDomain created: ${d.name} (id: ${d.id})`);
+          console.log('\nDNS Records to configure:');
+          console.log(renderDnsRecordsTable(d.records, d.name));
+          console.log(
+            `\nRun \`resend domains verify ${d.id}\` after configuring DNS.`,
+          );
+        },
+      },
+      globalOpts,
+    );
+  });

package/src/commands/domains/delete.ts

@@ -0,0 +1,42 @@
+import { Command } from '@commander-js/extra-typings';
+import { runDelete } from '../../lib/actions';
+import type { GlobalOpts } from '../../lib/client';
+import { buildHelpText } from '../../lib/help-text';
+
+export const deleteDomainCommand = new Command('delete')
+  .alias('rm')
+  .description('Delete a domain')
+  .argument('<id>', 'Domain ID')
+  .option('--yes', 'Skip confirmation prompt')
+  .addHelpText(
+    'after',
+    buildHelpText({
+      context:
+        'Non-interactive: --yes is required to confirm deletion when stdin/stdout is not a TTY.',
+      output: '  {"object":"domain","id":"<id>","deleted":true}',
+      errorCodes: ['auth_error', 'confirmation_required', 'delete_error'],
+      examples: [
+        'resend domains delete 4dd369bc-aa82-4ff3-97de-514ae3000ee0 --yes',
+        'resend domains delete 4dd369bc-aa82-4ff3-97de-514ae3000ee0 --yes --json',
+      ],
+    }),
+  )
+  .action(async (id, opts, cmd) => {
+    const globalOpts = cmd.optsWithGlobals() as GlobalOpts;
+    await runDelete(
+      id,
+      !!opts.yes,
+      {
+        confirmMessage: `Delete domain ${id}?\nThis cannot be undone.`,
+        spinner: {
+          loading: 'Deleting domain...',
+          success: 'Domain deleted',
+          fail: 'Failed to delete domain',
+        },
+        object: 'domain',
+        successMsg: 'Domain deleted.',
+        sdkCall: (resend) => resend.domains.remove(id),
+      },
+      globalOpts,
+    );
+  });

package/src/commands/domains/get.ts

@@ -0,0 +1,47 @@
+import { Command } from '@commander-js/extra-typings';
+import { runGet } from '../../lib/actions';
+import type { GlobalOpts } from '../../lib/client';
+import { buildHelpText } from '../../lib/help-text';
+import { renderDnsRecordsTable, statusIndicator } from './utils';
+
+export const getDomainCommand = new Command('get')
+  .description(
+    'Retrieve a domain with its DNS records and current verification status',
+  )
+  .argument('<id>', 'Domain ID')
+  .addHelpText(
+    'after',
+    buildHelpText({
+      output:
+        '  Full domain object including records array and current status.\n\nDomain status values: not_started | pending | verified | failed | temporary_failure',
+      errorCodes: ['auth_error', 'fetch_error'],
+      examples: [
+        'resend domains get 4dd369bc-aa82-4ff3-97de-514ae3000ee0',
+        'resend domains get 4dd369bc-aa82-4ff3-97de-514ae3000ee0 --json',
+      ],
+    }),
+  )
+  .action(async (id, _opts, cmd) => {
+    const globalOpts = cmd.optsWithGlobals() as GlobalOpts;
+    await runGet(
+      {
+        spinner: {
+          loading: 'Fetching domain...',
+          success: 'Domain fetched',
+          fail: 'Failed to fetch domain',
+        },
+        sdkCall: (resend) => resend.domains.get(id),
+        onInteractive: (d) => {
+          console.log(`\n${d.name} — ${statusIndicator(d.status)}`);
+          console.log(`ID: ${d.id}`);
+          console.log(`Region: ${d.region}`);
+          console.log(`Created: ${d.created_at}`);
+          if (d.records.length > 0) {
+            console.log('\nDNS Records:');
+            console.log(renderDnsRecordsTable(d.records, d.name));
+          }
+        },
+      },
+      globalOpts,
+    );
+  });

package/src/commands/domains/index.ts

@@ -0,0 +1,35 @@
+import { Command } from '@commander-js/extra-typings';
+import { buildHelpText } from '../../lib/help-text';
+import { createDomainCommand } from './create';
+import { deleteDomainCommand } from './delete';
+import { getDomainCommand } from './get';
+import { listDomainsCommand } from './list';
+import { updateDomainCommand } from './update';
+import { verifyDomainCommand } from './verify';
+
+export const domainsCommand = new Command('domains')
+  .description('Manage verified sending and receiving domains')
+  .addHelpText(
+    'after',
+    buildHelpText({
+      context: `Domain lifecycle:
+  1. resend domains create --name example.com    (get DNS records)
+  2. Configure DNS records at your DNS provider
+  3. resend domains verify <id>                  (trigger verification)
+  4. resend domains get <id>                     (poll until "verified")`,
+      examples: [
+        'resend domains list',
+        'resend domains create --name example.com --region us-east-1',
+        'resend domains verify 4dd369bc-aa82-4ff3-97de-514ae3000ee0',
+        'resend domains get 4dd369bc-aa82-4ff3-97de-514ae3000ee0',
+        'resend domains update <id> --tls enforced --open-tracking',
+        'resend domains delete <id> --yes',
+      ],
+    }),
+  )
+  .addCommand(createDomainCommand)
+  .addCommand(verifyDomainCommand)
+  .addCommand(getDomainCommand)
+  .addCommand(listDomainsCommand, { isDefault: true })
+  .addCommand(updateDomainCommand)
+  .addCommand(deleteDomainCommand);

package/src/commands/domains/list.ts

@@ -0,0 +1,53 @@
+import { Command } from '@commander-js/extra-typings';
+import { runList } from '../../lib/actions';
+import type { GlobalOpts } from '../../lib/client';
+import { buildHelpText } from '../../lib/help-text';
+import {
+  buildPaginationOpts,
+  parseLimitOpt,
+  printPaginationHint,
+} from '../../lib/pagination';
+import { renderDomainsTable } from './utils';
+
+export const listDomainsCommand = new Command('list')
+  .alias('ls')
+  .description('List all domains')
+  .option('--limit <n>', 'Maximum number of domains to return (1-100)', '10')
+  .option('--after <cursor>', 'Return domains after this cursor (next page)')
+  .option(
+    '--before <cursor>',
+    'Return domains before this cursor (previous page)',
+  )
+  .addHelpText(
+    'after',
+    buildHelpText({
+      output:
+        '  {"object":"list","data":[...],"has_more":true}\n  The list response does not include DNS records — use "resend domains get <id>" for that.',
+      errorCodes: ['auth_error', 'invalid_limit', 'list_error'],
+      examples: [
+        'resend domains list',
+        'resend domains list --limit 25 --json',
+        'resend domains list --after <cursor> --json',
+      ],
+    }),
+  )
+  .action(async (opts, cmd) => {
+    const globalOpts = cmd.optsWithGlobals() as GlobalOpts;
+    const limit = parseLimitOpt(opts.limit, globalOpts);
+    const paginationOpts = buildPaginationOpts(limit, opts.after, opts.before);
+    await runList(
+      {
+        spinner: {
+          loading: 'Fetching domains...',
+          success: 'Domains fetched',
+          fail: 'Failed to list domains',
+        },
+        sdkCall: (resend) => resend.domains.list(paginationOpts),
+        onInteractive: (list) => {
+          console.log(renderDomainsTable(list.data));
+          printPaginationHint(list);
+        },
+      },
+      globalOpts,
+    );
+  });

package/src/commands/domains/update.ts

@@ -0,0 +1,75 @@
+import { Command, Option } from '@commander-js/extra-typings';
+import type { UpdateDomainsOptions } from 'resend';
+import { runWrite } from '../../lib/actions';
+import type { GlobalOpts } from '../../lib/client';
+import { buildHelpText } from '../../lib/help-text';
+import { outputError } from '../../lib/output';
+
+export const updateDomainCommand = new Command('update')
+  .description(
+    'Update domain settings: TLS mode, open tracking, and click tracking',
+  )
+  .argument('<id>', 'Domain ID')
+  .addOption(
+    new Option('--tls <mode>', 'TLS mode').choices([
+      'opportunistic',
+      'enforced',
+    ] as const),
+  )
+  .option('--open-tracking', 'Enable open tracking')
+  .option('--no-open-tracking', 'Disable open tracking')
+  .option('--click-tracking', 'Enable click tracking')
+  .option('--no-click-tracking', 'Disable click tracking')
+  .addHelpText(
+    'after',
+    buildHelpText({
+      output: '  {"object":"domain","id":"<id>"}',
+      errorCodes: ['auth_error', 'no_changes', 'update_error'],
+      examples: [
+        'resend domains update <id> --tls enforced',
+        'resend domains update <id> --open-tracking --click-tracking',
+        'resend domains update <id> --no-open-tracking --json',
+      ],
+    }),
+  )
+  .action(async (id, opts, cmd) => {
+    const globalOpts = cmd.optsWithGlobals() as GlobalOpts;
+
+    const { tls, openTracking, clickTracking } = opts;
+
+    if (!tls && openTracking === undefined && clickTracking === undefined) {
+      outputError(
+        {
+          message:
+            'Provide at least one option to update: --tls, --open-tracking, or --click-tracking.',
+          code: 'no_changes',
+        },
+        { json: globalOpts.json },
+      );
+    }
+
+    const payload: UpdateDomainsOptions = { id };
+    if (tls) {
+      payload.tls = tls;
+    }
+    if (openTracking !== undefined) {
+      payload.openTracking = openTracking;
+    }
+    if (clickTracking !== undefined) {
+      payload.clickTracking = clickTracking;
+    }
+
+    await runWrite(
+      {
+        spinner: {
+          loading: 'Updating domain...',
+          success: 'Domain updated',
+          fail: 'Failed to update domain',
+        },
+        sdkCall: (resend) => resend.domains.update(payload),
+        errorCode: 'update_error',
+        successMsg: `Domain updated: ${id}`,
+      },
+      globalOpts,
+    );
+  });

package/src/commands/domains/utils.ts

@@ -0,0 +1,44 @@
+import type { DomainRecords } from 'resend';
+import { renderTable } from '../../lib/table';
+
+export function renderDnsRecordsTable(
+  records: DomainRecords[],
+  domainName: string,
+): string {
+  const rows = records.map((r) => {
+    const displayName = r.name
+      ? r.name.includes('.')
+        ? r.name
+        : `${r.name}.${domainName}`
+      : domainName;
+    return [r.type, displayName, r.ttl, r.value];
+  });
+  return renderTable(
+    ['Type', 'Name', 'TTL', 'Value'],
+    rows,
+    '(no DNS records)',
+  );
+}
+
+export function renderDomainsTable(
+  domains: Array<{ id: string; name: string; status: string; region: string }>,
+): string {
+  const rows = domains.map((d) => [d.name, d.status, d.region, d.id]);
+  return renderTable(['Name', 'Status', 'Region', 'ID'], rows, '(no domains)');
+}
+
+export function statusIndicator(status: string): string {
+  switch (status) {
+    case 'verified':
+      return '✓ Verified';
+    case 'pending':
+      return '⏳ Pending';
+    case 'not_started':
+      return '○ Not started';
+    case 'failed':
+    case 'temporary_failure':
+      return '✗ Failed';
+    default:
+      return status;
+  }
+}