AI Agent Protocol & Skills

Relevant source files

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

• skills/resend-cli/SKILL.md
• src/commands/doctor.ts
• src/commands/emails/send.ts
• src/commands/careers/apply.ts
• tests/commands/emails/batch.test.ts
• skill-evals/resend-cli/evals.json
• skills/resend-cli/references/workflows.md

The Resend CLI functions as a "skill" for AI agents and automated systems to operate the Resend platform via terminal commands. It provides a structured protocol for non-interactive environments, ensuring predictable output and execution in scripts, CI/CD pipelines, and agent-driven workflows.

Sources: skills/resend-cli/SKILL.md:4-15, skill-evals/resend-cli/evals.json

Agent Protocol Architecture

The CLI implements an auto-detection mechanism for its execution environment. When it identifies a non-TTY (Teletype) environment, it modifies its behavior to serve machine-readable requirements.

Environment Detection and Output Logic

The CLI automatically switches to JSON output when it is not connected to a terminal. Agents must provide all required flags because the CLI disables interactive prompts in this mode.

The diagram shows how the CLI bifurcates logic based on terminal detection and agent-specific flags.
Sources: skills/resend-cli/SKILL.md:43-53, src/commands/doctor.ts:187-200

Protocol Rules for Agents

• Mandatory Flags: You must supply all required arguments; the CLI fails with an error if input is missing.
• Silent Execution: Pass --quiet or -q to remove spinners and status noise from stderr.
• Exit Codes: The system returns 0 for success and 1 for any failure.
• Standardized Errors: Error information is sent to stderr as a JSON object containing a message and code.
• Destructive Actions: All delete or rm commands require the --yes flag to bypass confirmation prompts.

Sources: skills/resend-cli/SKILL.md:46-55, src/commands/careers/apply.ts:96-120

Authentication and Security

Agents authenticate primarily through environment variables to avoid persisting credentials in command history or logs.

Method	Variable / Flag	Requirement
Primary Env	RESEND_API_KEY	Mandatory for CI/CD and Agents
Profile Env	RESEND_PROFILE	Optional for multi-account setups
Global Flag	--api-key <key>	Overrides environment variables
Profile Flag	--profile <name>	Selects a specific stored credential

Sources: skills/resend-cli/SKILL.md:21-36, src/commands/doctor.ts:103-134

Credential Validation Flow

The resend doctor command allows agents to verify the health of their environment before performing critical tasks.

This flow illustrates the multi-step verification process used to ensure an agent has a valid, working environment.
Sources: src/commands/doctor.ts:180-280, skills/resend-cli/references/workflows.md:14-23

Dry-Run and Validation Protocol

For high-stakes operations like bulk sending, the CLI supports a --dry-run flag. This protocol allows agents to validate complex JSON payloads or React Email templates without executing an actual API call.

Dry-Run Implementation

The CLI serializes the internal request object and returns it to stdout. It provides a dryRun: true key in the JSON response to confirm no action was taken.

// Example dry-run serialization for email attachments
function serializeEmailPayloadForDryRun(payload) {
  const { attachments, ...rest } = payload;
  if (!attachments?.length) return rest;
  return {
    ...rest,
    attachments: attachments.map((a) => ({
      filename: a.filename,
      contentType: a.contentType,
      byteLength: a.content.byteLength // Content is not returned, only size
    })),
  };
}

Sources: src/commands/emails/send.ts:13-33, tests/commands/emails/batch.test.ts:442-455

Command Error Codes

Agents should programmatically handle specific error codes returned in the JSON error object.

Error Code	Context	Mitigation
auth_error	Missing or invalid API key	Verify RESEND_API_KEY environment variable
missing_id	Positional ID argument missing	Provide the required resource ID
missing_body	Email/Template content missing	Provide --html, --text, or --react-email
invalid_options	Mutually exclusive flags used	Remove conflicting flags (e.g., --html with --template)
file_read_error	File path is unreachable	Check local file permissions and paths
apply_error	Career application rejected	Check API validation messages in error response

Sources: src/commands/careers/apply.ts:55-70, src/commands/emails/send.ts:90-110

Automation Patterns

CI/CD Integration

Agents operating in CI/CD environments (like GitHub Actions) use the CLI by injecting secrets into the environment. The CLI's silent mode ensures logs remain clean and strictly contain the resulting JSON.

# Example agent execution in a script
resend emails send -q \
  --from "agent@example.com" \
  --to "dev@example.com" \
  --subject "Build Notification" \
  --text "Build successful."

Sources: skills/resend-cli/references/workflows.md:275-298, skills/resend-cli/SKILL.md:130-134

Batch Operations

Agents can process up to 100 emails in a single command using the emails batch protocol. This requires a JSON file input. The CLI provides a permissive validation mode allowing partial successes, which agents can parse from the errors array in the response.

Sources: tests/commands/emails/batch.test.ts:404-430, skills/resend-cli/references/workflows.md:67-80

The AI Agent Protocol within resend-cli prioritizes machine-readable output and strict environment safety, enabling developers to build reliable automated email and infrastructure management systems.