CLI

Overview

The Email Preview CLI lets you check Gmail compatibility from your terminal. It supports both HTML and React Email (TSX) input, and outputs results in human-readable or JSON format.

AI Agent Compatible

The CLI is designed to work with AI coding assistants and CI/CD pipelines. Use the --json flag for structured output that agents can parse and act on.

Installation

Install the CLI globally using npm, pnpm, or yarn:

npm install -g @felipefreitag/email-preview

pnpm add -g @felipefreitag/email-preview

yarn global add @felipefreitag/email-preview

Commands & Flags

The main command is email-preview. All flags are optional.

-f, --file <path>

Read email content from a file. Supports .html and .tsx files.

--stdin

Treat the positional argument as email content instead of a file path.

--json

Output results as JSON. Ideal for AI agents and CI/CD pipelines.

-h, --help

Show help message and exit.

-v, --version

Show version number and exit.

Input Methods

The CLI accepts input in several ways, checked in priority order:

1File via --file flag
```
email-preview --file ./email.html
```

2Content via --stdin

email-preview --stdin "<html>...</html>"

3Positional argument (file path)
```
email-preview ./email.tsx
```
4Piped stdin
```
cat email.html | email-preview
```

Exit Codes

The CLI uses exit codes to indicate the result, making it easy to use in scripts and CI/CD:

Success (OK or Warning)

No issues found, or only warnings that don't block the email.

Error (Issues Found)

The email has compatibility issues that need attention.

Failure (CLI Error)

CLI errors like file not found, invalid input, or network issues.

Output Examples

Human-readable output

⚠ Gmail Compatibility: WARNING

Some styles may not render as expected in Gmail.

Issues:
  • CSS Properties (3×): position, display, flex
    → https://www.caniemail.com/features/css-position/

Suggestion: Consider using table-based layouts instead of flexbox.

JSON output (--json)

{
  "verdict": "warning",
  "exitCode": 0,
  "assessment": {
    "impact": "Some styles may not render as expected",
    "suggestion": "Consider using table-based layouts",
    "changes": []
  },
  "issues": [
    {
      "id": "css-properties",
      "feature": "CSS Properties",
      "severity": "warning",
      "impact": "filtered",
      "details": {
        "count": 3,
        "items": [
          { "name": "position", "url": "https://www.caniemail.com/..." }
        ]
      }
    }
  ],
  "inputWarnings": [],
  "compilationWarnings": []
}

AI Agent Integration

The CLI is designed to work seamlessly with AI coding assistants like Claude, Cursor, or GitHub Copilot. Here's how to integrate it into your workflow.

Using --json for structured output

The --json flag outputs machine-readable JSON that agents can parse and act on:

email-preview --file email.tsx --json

Exit codes for automation

Use exit codes to determine the next action in scripts:

email-preview --file email.html --json
if [ $? -eq 0 ]; then
  echo "Email is Gmail-compatible"
else
  echo "Issues found - check output"
fi

JSON schema for agents

The JSON output follows a consistent schema that agents can rely on:

verdict — "ok" | "warning" | "error"
exitCode — 0, 1, or 2
assessment — Human-readable summary with impact and suggestions
issues[] — Array of compatibility issues with id, feature, severity, impact, and details (count, items)
inputWarnings[] — Warnings about the input itself
compilationWarnings[] — TSX compilation warnings (if applicable)

CLI