@vocoder/cli 0.1.6 → 0.1.8

package/README.md

@@ -1,6 +1,6 @@
 # @vocoder/cli
 
-Command-line tool for Vocoder. Handles project setup and automatic string wrapping for translation.
+Command-line tool for Vocoder. Handles project setup, string extraction, and translation sync.
 
 ## Installation
 
@@ -8,7 +8,7 @@ Command-line tool for Vocoder. Handles project setup and automatic string wrappi
 npm install -g @vocoder/cli
 ```
 
-Or use directly with npx:
+Or use without installing:
 
 ```bash
 npx vocoder <command>
@@ -18,61 +18,167 @@ npx vocoder <command>
 
 ### `vocoder init`
 
-Connect your repository to Vocoder.
+Connect your repository to Vocoder. Runs an interactive TUI that handles authentication, workspace setup, and project configuration — all in the terminal. Only one browser step is required (GitHub authorization), and only on first run.
 
 ```bash
 vocoder init
 ```
 
-The command detects your git remote and checks if a Vocoder project already exists for the repository. If found, it confirms the connection and prints next steps. If not, it opens a browser-based setup flow to create a new project.
+**First-time setup:**
+
+The CLI opens the Vocoder GitHub App installation page. Authorizing the App creates your account and workspace in one step — no separate sign-up required.
+
+```
+┌  Vocoder Setup
+
+◆  Opening GitHub to connect your account...
+│  Authorize Vocoder and install the GitHub App in one step.
+│
+│  https://github.com/apps/vocoder/installations/new?state=...
+│
+◆  Open in your browser? › Yes
+
+◒  Waiting for GitHub authorization...
+
+◇  Connected as @username — workspace: username
+
+◆  App Directory (Optional)
+│  Leave blank to cover the entire repository (or enter a subdirectory for monorepos)
+
+◆  Source language (type to search)
+│  English — en
+
+◆  Target languages (type to search, space to select)
+│  ◼ Spanish — es
+
+◆  Target branches
+│  ◼ main
+
+◒  Creating project...
+
+◆  Step 1: Add the plugin to vite.config.ts
+◆  Step 2: Wrap your app with VocoderProvider
+◆  Step 3: Mark strings for translation with <T>
+
+◆  Use Vocoder with Claude Code
+│  claude mcp add --scope project --transport stdio \
+│    --env VOCODER_API_KEY=vc_xxxx \
+│    vocoder -- npx -y @vocoder/mcp
+
+◇  You're all set.
+```
+
+**Returning user (stored credentials):**
+
+No browser opens. The stored token is verified and the flow continues in the terminal.
+
+```
+┌  Vocoder Setup
+
+◇  Authenticated as user@example.com
+
+◆  Select workspace
+│  ● my-workspace  (3 projects)
+│  ○ + Create new workspace
+```
+
+**Monorepo support:**
+
+When running `vocoder init` from a subdirectory of a git repository, the CLI automatically suggests that subdirectory as the app directory. Each app in a monorepo should be set up as a separate Vocoder project.
 
 **Options:**
 
 | Flag | Description |
 |---|---|
-| `--yes` | Skip confirmation prompts |
-| `--project-name <name>` | Pre-fill project name |
-| `--source-locale <locale>` | Pre-fill source locale |
-| `--target-locales <list>` | Comma-separated target locales (e.g., `es,fr,de`) |
+| `--yes` | Skip the "Open in your browser?" confirmation |
+| `--ci` | Non-interactive mode. Prints `VOCODER_AUTH_URL: <url>` to stdout instead of opening a browser. Intended for CI environments where the browser step is driven externally. |
+
+**Stored credentials:**
 
-### `vocoder wrap`
+After first sign-in, the CLI stores credentials at `~/.config/vocoder/auth.json` (mode `0600`). Tokens do not expire. Use `vocoder logout` to revoke.
 
-Automatically wrap string literals in your source code with `<T>` and `t()`.
+**Token resolution:**
+
+| Command | Source |
+|---|---|
+| `vocoder init` | `VOCODER_AUTH_TOKEN` env var → `~/.config/vocoder/auth.json` |
+| `vocoder sync` | `VOCODER_API_KEY` env var → `.env` file |
+| MCP tools | `VOCODER_API_KEY` env var |
+
+---
+
+### `vocoder sync`
+
+Extract translatable strings from your source code and submit them for translation.
 
 ```bash
-vocoder wrap
+vocoder sync
 ```
 
-Scans your JSX/TSX files for user-facing string literals and wraps them with the appropriate Vocoder translation markers. Uses AST analysis to detect strings that are likely user-facing (not keys, classnames, or internal identifiers).
+Reads `VOCODER_API_KEY` from environment or `.env`. Detects `<T>` and `t()` usages, submits them to Vocoder, and polls until translations are returned. Writes locale JSON files to the configured output path.
 
 **Options:**
 
 | Flag | Description |
 |---|---|
-| `--include <pattern>` | Glob pattern(s) to include (repeatable) |
-| `--exclude <pattern>` | Glob pattern(s) to exclude (repeatable) |
-| `--dry-run` | Preview changes without modifying files |
-| `--interactive` | Confirm each string interactively |
-| `--confidence <level>` | Minimum confidence: `high`, `medium`, `low` (default: `high`) |
-| `--verbose` | Detailed output |
+| `--locale <code>` | Sync only this target locale |
+| `--dry-run` | Show what would be synced without submitting |
+| `--verbose` | Show extraction and sync details |
+
+---
+
+### `vocoder logout`
+
+Revoke the stored credentials and clear `~/.config/vocoder/auth.json`.
+
+```bash
+vocoder logout
+```
+
+The token is also revoked server-side.
 
-## String Extraction
+---
 
-The `wrap` command uses Babel to parse JSX/TSX files and detect strings that are likely user-facing. It distinguishes between:
+### `vocoder whoami`
 
-- JSX text content (wrapped with `<T>`)
-- String props like `placeholder`, `title`, `aria-label` (wrapped with `t()`)
-- Non-translatable strings like class names, keys, and URLs (left alone)
+Print the currently authenticated user.
 
-It tracks imports from `@vocoder/react` to avoid double-wrapping strings that are already marked for translation.
+```bash
+vocoder whoami
+# Authenticated as user@example.com (my-workspace)
+```
+
+---
+
+## How `init` interacts with the browser
+
+`vocoder init` opens exactly one browser window, and only on first run. The browser is used to authorize the Vocoder GitHub App — this simultaneously authenticates you and connects your GitHub account, so no separate sign-up is needed.
+
+Once the GitHub authorization is complete, the browser redirects back and the CLI receives your credentials automatically via a local callback server. The rest of setup happens in the terminal.
+
+On subsequent runs, the stored token is used directly and no browser is needed.
+
+---
 
 ## Git Integration
 
-The CLI auto-detects the repository and branch:
+The CLI auto-detects repository context from the working directory:
+
+- **Repository:** Reads the git remote URL and normalizes it to `github:owner/repo`
+- **Branch:** Checks CI environment variables first (GitHub Actions, Vercel, Netlify, etc.), then falls back to `.git/HEAD`
+- **App directory:** For monorepos, computes the relative path from the git root to `process.cwd()`
+
+---
+
+## Environment Variables
+
+| Variable | Used by | Purpose |
+|---|---|---|
+| `VOCODER_API_KEY` | `sync`, MCP | Project API key (`vc_` prefix) |
+| `VOCODER_AUTH_TOKEN` | `init` | Override stored user token (`vcu_` prefix) |
+| `VOCODER_API_URL` | All commands | Override API base URL (default: `https://vocoder.app`) |
 
-- **Repository:** Reads the git remote URL and normalizes it to a canonical format (`github:owner/repo`)
-- **Branch:** Checks CI environment variables first (GitHub Actions, Vercel, Netlify, etc.), then falls back to reading `.git/HEAD`
-- **Scope path:** For monorepos, computes the relative path from the git root to the working directory
+---
 
 ## License