@letterapp/cli

Letter CLI — connect your app to Letter in one command, then manage the connection from the terminal.

Built for AI coding agents (Claude Code, Cursor, Codex, Windsurf, Cline, OpenClaw) and developers alike. The setup flow uses an interactive, secure device login: the API key is provisioned by a browser confirmation and written straight to your project's env file. The key never appears in your shell history, terminal output, or an agent's chat transcript.

Installation

No install needed - run it straight from your project root:

npx @letterapp/cli

Or install globally:

npm install -g @letterapp/cli
letter --version

For AI Agents

Point your agent at the agent setup guide: it runs npx @letterapp/cli (which provisions the key and installs the SDK), then instruments identify / track in your codebase. After login the CLI also prints a ready-to-paste prompt so you can hand the last mile to any agent. The flow is language-agnostic: Node, Python, and Ruby get their SDK, everything else gets HTTP API instructions.

Or add the Letter MCP server so your agent can set up and verify with tools instead of shell parsing:

{
  "mcpServers": {
    "letter": { "command": "npx", "args": ["-y", "@letterapp/mcp"] }
  }
}

See @letterapp/mcp.

Setup

From your project root:

npx @letterapp/cli

What happens:

1. The CLI prints a short confirmation code and (after you press Enter) opens your browser to the Letter dashboard.
2. You confirm the code matches and pick the project to connect.
3. Letter mints two credentials and sends them to the CLI over a secure back channel:
   • a project ingestion key (lt_live_*) written to .env.local as LETTER_API_KEY for the SDK / ingestion API, and
   • a workspace Personal Access Token (lt_pat_*) stored in ~/.letter/credentials.json for the CLI's management commands and @letterapp/mcp.
4. It detects your package manager and installs @letterapp/node.

Neither secret is printed to the terminal or chat. You never pass a token by hand: each command picks the right credential automatically.

Commands

Login

# Interactive device login (default command). `letter` and `letter login`
# and `letter init` are equivalent.
letter
letter login
letter init

| Flag | Description | | --- | --- | | --no-open | Don't auto-open the browser; print the URL to open manually (headless/remote). | | -y, --yes | Non-interactive: don't wait for Enter. Useful when an agent runs the command. | | --no-install | Skip installing @letterapp/node. | | --base-url <url> | Target a self-hosted or local Letter instance. | | --api-key <key> | CI only. Writes the key without the device flow. Do not use interactively or in chat. |

Status

# Check whether your project has received any contacts or events yet.
letter status

Auth

# Show whether this machine is connected, and to which project.
letter auth status

# Remove the stored credential (~/.letter/credentials.json).
letter auth logout

Config

# Set the API origin (defaults to https://api.letter.app).
letter config set base-url https://api.letter.app

# Show current configuration.
letter config get

# Reset to defaults.
letter config reset

Manage your workspace

The same things the dashboard does are available as resource commands, backed by the workspace PAT from letter login. Each group has list / get / create / update / delete plus verb subcommands; run letter <group> --help for the exact flags. Project-scoped groups default to the connected project and accept --project <slug>.

letter me                                  # identity, workspace, role
letter projects list --json
letter contacts list --limit 20
letter segments preview --filter @paid.json
letter sequences draft seq_123 --graph @graph.json --trigger @trigger.json --expected-revision 7
letter sequences publish seq_123
letter broadcasts preflight bc_42
letter broadcasts schedule bc_42 --scheduled-at 2026-06-01T09:00:00Z
letter domains create --domain mail.acme.com
letter sender-identity --from-email [email protected] --from-name "Acme"

Groups: projects, members, invitations, api-keys, contacts, accounts, events, suppressions, segments, sequences, broadcasts, templates, domains, project-tokens, sender-identity, sending-mode, me. Full reference: letter.app/docs/cli and the Management API.

Two credentials, one login

| Purpose | Format | Dashboard | CLI group | Stored as | | --- | --- | --- | --- | --- | | Send events (SDK / ingestion) | lt_live_* | Project tokens | project-tokens | LETTER_API_KEY in .env.local | | Run the CLI / Management API | lt_pat_* | API keys | api-keys | ~/.letter/credentials.json |

(The older group names keys and tokens still work as aliases.)

Output Modes

• Default — human-friendly colored output.
• --json — raw JSON, for scripting and agents:

letter --json auth status
letter --json status | jq '.events'

Environment Variables

| Variable | Default | Purpose | | --- | --- | --- | | LETTER_API_KEY | (from credential store) | Project ingestion key (lt_live_*) for the SDK / letter status. Overrides the stored key (CI). | | LETTER_PAT | (from credential store) | Workspace PAT (lt_pat_*) for management commands. Set it to run them without letter login (CI). | | LETTER_PROJECT | (connected project) | Default project slug for project-scoped management commands. | | LETTER_BASE_URL | https://api.letter.app | API origin for self-host / local dev. |

Security

The interactive flow follows the OAuth 2.0 Device Authorization Grant pattern (gh auth login / vercel login style). The key is minted server-side only after a human approves in the browser, then delivered to the CLI out of band. The CLI confirms success without ever echoing the secret. Treat .env.local and ~/.letter/credentials.json as secrets and keep them out of source control.

Project Structure

src/
├── index.ts            # CLI entry point — Commander program + global flags
├── client.ts           # Device-auth flow + authenticated API client
├── config.ts           # base-url config (conf) + secret credential store
├── output.ts           # Colors, spinners, JSON mode, prompts
├── browser.ts          # Open the confirmation URL
├── env-file.ts         # Upsert keys into .env.local
├── pm.ts               # Detect package manager / framework, install the SDK
└── commands/
    ├── login.ts        # login / init — the device flow (default command)
    ├── auth.ts         # auth status / logout
    ├── status.ts       # status — has data landed?
    └── config.ts       # config set / get / reset
package.json
tsconfig.json
tsup.config.ts

Development

npm install      # install dependencies
npm run build    # bundle to dist/ with tsup
npm run dev      # watch mode
npm run typecheck

node dist/index.js --help

See Also

• @letterapp/mcp — MCP server for AI agents.
• @letterapp/node — Node.js SDK.

Links

• Website: letter.app
• npm: @letterapp/cli
• GitHub: vincenzor/letter-cli
• Issues: Report a bug

License

MIT