Local Config & State Management

Relevant source files

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

• src/lib/config.ts
• src/lib/update-check.ts
• src/lib/write-file-atomic.ts
• src/commands/doctor.ts
• tests/lib/write-file-atomic.test.ts
• tests/commands/whoami.test.ts

Local Config & State Management in the Resend CLI handles the persistence of user credentials, environment-specific profiles, and application state such as update notifications. This system ensures that API keys and OAuth tokens remain available across sessions while providing mechanisms for secure storage and atomic file operations.

The system prioritizes credential safety by supporting both plaintext configuration files and secure OS-level storage backends. It also manages non-sensitive state, such as the last time the CLI checked for a newer version, in separate local JSON files.

Sources: src/lib/config.ts, src/lib/update-check.ts, src/commands/doctor.ts

Credential Persistence and Profiles

The CLI stores authentication data in a credentials.json file located in the user's configuration directory. It supports multiple "profiles," allowing you to switch between different Resend accounts or environments (e.g., production vs. staging).

Authentication Resolution Hierarchy

The CLI resolves authentication in a specific order of precedence:

1. Command-line flag: --api-key <key>
2. Environment variable: RESEND_API_KEY
3. Local configuration: Stored in credentials.json using either the active profile or a profile specified via --profile.

Sources: src/lib/config.ts:182-192, src/commands/doctor.ts:98-105

Credential Data Structures

Credentials can be stored as direct API keys or as OAuth grants. The following table describes the fields found in the configuration schema:

Field	Type	Description
active_profile	string	The name of the profile used by default.
profiles	Record<string, ProfileData>	A map of named profiles to their authentication data.
storage	"secure_storage" | "file"	Indicates if credentials are in the OS keychain or the JSON file.

Each profile contains either an api_key (string) or an oauth_grant containing an access_token, refresh_token, and expiry information.

Sources: src/lib/config.ts:16-56, tests/commands/whoami.test.ts:101-110

Atomic File Operations

To prevent data corruption during concurrent writes or sudden process exits, the CLI uses an atomic write pattern. This is particularly critical for the credentials.json and update-state.json files.

The following flowchart illustrates the atomic write process:

The writeFileAtomic function ensures that the target file is only replaced if the write to the temporary file succeeds. It applies restricted permissions (0o600) to ensure only the current user can read the sensitive configuration.

Sources: src/lib/write-file-atomic.ts:11-40, tests/lib/write-file-atomic.test.ts:33-40

State Management for Updates

The CLI tracks its update status to avoid excessive network requests to GitHub. It stores this state in update-state.json.

Update State Schema

The state object persists the timestamp of the last check and the latest known version string.

Property	Type	Description
lastChecked	number	Unix timestamp in milliseconds of the last GitHub API call.
latestVersion	string	The semver string retrieved from the latest release.

Sources: src/lib/update-check.ts:10-13

Update Check Logic

The system compares the local version against the remote version fetched from https://api.github.com/repos/resend/resend-cli/releases/latest.

The check is skipped if the environment is a non-TTY, CI/CD pipeline (e.g., GITHUB_ACTIONS), or if the RESEND_NO_UPDATE_NOTIFIER environment variable is set to 1.

Sources: src/lib/update-check.ts:25-95

System Health Diagnostics

The doctor command serves as the primary interface for auditing local config and state. It validates the presence and validity of credentials and identifies the storage backend in use.

Diagnostic Checks

The doctor command performs the following sequence of checks:

1. CLI Version: Compares the local binary version against the latest GitHub release.
2. API Key Presence: Verifies if a key is available via flags, env vars, or local config.
3. Credential Storage: Reports whether the backend is secure_storage (keychain) or a plaintext file.
4. API Validation: Exercises the key against the Resend API to ensure it is active and has proper permissions.

Sources: src/commands/doctor.ts:32-150

Summary

Local Config & State Management provides the foundation for persistent CLI behavior. By utilizing atomic writes and a tiered authentication resolution strategy, the system maintains data integrity and security. The separation of sensitive credentials from non-sensitive state allows the CLI to perform background tasks like update checks without compromising user security.

Sources: src/lib/config.ts, src/lib/write-file-atomic.ts, src/lib/update-check.ts