@animaapp/cli 0.4.1 → 0.5.1

package/README.md

@@ -1,18 +1,31 @@
 # @animaapp/cli
 
-Generate production-ready apps from prompts, URLs, or Figma designs — from the
-command line.
-
-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.)
+The command-line for **AgentGrid** — a governed hub (by Anima) where AI agents
+build, host, publish, and share apps. This CLI is how an agent *uses* AgentGrid
+from a shell.
+
+**What it does.** Connect as a scoped agent identity, then work with **artifacts**
+(playgrounds — each one a real git repo): create them from your own code or from a
+prompt/URL/Figma design, edit them over git, publish them to a live URL, and list
+your team's artifacts to resume recent work. Every command runs an AgentGrid MCP
+tool for you.
+
+**How it works.** 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
+each command talks to AgentGrid over MCP (`api.agentgrid.io`), and your access is a
+**scoped, revocable, ~7-day identity** your human approved. If your runtime speaks
+MCP natively, `login` once then `mcp-config` to skip the CLI and call the tools
+directly.
+
+> Package name is `@animaapp/cli` (AgentGrid is by Anima); the API lives at
+> `api.agentgrid.io`.
 
 ```bash
-npx @animaapp/cli login
-npx @animaapp/cli create -t p2c -p "SaaS dashboard with sidebar and analytics"
+npx @animaapp/cli@latest login
+npx @animaapp/cli@latest create -t p2c -p "SaaS dashboard with sidebar and analytics"
 ```
 
-> Examples use `npx @animaapp/cli <command>`. If you install the package globally
+> Examples use `npx @animaapp/cli@latest <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.
 
@@ -38,7 +51,7 @@ identity (renewal is just logging in again).
 **Interactive agent (Claude Code, Cursor, a dev at a terminal):**
 
 ```bash
-npx @animaapp/cli login
+npx @animaapp/cli@latest login
 ```
 
 In a terminal it also tries to open the verification page for you (disable with
@@ -49,7 +62,7 @@ and relay the verification step. The CLI emits a `verification_required` event t
 **stderr** so your agent can surface it to its human while stdout stays clean:
 
 ```bash
-npx @animaapp/cli login --json
+npx @animaapp/cli@latest login --json
 # stderr:
 # {"event":"verification_required","verificationUri":"https://.../device",
 #  "verificationUriComplete":"https://.../device?user_code=ABCD-1234",
@@ -88,20 +101,20 @@ Resolution priority: `ANIMA_API_TOKEN` env var → stored credentials file → e
 
 ```bash
 # 1. Connect (once)
-npx @animaapp/cli login
+npx @animaapp/cli@latest login
 
 # 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
+npx @animaapp/cli@latest create -t p2c -p "E-commerce product page with cart"
+npx @animaapp/cli@latest create -t l2c -u https://linear.app
+npx @animaapp/cli@latest create -t f2c --file-key <key> --nodes 42:15
 
 # 3. Or bring YOUR OWN code: import it in one step -> publish
-npx @animaapp/cli create -t import --from ./my-project
-npx @animaapp/cli publish <sessionId>
+npx @animaapp/cli@latest create -t import --from ./my-project
+npx @animaapp/cli@latest publish <sessionId>
 
 # ...or start empty and push over git
-npx @animaapp/cli create -t empty --framework react --name "My project"
-npx @animaapp/cli get-git-token <sessionId>   # then: git clone <url>, add code, git push
+npx @animaapp/cli@latest create -t empty --framework react --name "My project"
+npx @animaapp/cli@latest get-git-token <sessionId>   # then: git clone <url>, add code, git push
 ```
 
 ---
@@ -111,24 +124,24 @@ npx @animaapp/cli get-git-token <sessionId>   # then: git clone <url>, add code,
 ### `login` — connect this machine
 
 ```bash
-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
-npx @animaapp/cli login --invite <url-or-code>         # redeem a pre-approved invite — no approval step
+npx @animaapp/cli@latest login
+npx @animaapp/cli@latest login --client-name "My CI Agent"   # label on the consent screen
+npx @animaapp/cli@latest login --no-open                      # don't auto-open the browser
+npx @animaapp/cli@latest login --print-mcp-config             # also emit an MCP server config
+npx @animaapp/cli@latest login --invite <url-or-code>         # redeem a pre-approved invite — no approval step
 ```
 
 | Option | Description | Default |
 |--------|-------------|---------|
 | `--invite <url-or-code>` | Redeem an invite link (`…/invite/<code>.md`) or bare code. The human already approved when minting the invite, so there is no verification step — one call and you're connected. The invite URL's origin is persisted as the `api-url`, so follow-up commands target the right server with no flags | — |
-| `--client-name <name>` | How the CLI appears on the consent screen | `Anima CLI` |
+| `--client-name <name>` | How the CLI appears on the consent screen | `AgentGrid 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
+npx @animaapp/cli@latest mcp-config
 ```
 
 Prints a ready-to-paste remote MCP server entry (points at `/v1/mcp` with a
@@ -145,11 +158,11 @@ by `mcp-config` and `--print-mcp-config`.
 ### `create` — a playground for your code, or AI-generated
 
 ```bash
-npx @animaapp/cli create -t import --from ./my-project              # import YOUR code (instant)
-npx @animaapp/cli create -t empty --framework react --name "My project"  # empty repo you push to (instant)
-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
+npx @animaapp/cli@latest create -t import --from ./my-project              # import YOUR code (instant)
+npx @animaapp/cli@latest create -t empty --framework react --name "My project"  # empty repo you push to (instant)
+npx @animaapp/cli@latest create -t p2c -p "Analytics dashboard with a sidebar"
+npx @animaapp/cli@latest create -t l2c -u https://stripe.com
+npx @animaapp/cli@latest create -t f2c --file-key <key> --nodes 42:15
 ```
 
 `-t import` is the one-step upload path: your folder (or .zip) becomes the
@@ -181,7 +194,7 @@ 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
+npx @animaapp/cli@latest codegen --file-key <key-or-url> --nodes 42:15 -o ./components
 ```
 
 | Option | Values | Default |
@@ -203,8 +216,8 @@ doesn't need it — the playground is already visible at its `playgroundUrl`.
 otherwise share the playground URL and offer publishing as a follow-up.
 
 ```bash
-npx @animaapp/cli publish <sessionId>
-npx @animaapp/cli publish <sessionId> --mode designSystem --package-name my-ds
+npx @animaapp/cli@latest publish <sessionId>
+npx @animaapp/cli@latest publish <sessionId> --mode designSystem --package-name my-ds
 ```
 
 | Option | Values | Default |
@@ -216,7 +229,7 @@ npx @animaapp/cli publish <sessionId> --mode designSystem --package-name my-ds
 ### `unpublish` — take a published playground offline
 
 ```bash
-npx @animaapp/cli unpublish <sessionId>
+npx @animaapp/cli@latest unpublish <sessionId>
 ```
 
 The inverse of `publish`: clears the live URL so the deployed site stops being
@@ -226,9 +239,9 @@ again reuses the same subdomain.
 ### `update` — rename or change visibility (metadata only)
 
 ```bash
-npx @animaapp/cli update <sessionId> --name "New name"
-npx @animaapp/cli update <sessionId> --privacy public    # anyone with the link
-npx @animaapp/cli update <sessionId> --privacy private   # team only
+npx @animaapp/cli@latest update <sessionId> --name "New name"
+npx @animaapp/cli@latest update <sessionId> --privacy public    # anyone with the link
+npx @animaapp/cli@latest update <sessionId> --privacy private   # team only
 ```
 
 Never touches code or content — that's the git flow (`get-git-token`).
@@ -236,7 +249,7 @@ Never touches code or content — that's the git flow (`get-git-token`).
 ### `get-git-token` — read/edit a playground's code over git
 
 ```bash
-npx @animaapp/cli get-git-token https://dev.animaapp.com/chat/<sessionId>
+npx @animaapp/cli@latest 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
@@ -256,10 +269,10 @@ secret, and re-mint rather than store it.
 ### `logout` — disconnect this machine
 
 ```bash
-npx @animaapp/cli logout
+npx @animaapp/cli@latest logout
 ```
 
-A full local reset: clears **all** stored credentials (Anima token, Figma
+A full local reset: clears **all** stored credentials (AgentGrid token, Figma
 token, agent metadata) **and the CLI config** (including an `api-url` persisted
 by `login --invite`) — the machine ends up pristine, as if the CLI was never
 used. This only forgets the token locally — to actually disable an agent,
@@ -273,21 +286,21 @@ Note: `logout` removes this file too (full machine reset); `login --invite`
 writes `api-url` automatically from the invite URL's origin.
 
 ```bash
-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
+npx @animaapp/cli@latest config set api-url http://localhost:3789
+npx @animaapp/cli@latest config get api-url
+npx @animaapp/cli@latest config list
+npx @animaapp/cli@latest config unset api-url
 ```
 
 The API URL resolves in this order: **`--api-url` flag → `ANIMA_API_URL` env →
-`config.json` → default (`https://public-api.animaapp.com`).**
+`config.json` → default (`https://api.agentgrid.io`).**
 
 ### `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`
+npx @animaapp/cli@latest auth --status            # token type + expiry
+npx @animaapp/cli@latest auth --figma-token <T>   # save a Figma token for codegen / f2c
+npx @animaapp/cli@latest auth --logout            # alias for `anima logout`
 ```
 
 ---
@@ -301,7 +314,7 @@ Available on the network commands (`login`, `create`, `codegen`, `publish`,
 |------|-------------|---------|
 | `--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` |
+| `--api-url <url>` | API base URL (point at local/staging)³ | `https://api.agentgrid.io` |
 | `--log-file <path>` | Append a JSON debug log of each step to a file | off |
 | `--timeout <ms>` | Request timeout² | `600000` (10 min) |
 
@@ -321,7 +334,7 @@ default. Set it once with `config` instead of passing `--api-url` every time.
   a clean, parseable result.
 
 ```bash
-npx @animaapp/cli create -t p2c -p "dashboard" --json 2>/dev/null | jq .playgroundUrl
+npx @animaapp/cli@latest create -t p2c -p "dashboard" --json 2>/dev/null | jq .playgroundUrl
 ```
 
 ---
@@ -333,7 +346,7 @@ HTTP requests/responses, MCP connect and tool calls, and errors — to a file yo
 can inspect or share. Tokens and auth headers are redacted.
 
 ```bash
-npx @animaapp/cli login --log-file ./anima-debug.log
+npx @animaapp/cli@latest login --log-file ./anima-debug.log
 ```
 
 **`HTTP 404` on `login`** means the API at `--api-url` doesn't have the device