@letterapp/cli 0.2.0 → 0.3.2

package/README.md

@@ -26,7 +26,14 @@ 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:
+Point your agent at the [agent setup guide](https://letter.app/docs/agent-setup):
+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:
 
 ```json
 {
@@ -52,10 +59,12 @@ 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 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`.
 
-The API key is never printed to the terminal or chat.
+Neither secret is printed to the terminal or chat. You never pass a token by hand: each command picks the right credential automatically.
 
 ---
 
@@ -99,8 +108,8 @@ letter auth logout
 ### Config
 
 ```bash
-# Point the CLI at a self-hosted / local Letter instance.
-letter config set base-url http://localhost:3001
+# 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
@@ -109,6 +118,42 @@ letter config get
 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
@@ -127,7 +172,9 @@ letter --json status | jq '.events'
 
 | Variable | Default | Purpose |
 | --- | --- | --- |
-| `LETTER_API_KEY` | (from credential store) | Overrides the stored key (CI). |
+| `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. |
 
 ---
@@ -174,18 +221,6 @@ node dist/index.js --help
 
 ---
 
-## Roadmap
-
-v1 ships the secure setup/login flow plus connection helpers. The command
-structure is built to extend: future authenticated areas register the same way
-and reuse the credential store + API client, for example:
-
-- `letter sequences` — list / create / configure automation sequences
-- `letter broadcast` — create and send broadcasts
-- `letter contacts`, `letter events`, `letter keys`
-
----
-
 ## See Also
 
 - [`@letterapp/mcp`](https://www.npmjs.com/package/@letterapp/mcp) — MCP server for AI agents.