@emailens/cli 0.6.0 → 0.8.0

package/README.md

@@ -5,7 +5,7 @@
   <img src="./docs/wordmark-light.svg" alt="emailens / cli" width="444">
 </picture>
 
-**The rendering linter for email, in your terminal**
+**The email rendering linter for terminal and CI**
 
 [![CI](https://github.com/emailens/cli/actions/workflows/ci.yml/badge.svg)](https://github.com/emailens/cli/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/@emailens/cli)](https://www.npmjs.com/package/@emailens/cli)
@@ -14,15 +14,40 @@
 
 </div>
 
-CLI tool for email compatibility analysis; preview how your emails render across 21 email clients (Gmail, Outlook, Apple Mail, Yahoo, Samsung, Thunderbird, HEY, Proton Mail, AOL, Fastmail, Superhuman).
+Your email looks perfect in Apple Mail. Gmail strips half the CSS. Outlook renders it in Word.
 
-Point it at **HTML, MJML, Maizzle or React Email**. The format is detected from the file extension, the template is compiled with your project's own compiler, and what gets linted is the HTML your readers actually receive.
+`@emailens/cli` checks HTML, React Email, MJML, and Maizzle against real client behavior across 21 email clients. It flags compatibility issues before they ship, in your terminal, in CI, or in your AI workflow.
 
-Across the 255 CSS and HTML features we track, only 6 are fully supported in every major client ([see the data](https://emailens.dev/email-css/report)). This tool catches the other 249 before your users do.
+The quickest way to try it:
 
-![emailens lint output showing errors and warnings across email clients](./docs/lint-demo.png)
+```bash
+npx @emailens/cli lint email.html
+```
+
+If you want a hosted preview, screenshots, and team workflows, see [emailens.dev](https://emailens.dev).
+
+## Why Emailens
+
+Email clients are the hardest frontend target in existence. Every client has different CSS support, different rendering engines, and different failure modes.
+
+Emailens gives you:
+
+- per-client compatibility scoring across 21 clients
+- file:line reporting for HTML inputs
+- CI-safe exit codes for build pipelines
+- support for React Email, MJML, Maizzle, and raw HTML
+- local/offline usage with no account required
+
+## The ecosystem
 
-> **Prefer AI?** Use the [MCP server](https://github.com/emailens/mcp); same engine, works with Claude, Cursor, and any MCP client.
+| Project | Purpose | Start here |
+|---|---|---|
+| [@emailens/engine](https://github.com/emailens/engine) | Core analysis engine and library API | If you want to build on top of it |
+| [@emailens/cli](https://github.com/emailens/cli) | Terminal linting and CI checks | Best first stop |
+| [@emailens/mcp](https://github.com/emailens/mcp) | Claude/Cursor/AI agent integration | If you want AI-assisted email QA |
+| [emailens/action](https://github.com/emailens/action) | GitHub Action quality gate | If you want PR blocking |
+| [emailens/vscode](https://github.com/emailens/vscode) | VS Code linting and preview | If you want editor feedback |
+| [emailens.dev](https://emailens.dev) | Hosted previews, screenshots, team workflows | If you want team-grade QA and shareable reports |
 
 ## Install
 
@@ -30,35 +55,80 @@ Across the 255 CSS and HTML features we track, only 6 are fully supported in eve
 npm install -g @emailens/cli
 ```
 
-Or use with npx:
+Or use it without installing:
 
 ```bash
-npx @emailens/cli analyze email.html
+npx @emailens/cli lint email.html
 ```
 
-## Commands
+Maizzle HTML needs `@maizzle/framework@5` installed beside the CLI. A `.vue` file needs `@maizzle/framework@6`. One install is one major.
 
-### `emailens analyze <file>`
+## Quick start
 
-Analyze CSS compatibility and get per-client scores.
+### Check a single file
 
 ```bash
 emailens analyze email.html
 emailens analyze email.html --clients gmail-web,outlook-windows
 emailens analyze email.html --json
-cat email.html | emailens analyze -
 ```
 
-Warnings show where the property is used, and how many other places share the
-problem:
+### Lint in CI
 
+```bash
+npx @emailens/cli lint 'emails/**/*.{html,tsx,mjml}' --fail-on-warning
 ```
-  ⚠ Outlook (New) (1 issue)
-    ⚠ border-radius (4:8 +2 more): Outlook (New) does not support "border-radius".
+
+### Preview a render
+
+```bash
+emailens preview email.html
+emailens preview email.html --dark-mode
+emailens preview email.html --screenshots --out ./screenshots
+```
+
+### Fix common issues
+
+```bash
+emailens fix email.html
+emailens fix email.html -o fixed.html
+```
+
+## What the output looks like
+
+```text
+src/emails/welcome.html
+  error  12:8  outlook-windows     border-radius     Not supported in Outlook Windows
+  warn          spam               caps-ratio        20%+ of words are ALL CAPS
+
+2 files | 1 error | 1 warning
 ```
 
-`--json` carries the full `loc` / `locs` for each warning. As with `lint`,
-positions are reported for HTML input only, see below.
+This is intentionally readable in a terminal and structured enough for CI, editors, and agents.
+
+## Supported formats
+
+Point it at:
+
+- HTML
+- JSX / React Email
+- MJML
+- Maizzle
+
+Format is detected from the file extension, and the CLI compiles your template before it analyzes the actual HTML that would be sent.
+
+## Commands
+
+### `emailens analyze <file>`
+
+Analyze CSS compatibility and get per-client scores.
+
+```bash
+emailens analyze email.html
+emailens analyze email.html --clients gmail-web,outlook-windows
+emailens analyze email.html --json
+cat email.html | emailens analyze -
+```
 
 ### `emailens preview <file>`
 
@@ -78,93 +148,47 @@ Export a self-contained HTML or JSON report.
 ```bash
 emailens export email.html -o ./report
 emailens export email.html --json -o ./report
-emailens export email.html --dark-mode --screenshots -o ./report
-```
-
-### `emailens fix <file>`
-
-Generate AI-powered fixes for email compatibility issues. Uses `@emailens/engine` analysis to build a structured prompt, then calls Claude to fix structural issues (table layouts, VML, MSO conditionals) that static snippets can't handle.
-
-Requires `ANTHROPIC_API_KEY` environment variable and the optional `@anthropic-ai/sdk` dependency.
-
-```bash
-emailens fix email.html                           # Fix and print to stdout
-emailens fix email.html -o fixed.html             # Write to file
-emailens fix email.html --estimate                 # Show token estimate only (no AI call)
-emailens fix email.html --clients outlook-windows  # Scope to one client
-emailens fix email.html --json                     # Full JSON output with metadata
-emailens fix email.html --max-tokens 8000          # Limit prompt size
-cat email.html | emailens fix - --format jsx       # Pipe from stdin
 ```
 
-| Flag | Alias | Description |
-|------|-------|-------------|
-| `--format` | `-f` | Input format: `html`, `jsx`, `mjml`, `maizzle` |
-| `--clients` | `-c` | Comma-separated client IDs to scope the fix |
-| `--output` | `-o` | Write fixed code to file instead of stdout |
-| `--json` | | Output as JSON (includes token estimates and metadata) |
-| `--quiet` | `-q` | Suppress spinners and decorations |
-| `--estimate` | | Only show token estimate without calling the AI |
-| `--max-tokens` | | Maximum input tokens for the prompt (default: 16000) |
-
 ### `emailens lint <file|glob>`
 
-CI/CD-friendly linting with structured exit codes. Flattens all audit checks (compatibility, content hygiene, links, accessibility, images, inbox preview, size, template variables, content overflow, visual bugs, dark-mode and mobile contrast, design consistency) into a unified issue list.
+CI-friendly linting with structured exit codes.
 
 ```bash
 emailens lint email.html
 emailens lint src/*.html
 emailens lint email.html --json
 emailens lint email.html --fail-on-warning
-emailens lint email.html --skip spam,links
 emailens lint email.html --max-warnings 5
 ```
 
 | Flag | Alias | Description |
 |------|-------|-------------|
-| `--format` | `-f` | Input format: `html`, `jsx`, `mjml`, `maizzle` |
+| `--format` | `-f` | Input format: `html`, `jsx`, `mjml`, `maizzle`. `.vue` is `maizzle`. A pasted Vue file with no flag is detected. |
 | `--json` | | Output as JSON |
 | `--fail-on-warning` | | Exit 2 if warnings found |
-| `--skip` | | Comma-separated checks to skip: `spam,links,accessibility,images,compatibility,inboxPreview,size,templateVariables,overflow,visual,darkContrast,mobileContrast,design` |
+| `--skip` | | Comma-separated checks to skip: `spam,links,accessibility,images,compatibility,inboxPreview,size,templateVariables,overflow,visual,darkContrast,mobileContrast,design,vml,styleSurvival,targeting` |
+| `--targeting-policy` | | `progressive` (default), `strict`, or `lenient` |
 | `--max-warnings` | | Fail if more than n warnings |
 
-**Exit codes:**
+Exit codes:
+
 - `0`: clean
 - `1`: errors found
 - `2`: warnings only (with `--fail-on-warning` or `--max-warnings` exceeded)
 
-**Output format:**
-
-```
-src/emails/welcome.html
-  error  12:8  outlook-windows     border-radius           Not supported in Outlook Windows
-  warn         spam                caps-ratio              20%+ of words are ALL CAPS
+### `emailens clients`
 
-src/emails/newsletter.html
-  pass   No issues found
+List all 21 supported clients.
 
-2 files | 1 error | 1 warning
+```bash
+emailens clients
+emailens clients --json
 ```
 
-Issues that belong to a specific place in the file carry a `line:col`; findings
-about the document as a whole (spam signals, Gmail clipping, inbox preview) have
-no position and leave the column blank. With `--json`, each issue carries a
-`loc` object instead (`line`, `column`, `endLine`, `endColumn`, `offset`,
-`length`) for editors, annotations, and agents that need to point at or edit
-the exact source.
-
-One property can break in many places, so CSS issues also carry `locs`: every
-occurrence in document order, with `loc` as the first, and `locsTruncated: true`
-when there were more than 100.
-
-Positions are reported for **HTML sources only**. JSX, MJML and Maizzle are
-compiled before analysis, so a line number would refer to generated output
-rather than the file you wrote; the CLI omits it rather than print one that
-looks authoritative and isn't.
+## GitHub Actions
 
-#### CI / GitHub Actions
-
-Drop this into `.github/workflows/email-lint.yml` to fail PRs that introduce broken email CSS, spam triggers, or accessibility regressions:
+Add a PR gate to fail builds when email regressions appear:
 
 ```yaml
 name: Email lint
@@ -187,125 +211,25 @@ jobs:
         run: npx -y @emailens/cli lint 'emails/**/*.{html,tsx,mjml}' --fail-on-warning
 ```
 
-For React Email / MJML / Maizzle source files, the CLI auto-detects the format from the extension. Want full preview reports (with screenshots and shareable links) on every PR? Use the [Emailens GitHub Action](https://github.com/marketplace/actions/emailens-email-preview-check) instead; it wraps the same engine.
-
-### `.emailensrc`
-
-The project file the [VS Code extension](https://github.com/emailens/vscode)
-already reads, so the editor and CI agree about what matters. Put it at the
-repo root, or use an `emailens` key in `package.json`:
-
-```json
-{
-  "skip": ["spam"],
-  "rules": {
-    "border-radius": "error",
-    "font-size": "off"
-  }
-}
-```
-
-**`rules`** sets the severity of one rule, keyed by the code `lint` prints: a
-CSS property (`border-radius`) or a rule id (`insecure-link`). `off` drops it
-entirely. Promoting a rule to `error` makes it exit 1, which is the point:
-without this the only control is `--skip`, and a team that cares about one
-Outlook property has to keep the whole compatibility check at warning level.
-
-A rule demoted in the editor that still fails the build is the worst of both
-worlds, and this is the file that stops that happening.
+## AI and MCP
 
-**Precedence.** A command-line flag wins over the file; it is an explicit
-choice for one invocation. In the editor it is the other way round: the repo's
-file wins over personal settings, because those are ambient and the file is
-the team's.
-
-A malformed file is linted without rather than fatal. A severity that is not
-one of `error`, `warning`, `info`, `off` is named on stderr and ignored, so a
-typo cannot quietly leave a rule on that you believe is off. Warnings go to
-stderr, so `lint --json | jq` stays parseable.
-
-### `emailens clients`
-
-List all 21 supported email clients.
+Prefer AI? Use the [MCP server](https://github.com/emailens/mcp). It gives your coding agent access to the same analysis engine and lets it preview, audit, fix, and diff email templates.
 
 ```bash
-emailens clients
-emailens clients --json
+claude mcp add emailens -- npx -y @emailens/mcp
 ```
 
-## Options
-
-All file-processing commands share:
+## Why not just use the hosted app?
 
-| Flag | Alias | Description |
-|------|-------|-------------|
-| `--format` | `-f` | Input format: `html`, `jsx`, `mjml`, `maizzle` |
-| `--clients` | `-c` | Comma-separated client IDs to filter |
-| `--json` | | Output JSON instead of terminal table |
-| `--quiet` | `-q` | Suppress spinners and decorations |
+You can. But the open-source tools are what let developers:
 
-Preview and export add:
+- validate before a push
+- fail CI before a broken email ships
+- run audits offline
+- keep email QA in their editor and terminal
+- build local automation without signing up for a platform
 
-| Flag | Alias | Description |
-|------|-------|-------------|
-| `--dark-mode` | `-d` | Include dark mode simulation |
-| `--screenshots` | | Capture screenshots (requires `BROWSERLESS_URL`) |
-| `--out` | `-o` | Output directory |
-
-## AI Fixes
-
-The `fix` command requires an `ANTHROPIC_API_KEY` environment variable and the `@anthropic-ai/sdk` package:
-
-```bash
-npm install @anthropic-ai/sdk
-export ANTHROPIC_API_KEY=sk-ant-...
-```
-
-Use `--estimate` to check token usage before making an API call:
-
-```bash
-emailens fix email.html --estimate
-#   Input tokens:    ~4,200
-#   Output tokens:   ~5,400
-#   Warnings:        23 (5 structural)
-```
-
-## Framework Support
-
-The CLI can compile React Email (JSX/TSX), MJML, and Maizzle templates to HTML before analysis. Format is auto-detected from file extension, or specify with `--format`.
-
-```bash
-emailens analyze newsletter.tsx              # Auto-detected as JSX
-emailens analyze template.mjml               # Auto-detected as MJML
-emailens preview email.html --format maizzle # Explicit format
-```
-
-Framework compilers are optional peer dependencies; install only what you need:
-
-```bash
-npm install sucrase react @react-email/components @react-email/render  # For JSX
-npm install mjml                                                        # For MJML
-npm install @maizzle/framework                                          # For Maizzle
-```
-
-## Screenshots
-
-Screenshots require a [Browserless](https://www.browserless.io/) instance and `playwright-core`:
-
-```bash
-npm install playwright-core
-export BROWSERLESS_URL=ws://localhost:3000
-emailens preview email.html --screenshots --out ./screenshots
-```
-
-## Piping
-
-Read from stdin with `-`:
-
-```bash
-cat email.html | emailens analyze -
-echo '<html><body>Hello</body></html>' | emailens preview - --json
-```
+The hosted SaaS adds screenshot previews, shared reports, and team workflows. The OSS tools give you the developer-first layer.
 
 ## License
 
@@ -314,3 +238,4 @@ MIT
 ---
 
 If this saved you from an Outlook surprise, [a star](https://github.com/emailens/cli) helps other email developers find it.
+