@letterapp/cli 0.1.0 → 0.2.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,157 @@ 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 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`).
 4. It detects your package manager and installs `@letterapp/node`.
 
-## Options
+The API key is never printed to the terminal or chat.
+
+---
+
+## 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
+# Point the CLI at a self-hosted / local Letter instance.
+letter config set base-url http://localhost:3001
+
+# Show current configuration.
+letter config get
+
+# Reset to defaults.
+letter config reset
+```
+
+---
+
+## 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) | Overrides the stored key (CI). |
+| `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
+```
+
+---
 
 ## Roadmap
 
-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:
+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.
+- [`@letterapp/node`](https://www.npmjs.com/package/@letterapp/node) — Node.js SDK.
+
+---
+
+## Links
+
+- **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