@letterapp/cli 0.1.0 → 0.3.0

package/README.md

@@ -1,11 +1,46 @@
 # @letterapp/cli
 
-Connect your app to [Letter](https://letter.app) in one command. The CLI runs 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.**
+[![npm version](https://img.shields.io/npm/v/@letterapp/cli)](https://www.npmjs.com/package/@letterapp/cli)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green)](./LICENSE)
 
-## Usage
+**Letter CLI** — connect your app to [Letter](https://letter.app) 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:
+
+```bash
+npx @letterapp/cli
+```
+
+Or install globally:
+
+```bash
+npm install -g @letterapp/cli
+letter --version
+```
+
+### For AI Agents
+
+Add the Letter MCP server so your agent can set up and verify the integration with tools instead of shell parsing:
+
+```json
+{
+  "mcpServers": {
+    "letter": { "command": "npx", "args": ["-y", "@letterapp/mcp"] }
+  }
+}
+```
+
+See [`@letterapp/mcp`](https://www.npmjs.com/package/@letterapp/mcp).
+
+---
+
+## Setup
 
 From your project root:
 
@@ -15,41 +50,185 @@ 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.
+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 a project API key and sends it to the CLI over a secure back
-   channel. The CLI writes `LETTER_API_KEY` to `.env.local` and stores a copy in
-   `~/.letter/credentials.json` for tooling (such as `@letterapp/mcp`).
+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`.
 
-## Options
+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
+
+```bash
+# 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). |
-| `--yes`, `-y` | Non-interactive: don't wait for Enter. Useful when an agent runs the command. |
+| `-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
+
+```bash
+# Check whether your project has received any contacts or events yet.
+letter status
+```
+
+### Auth
+
+```bash
+# Show whether this machine is connected, and to which project.
+letter auth status
+
+# Remove the stored credential (~/.letter/credentials.json).
+letter auth logout
+```
+
+### Config
+
+```bash
+# 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>`.
+
+```bash
+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 hi@mail.acme.com --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](https://letter.app/docs/cli) and the
+[Management API](https://letter.app/docs/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:
+
+```bash
+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.
+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
+
+```bash
+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`](https://www.npmjs.com/package/@letterapp/mcp) — MCP server for AI agents.
+- [`@letterapp/node`](https://www.npmjs.com/package/@letterapp/node) — Node.js SDK.
+
+---
 
-## Roadmap
+## Links
 
-v1 ships the setup/login flow. The command registry and credential store are
-built to extend: future versions add authenticated subcommands that reuse the
-same stored credential, for example:
+- **Website:** [letter.app](https://letter.app)
+- **npm:** [@letterapp/cli](https://www.npmjs.com/package/@letterapp/cli)
+- **GitHub:** [vincenzor/letter-cli](https://github.com/vincenzor/letter-cli)
+- **Issues:** [Report a bug](https://github.com/vincenzor/letter-cli/issues)
 
-- `letter sequences` - list / create / configure automation sequences
-- `letter broadcast` - create and send broadcasts
-- `letter contacts`, `letter events`, `letter keys`, `letter status`
+---
 
 ## License