@animaapp/cli 0.2.0 → 0.3.1

package/README.md

@@ -1,134 +1,291 @@
 # @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:
+
+```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}
+```
 
-# Convert Figma to code
-npx @animaapp/cli codegen --file-key <figma-url> -o ./components
+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.
 
-# Publish to a live URL
-npx @animaapp/cli publish <sessionId>
+### 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` | After login, print an MCP server config (with the token) to paste into an MCP-capable agent | off |
+
+**MCP-capable agents:** use `login` only to obtain the token, then `--print-mcp-config`
+gives you a ready-to-paste remote MCP server entry (points at `/v1/mcp` with a bearer
+header). Configure that and use native MCP tools directly — no CLI in the loop. The token
+is scoped and expires in ~7 days; re-run `login` to refresh it. The token is only printed
+with this flag (never in plain `--json` output).
+
+### `create` — generate a playground (3–7 min)
 
-# Figma to Code
+```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: `--framework` (react|html), `--styling` (tailwind|css|inline_styles), `--language` (typescript|javascript), `--ui-library` (shadcn|mui|antd|clean_react)
+| 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)
 
-### `publish` — Deploy to live URL (1-3 min)
+```bash
+npx @animaapp/cli codegen --file-key <key-or-url> --nodes 42:15 -o ./components
+```
+
+| Option | Values | Default |
+|--------|--------|---------|
+| `--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 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>
+```
+
+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:
+
+```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
 ```
 
-Requires a Figma personal access token (stored via `auth --figma-token` or `FIGMA_TOKEN` env var).
+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.
 
-### `download` — Download playground project
+### `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
-# AI tool usage — parse JSON output
-npx @animaapp/cli create -t p2c -p "dashboard" --json 2>/dev/null | jq .playgroundUrl
+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`
 ```
 
-Progress is streamed to stderr with `--verbose`.
+---
+
+## Global flags
 
-## Timing
+Available on the network commands (`login`, `create`, `codegen`, `publish`,
+`get-git-token`):
 
-| Command | Duration |
-|---------|----------|
-| `create` | 3-7 minutes |
-| `publish` | 1-3 minutes |
-| `codegen` | 2-5 minutes |
-| `download` | seconds |
+| 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) |
 
-The `--timeout` default is 600,000ms (10 min). Do not reduce it.
+¹ `--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.
 
-## Exit Codes
+---
 
-| Code | Meaning |
-|------|---------|
-| 0 | Success |
-| 1 | API error |
-| 2 | Auth error |
-| 3 | Validation error |
-| 4 | Timeout |
+## Output modes
 
-## Development
+- **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
-npm install
-npm run build     # tsup → dist/index.js
-npm test          # vitest (35 tests)
-npm run typecheck # tsc --noEmit
+npx @animaapp/cli create -t p2c -p "dashboard" --json 2>/dev/null | jq .playgroundUrl
 ```
 
+---
+
+## Debugging
+
+**`--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.
+
+```bash
+npx @animaapp/cli login --log-file ./anima-debug.log
+```
+
+**`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`.
+
+---
+
 ## License
 
 MIT