@animaapp/cli 0.2.1 → 0.3.2

package/README.md

@@ -1,132 +1,301 @@
 # @animaapp/cli
 
-CLI for generating production-ready apps from prompts, URLs, or Figma designs.
+Generate production-ready apps from prompts, URLs, or Figma designs — from the
+command line.
 
-Works with any AI coding tool that can run shell commands — no MCP setup, no plugins, just `npx`.
+Built for **agents**: any AI tool that can run a shell command can use it. No MCP
+server to configure, no plugins — just `npx`. (Under the hood every command talks
+to Anima over MCP; you don't have to set any of that up.)
 
-## Quick Start
+```bash
+npx @animaapp/cli login
+npx @animaapp/cli create -t p2c -p "SaaS dashboard with sidebar and analytics"
+```
+
+> Examples use `npx @animaapp/cli <command>`. If you install the package globally
+> (`npm i -g @animaapp/cli`), the same commands are available as `anima <command>` —
+> the shorthand used in prose below.
+
+---
+
+## Connecting an agent
+
+Every command runs as a **scoped agent identity**: it acts only within the
+workspaces and capabilities a human approved, your team can see and **revoke** it
+at any time, and it expires after ~7 days. You get that identity one of two ways.
+
+### 1. Device login — `anima login`
+
+The machine running the CLI needs **no browser and no human sitting at it**. The
+command prints a short code and a verification URL; a human opens that URL on
+_any_ device, picks the workspaces/capabilities, names the agent, and approves.
+The CLI polls until approval lands, then stores the token at
+`~/.config/anima/credentials.json`.
+
+Re-running `anima login` with the **same agent name** reconnects to the same
+identity (renewal is just logging in again).
+
+**Interactive agent (Claude Code, Cursor, a dev at a terminal):**
 
 ```bash
-# One-time: save your tokens
-npx @animaapp/cli auth --token <anima-token>
-npx @animaapp/cli auth --figma-token <figma-token>
+npx @animaapp/cli login
+```
 
-# Create an app from a prompt
-npx @animaapp/cli create -t p2c -p "SaaS dashboard with sidebar and analytics"
+In a terminal it also tries to open the verification page for you (disable with
+`--no-open`).
 
-# Clone a website
-npx @animaapp/cli create -t l2c -u https://stripe.com
+**Headless agent with a human it can reach (chat, PR, logs):** run in JSON mode
+and relay the verification step. The CLI emits a `verification_required` event to
+**stderr** so your agent can surface it to its human while stdout stays clean:
 
-# Convert Figma to code
-npx @animaapp/cli codegen --file-key <figma-url> -o ./components
+```bash
+npx @animaapp/cli login --json
+# stderr:
+# {"event":"verification_required","verificationUri":"https://.../device",
+#  "verificationUriComplete":"https://.../device?user_code=ABCD-1234",
+#  "userCode":"ABCD-1234","expiresIn":900}
+```
 
-# Publish to a live URL
-npx @animaapp/cli publish <sessionId>
+The agent shows the human the URL + code, the human approves, and the same
+process resolves with the final `{ "success": true, "tokenType": "agent", ... }`
+on stdout.
+
+### 2. Pre-issued token — `ANIMA_API_TOKEN`
+
+For CI or a fully headless agent with **no human in the loop**, skip login and
+provide a token directly:
+
+```bash
+export ANIMA_API_TOKEN=<agent-or-personal-token>
+export ANIMA_TEAM_ID=<team-id>        # optional
+export FIGMA_TOKEN=<token>            # only for codegen / f2c
 ```
 
-## Authentication
+Resolution priority: `ANIMA_API_TOKEN` env var → stored credentials file → error.
+
+### Which do I use?
+
+| Situation | How to connect |
+|-----------|----------------|
+| Human at a dev machine | `anima login` (browser opens) |
+| Interactive agent, human nearby | `anima login` — show the URL + code, human approves on any device |
+| Headless agent, human reachable | `anima login --json` — relay the `verification_required` event, polling finishes automatically |
+| Fully headless / CI, no human | set `ANIMA_API_TOKEN` — no login step |
 
-Get your Anima API token at [dev.animaapp.com](https://dev.animaapp.com) > Settings > API Keys.
+---
+
+## Quick start
 
 ```bash
-# Store tokens (persisted to ~/.config/anima/credentials.json)
-npx @animaapp/cli auth --token <anima-token>
-npx @animaapp/cli auth --figma-token <figma-token>
+# 1. Connect (once)
+npx @animaapp/cli login
 
-# Or use environment variables
-export ANIMA_API_TOKEN=<token>
-export FIGMA_TOKEN=<token>
+# 2. Create from a prompt / URL / Figma
+npx @animaapp/cli create -t p2c -p "E-commerce product page with cart"
+npx @animaapp/cli create -t l2c -u https://linear.app
+npx @animaapp/cli create -t f2c --file-key <key> --nodes 42:15
+
+# 3. Publish, edit over git, or generate raw files
+npx @animaapp/cli publish <sessionId>
+npx @animaapp/cli get-git-token https://dev.animaapp.com/chat/<sessionId>   # then: git clone <url>
+npx @animaapp/cli codegen --file-key <key> --nodes 42:15 -o ./components
 ```
 
-Priority: env var > stored credentials file.
+---
 
 ## Commands
 
-### `create` — Generate a playground (3-7 min)
+### `login` — connect this machine
 
 ```bash
-# Prompt to Code
-npx @animaapp/cli create -t p2c -p "E-commerce product page with cart"
+npx @animaapp/cli login
+npx @animaapp/cli login --client-name "My CI Agent"   # label on the consent screen
+npx @animaapp/cli login --no-open                      # don't auto-open the browser
+npx @animaapp/cli login --print-mcp-config             # also emit an MCP server config
+```
 
-# Link to Code (clone a website)
-npx @animaapp/cli create -t l2c -u https://linear.app
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--client-name <name>` | How the CLI appears on the consent screen | `Anima CLI` |
+| `--no-open` | Don't try to open the verification page in a browser | — |
+| `--print-mcp-config` | One-shot: after this fresh login, also print the MCP server config. If you are already logged in, use `mcp-config` instead — this flag always starts a new login | off |
+
+### `mcp-config` — print your MCP server config (no new login)
+
+```bash
+npx @animaapp/cli mcp-config
+```
+
+Prints a ready-to-paste remote MCP server entry (points at `/v1/mcp` with a
+bearer header) **from your stored credentials** — no network call, no device
+flow. Errors with "run `anima login`" if you are not logged in or the token
+expired. `--json` wraps it as `{ success, mcpConfig, expiresAt }`.
+
+**MCP-capable agents:** `login` once, then `mcp-config`. Configure the printed
+entry and use native MCP tools directly — no CLI in the loop. The token is
+scoped and expires in ~7 days; on auth errors run `login` again, then
+`mcp-config` again. The token is never printed by plain `login --json` — only
+by `mcp-config` and `--print-mcp-config`.
 
-# Figma to Code
+### `create` — generate a playground (3–7 min)
+
+```bash
+npx @animaapp/cli create -t p2c -p "Analytics dashboard with a sidebar"
+npx @animaapp/cli create -t l2c -u https://stripe.com
 npx @animaapp/cli create -t f2c --file-key <key> --nodes 42:15
 ```
 
-**Options** (all optional with sensible defaults):
+| Option | Values | Default |
+|--------|--------|---------|
+| `-t, --type` | `p2c` (prompt), `l2c` (URL), `f2c` (Figma) | _required_ |
+| `-p, --prompt` | free text | _(p2c)_ |
+| `-u, --url` | website URL | _(l2c)_ |
+| `--file-key` | Figma file key or URL | _(f2c)_ |
+| `--nodes` | Figma node IDs, comma-separated | _(f2c)_ |
+| `--figma-token` | Figma PAT (or `FIGMA_TOKEN` env) | _(f2c)_ |
+| `--framework` | `react`, `html` | `react` |
+| `--styling` | `tailwind`, `css`, `plain_css`, `css_modules`, `inline_styles`¹ | `tailwind` |
+| `--language` | `typescript`, `javascript` | `typescript` (react) |
+| `--ui-library` | `shadcn`, `mui`, `antd`, `clean_react` | _(none)_ |
+| `--guidelines` | free text | _(p2c only)_ |
+
+¹ The valid styling / UI-library set depends on `--type`; the server validates and
+returns a clear error for unsupported combinations.
+
+### `codegen` — Figma to local files (no playground)
+
+```bash
+npx @animaapp/cli codegen --file-key <key-or-url> --nodes 42:15 -o ./components
+```
 
 | Option | Values | Default |
 |--------|--------|---------|
-| `--framework` | react, html | react |
-| `--styling` | tailwind, css, plain_css, css_modules, inline_styles | tailwind |
-| `--language` | typescript, javascript | typescript (when react) |
-| `--ui-library` | shadcn, mui, antd, clean_react | _(none)_ |
-| `--guidelines` | free text | _(none, p2c only)_ |
+| `--file-key` | Figma file key or URL | _required_ |
+| `--nodes` | Figma node IDs, comma-separated | _(or node id in the URL)_ |
+| `--figma-token` | Figma PAT (or `FIGMA_TOKEN` env) | _required_ |
+| `-o, --output` | output directory | `./generated` |
+| `--framework` | `react`, `html` | `react` |
+| `--styling` | `tailwind`, `plain_css` | `tailwind` |
+| `--language` | `typescript`, `javascript` | `typescript` (react) |
+| `--ui-library` | `shadcn`, `mui`, `antd`, `clean_react` | _(none)_ |
 
-### `publish` — Deploy to live URL (1-3 min)
+### `publish` — deploy a session (1–3 min)
 
 ```bash
 npx @animaapp/cli publish <sessionId>
 npx @animaapp/cli publish <sessionId> --mode designSystem --package-name my-ds
 ```
 
-### `codegen` — Figma to local files
+| Option | Values | Default |
+|--------|--------|---------|
+| `--mode` | `webapp`, `designSystem` | `webapp` |
+| `--package-name` | npm package name | _(designSystem)_ |
+| `--package-version` | npm package version | _(designSystem)_ |
+
+### `get-git-token` — read/edit a playground's code over git
 
 ```bash
-npx @animaapp/cli codegen --file-key <key-or-url> --nodes 42:15 -o ./components
+npx @animaapp/cli get-git-token https://dev.animaapp.com/chat/<sessionId>
 ```
 
-Requires a Figma personal access token (stored via `auth --figma-token` or `FIGMA_TOKEN` env var).
+A playground **is** a git repository, and git is the only way to read or edit
+its code. This command mints a short-lived access token scoped to that one
+playground and prints a ready-to-use remote URL — you run git yourself:
 
-### `download` — Download playground project
+```bash
+git clone <gitRemoteUrl>               # read (and edit locally)
+git push                               # read-write access: updates the live playground
+git remote set-url origin <new url>    # after expiry: re-run get-git-token, re-point the clone
+```
+
+In `--json` mode the output is `{ gitRemoteUrl, access: "ro"|"rw", expiresAt }`.
+The token expires within an hour and cannot be renewed — treat the URL as a
+secret, and re-mint rather than store it.
+
+### `logout` — disconnect this machine
 
 ```bash
-npx @animaapp/cli download https://dev.animaapp.com/chat/<sessionId> -o ./my-project
+npx @animaapp/cli logout
 ```
 
-### `auth` — Manage credentials
+Clears **all** stored credentials (Anima token, Figma token, agent metadata) and
+removes the config directory. This only forgets the token locally — to actually
+disable an agent, revoke it from your team settings.
+
+### `config` — store CLI preferences
+
+Persist non-secret settings to `~/.config/anima/config.json` so you don't have to
+pass flags every time — handy for pointing at a local API during development.
+Kept separate from credentials, so `logout` never touches it.
 
 ```bash
-npx @animaapp/cli auth --token <T>         # Save Anima token
-npx @animaapp/cli auth --figma-token <T>   # Save Figma token
-npx @animaapp/cli auth --status            # Check what's configured
-npx @animaapp/cli auth --logout            # Clear all credentials
+npx @animaapp/cli config set api-url http://localhost:3789
+npx @animaapp/cli config get api-url
+npx @animaapp/cli config list
+npx @animaapp/cli config unset api-url
 ```
 
-## Output Modes
+The API URL resolves in this order: **`--api-url` flag → `ANIMA_API_URL` env →
+`config.json` → default (`https://public-api.animaapp.com`).**
 
-- **Terminal (TTY):** Colored text with spinner and progress
-- **Piped (AI tools):** Single JSON object to stdout
+### `auth` — inspect or manage credentials
+
+```bash
+npx @animaapp/cli auth --status            # token type + expiry
+npx @animaapp/cli auth --figma-token <T>   # save a Figma token for codegen / f2c
+npx @animaapp/cli auth --logout            # alias for `anima logout`
+```
+
+---
+
+## Global flags
+
+Available on the network commands (`login`, `create`, `codegen`, `publish`,
+`get-git-token`):
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--json` | Emit a single JSON object to stdout (for agents) | off (pretty in a TTY) |
+| `--verbose` | Stream progress to stderr in JSON mode¹ | off |
+| `--api-url <url>` | API base URL (point at local/staging)³ | `https://public-api.animaapp.com` |
+| `--log-file <path>` | Append a JSON debug log of each step to a file | off |
+| `--timeout <ms>` | Request timeout² | `600000` (10 min) |
+
+¹ `--verbose` applies to `create` / `codegen` / `publish` / `get-git-token`.
+² `--timeout` applies to `create` / `codegen`. Don't lower it — generation takes
+minutes.
+³ Falls back to `ANIMA_API_URL`, then `anima config set api-url`, then the
+default. Set it once with `config` instead of passing `--api-url` every time.
+
+---
+
+## Output modes
+
+- **Terminal (TTY):** colored text, spinner, elapsed time.
+- **Piped / `--json`:** a single JSON object on **stdout**; progress and the
+  device-flow `verification_required` event go to **stderr**, so stdout is always
+  a clean, parseable result.
 
 ```bash
-# AI tool usage — parse JSON output
 npx @animaapp/cli create -t p2c -p "dashboard" --json 2>/dev/null | jq .playgroundUrl
 ```
 
-Progress is streamed to stderr with `--verbose`.
+---
 
-## Timing
+## Debugging
 
-| Command | Duration |
-|---------|----------|
-| `create` | 3-7 minutes |
-| `publish` | 1-3 minutes |
-| `codegen` | 2-5 minutes |
-| `download` | seconds |
+**`--log-file`** (or the `ANIMA_LOG_FILE` env var) writes one JSON line per step —
+HTTP requests/responses, MCP connect and tool calls, and errors — to a file you
+can inspect or share. Tokens and auth headers are redacted.
 
-The `--timeout` default is 600,000ms (10 min). Do not reduce it.
+```bash
+npx @animaapp/cli login --log-file ./anima-debug.log
+```
 
-## Exit Codes
+**`HTTP 404` on `login`** means the API at `--api-url` doesn't have the device
+grant deployed. Point at an API that does (`--api-url`) or use `ANIMA_API_TOKEN`.
 
-| Code | Meaning |
-|------|---------|
-| 0 | Success |
-| 1 | API error |
-| 2 | Auth error |
-| 3 | Validation error |
-| 4 | Timeout |
+---
 
 ## License