Output Formatting & Pagination

Relevant source files

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

• src/lib/table.ts
• src/lib/help-text.ts
• src/lib/actions.ts
• src/commands/emails/send.ts
• skills/resend-cli/SKILL.md
• tests/lib/output.test.ts
• tests/lib/safe-terminal-text.test.ts

Output Formatting & Pagination governs how the Resend CLI presents data to users across different environments. The system automatically detects whether the output destination is a terminal (TTY) or a pipe/script (non-TTY) to choose between human-readable tables and machine-parseable JSON.

The CLI prioritizes clear terminal presentation for interactive users while providing a strict JSON contract for automation agents. It uses specific utilities to sanitize data, render responsive tables, and standardize help documentation.

Output Modes & Detection

The CLI implements an "Agent Protocol" that auto-detects non-TTY environments. It switches to JSON output automatically if stdout is piped or if the --json flag is provided.

Interactive vs. Non-Interactive Logic

• Non-interactive mode: The CLI outputs raw JSON to stdout for successful operations and to stderr for errors. It suppresses all spinners and status messages.
• Interactive mode: The CLI provides human-readable text, spinners for long-running operations, and formatted tables for list data.

Global Output Options

The CLI provides standardized global flags to control output behavior regardless of the environment.

Flag	Effect
--json	Forces JSON output even in interactive terminals.
-q, --quiet	Suppresses spinners and status messages; implies --json.
-p, --profile	Selects a specific authentication profile for the request.

Sources: src/lib/help-text.ts:9-13, skills/resend-cli/SKILL.md:89-93

Table Rendering & Adaptive Layouts

The renderTable utility in src/lib/table.ts handles the display of collection data (like domain lists or contact logs). It dynamically adjusts its format based on the available terminal width.

Adaptive Layout Logic

1. Table Layout: Used when the data fits within the terminal width. It uses box-drawing characters to create a grid.
2. Card Layout: Used when the total width of the columns exceeds the terminal width. It transforms each row into a vertical "card" to prevent horizontal scrolling or text wrapping issues.

Border Character Sets

The CLI detects Unicode support to provide the best possible visual experience.

Character Type	Unicode (Supported)	ASCII (Fallback)
Horizontal	─	-
Vertical	│	|
Corners	┌ ┐ └ ┘	+

Sources: src/lib/table.ts:5-29

Help Text & Error Standardization

Every command utilizes a centralized buildHelpText function to ensure consistency in documentation and error reporting.

Help Structure

The help output is divided into logical sections:

1. Context: Description of the command and specific non-interactive requirements.
2. Global Options: Standard flags like --api-key and --json.
3. Output: An example of the JSON schema returned by the command.
4. Errors: A list of possible error codes (e.g., auth_error, send_error) and the standard error envelope.
5. Examples: Practical command-line usage patterns.

Sources: src/lib/help-text.ts:25-41, tests/lib/help-text.test.ts:7-36

Standard Error Envelope

Errors in JSON mode follow a fixed structure to simplify parsing for external tools.

{
  "error": {
    "message": "<message>",
    "code": "<code>"
  }
}

Sources: src/lib/help-text.ts:21, skills/resend-cli/SKILL.md:71-74

Data Sanitization & Safety

Before data is rendered to a terminal, the CLI passes it through sanitization layers to prevent terminal escape sequence injection and handle untrusted third-party data.

safeTerminalText

The safeTerminalText utility performs the following actions:

• Strips ANSI escape sequences that could manipulate terminal colors or cursor positions.
• Removes OSC hyperlink sequences and title-setting sequences.
• Filters NUL and C0 control characters (except tabs and newlines).
• Prevents bare carriage returns from overwriting terminal lines.

deepSanitize

Commands that fetch data (like emails get or logs list) use deepSanitize to recursively clean entire object trees before they are passed to the interactive rendering logic.

Pagination and Limits

While full cursor-based pagination is managed by the Resend API, the CLI exposes flags to control result sets. The list commands typically support a --limit flag to restrict the number of items returned.

• Common Mistake: Expecting full details in list commands. List outputs are summaries; you must use get <id> for full resource bodies.
• Default Behavior: Inbound email listening (emails receiving listen) and log streaming often default to specific intervals or limits if not specified.

Sources: skills/resend-cli/SKILL.md:98-100, skills/resend-cli/SKILL.md:270-272

Summary: The Output Formatting system ensures that the Resend CLI is both a user-friendly terminal tool and a reliable automation component. It achieves this through automatic TTY detection, adaptive table rendering, standardized help generation, and rigorous data sanitization.