Developer Diagnostics (Doctor)

Relevant source files

The following files were used as context for generating this wiki page:

• src/commands/doctor.ts
• tests/commands/doctor.test.ts
• src/lib/update-check.ts
• skills/resend-cli/SKILL.md
• src/commands/emails/send.ts

The Developer Diagnostics system, invoked via the resend doctor command, evaluates the health and configuration of the Resend CLI environment. It identifies issues with installation versions, authentication credentials, and remote domain statuses to ensure the CLI operates correctly.

The system performs a suite of automated checks, ranging from local file system inspections to remote API validations. It provides both human-readable status updates in interactive terminals and structured JSON payloads for automated environments.
Sources: src/commands/doctor.ts:168-175, skills/resend-cli/SKILL.md:144-146

Diagnostic Execution Flow

The doctor command executes four primary diagnostic modules in sequence. Each module returns a result consisting of a status, a message, and optional details.

The diagram shows the sequential execution of health checks and the conditional output formatting based on the environment.
Sources: src/commands/doctor.ts:182-243

Core Diagnostic Modules

1. CLI Version Validation

This module compares the locally installed version against the latest release on GitHub. It uses the GITHUB_RELEASES_URL to fetch version metadata and determines if an update is available.
Sources: src/commands/doctor.ts:38-41, src/lib/update-check.ts:13-14

• Pass: The installed version matches the latest release.
• Warn: A newer version exists or the update check fails due to network issues.
  Sources: src/commands/doctor.ts:64-84

2. API Key Presence

The system verifies if an API key is accessible to the CLI. It checks multiple sources including the --api-key flag, the RESEND_API_KEY environment variable, and the local credentials file.
Sources: src/commands/doctor.ts:87-94, skills/resend-cli/SKILL.md:92-94

• Logic: It calls resolveAuthentication with the refresh: false option to perform a local-only check without exercising the credential against the network.
• Security: The system masks the API key in the output to prevent accidental exposure of secrets.
  Sources: src/commands/doctor.ts:95-101, src/commands/doctor.ts:121-125

3. Credential Storage Backend

This check identifies how the CLI stores sensitive credentials on the local machine. It distinguishes between secure OS-level storage and plaintext files.
Sources: src/commands/doctor.ts:208-212

Storage Type	Status	Description
Secure Storage	Pass	Credentials are encrypted using the system keychain.
Plaintext File	Warn	Credentials reside in a local JSON file without encryption.
Sources: src/commands/doctor.ts:213-228

4. API Validation and Domain Status

This module performs a live network request to the Resend API. It exercises the stored credential by attempting to list domains.
Sources: src/commands/doctor.ts:135-144

The sequence illustrates the interaction between the CLI and the Resend API to validate credential permissions and domain health.
Sources: src/commands/doctor.ts:148-180

Data Structures

The system utilizes standardized types to represent diagnostic outcomes.

type CheckStatus = 'pass' | 'warn' | 'fail';

type CheckResult = {
  name: string;
  status: CheckStatus;
  message: string;
  detail?: string;
};

Sources: src/commands/doctor.ts:31-36

Output and Exit Logic

The diagnostic system adjusts its behavior based on the detected environment:

1. Interactive Mode: Uses animated spinners and colored text for human readability.
2. JSON Mode: Triggered by the --json flag or a non-TTY environment (e.g., CI/CD). It outputs a single JSON object containing all check results.
3. Exit Codes: The process exits with code 1 if any check results in a fail status. If all checks are pass or warn, it exits with code 0.
   Sources: src/commands/doctor.ts:182-184, src/commands/doctor.ts:245-251, tests/commands/doctor.test.ts:129-142

Error Handling

The system differentiates between transient and permanent errors.

• Transient Errors: Network timeouts or OAuth network errors result in a warn status.
• Permanent Errors: Explicit server rejections (e.g., "invalid_grant" or "Invalid API key") result in a fail status.
  Sources: src/commands/doctor.ts:24-29, src/commands/doctor.ts:140-147, tests/commands/doctor.test.ts:175-195

The Developer Diagnostics system ensures that developers have immediate visibility into their local configuration and remote account status, facilitating rapid troubleshooting of CLI-related issues.