@animaapp/cli 0.7.1 → 0.8.0

package/README.md

@@ -6,9 +6,10 @@ from a shell.
 
 **What it does.** Connect as a scoped agent identity, then work with **artifacts**
 (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.
+prompt/URL/Figma design, read and change their files (with or without git),
+publish them to a live URL, answer the review comments humans leave on them, 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
@@ -38,7 +39,7 @@ Every command runs as a **scoped agent identity**: it acts only within the
 workspaces and capabilities a human approved, and your team can see and
 **revoke** it at any time. The CLI renews it in the background; after a few
 months the consent reaches its renewal limit and a human approves again. You get
-that identity one of four ways. Door 3 is the usual one — you lead with
+that identity one of three ways. Door 2 is the usual one — you lead with
 something to show, and it needs neither a token nor an account on their side.
 
 ### 1. Device login — `anima login`
@@ -77,20 +78,7 @@ 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
-```
-
-Resolution priority: `ANIMA_API_TOKEN` env var → stored credentials file → error.
-
-### 3. Create first, hand off later — anonymous artifacts
+### 2. Create first, hand off later — anonymous artifacts
 
 This is the flow where **you** lead: no token, and a human who needs no
 AgentGrid account until the moment they claim. Two commands:
@@ -123,7 +111,7 @@ a fresh one.
 
 **Send `clientName` — say what product you are** (`"Claude Code"`, `"Cursor"`,
 …), the same name you would pass to `login --client-name`. The human sees it on
-the claim page and it becomes the agent name they approve; without it they are
+the artifact page and it becomes the agent name they approve; without it they are
 asked to invent a name for an artifact they did not create. Display-only, never
 verified, ≤120 characters.
 
@@ -147,9 +135,8 @@ says so rather than polling forever.
 | 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 |
 | You want to lead: share something first, no account needed on their side | `anima create --anonymous …` → send `artifactUrl` → `anima login --handoff` |
-| Your human led: they sent you an invite link to join | `anima login --invite <url-or-code>` — one exchange, no approval step |
+| Fully headless / CI, or a human sent you an invite link | `anima login --invite <url-or-code>` — they approved when minting it, so there is no approval step at run time |
 
 ---
 
@@ -159,27 +146,63 @@ says so rather than polling forever.
 # 1. Connect (once)
 npx @animaapp/cli@latest login
 
-# 2. Create from a prompt / URL / Figma
-npx @animaapp/cli@latest create -t p2c -p "E-commerce product page with cart"
+# 2. Make an artifact — from your own code, or generated
+npx @animaapp/cli@latest create -t import --from ./my-project     # instant
+npx @animaapp/cli@latest create -t p2c -p "E-commerce page with a cart"  # waits ~3-7 min
 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@latest create -t import --from ./my-project
-npx @animaapp/cli@latest publish <sessionId>
-
 # ...or start empty and push over git
 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
 
-# ...or create an independent copy of an existing artifact
-npx @animaapp/cli@latest duplicate <artifactUrl-or-sessionId> --name "My copy"
+# 3. Change it — no clone, no git binary
+npx @animaapp/cli@latest explore <sessionId> --search "primaryColor"
+npx @animaapp/cli@latest explore <sessionId> --read src/App.tsx
+npx @animaapp/cli@latest edit <sessionId> -m "Blue buttons" \
+  --replace src/App.tsx --old "red" --new "blue"
+
+# ...or with a real checkout, when the job needs one
+npx @animaapp/cli@latest get-git-token <sessionId>   # then: git clone <url>, commit, push
+
+# 4. Share the artifactUrl the create printed. Publishing is a separate,
+#    explicit step that makes the app public to the world:
+npx @animaapp/cli@latest publish <sessionId>
+
+# Along the way
+npx @animaapp/cli@latest list                        # resume recent work
+npx @animaapp/cli@latest review list                 # what humans asked you to change
 ```
 
 ---
 
 ## Commands
 
+Every command runs one MCP tool. `anima <command> --help` prints its own
+options; `--json` makes any of them agent-readable.
+
+| | Command | What it does |
+|---|---------|--------------|
+| **Connect** | [`login`](#login--connect-this-machine) | Connect this machine as a scoped agent identity |
+| | [`logout`](#logout--disconnect-this-machine) | Revoke and clear every stored credential |
+| | [`auth`](#auth--inspect-or-manage-credentials) | Inspect credentials, store a Figma token |
+| | [`skill`](#skill--install-the-agentgrid-guide-for-your-agent) | Install the AgentGrid guide as a SKILL.md your agent can read |
+| | [`mcp-config`](#mcp-config--print-your-mcp-server-config) | Print an MCP server config for your MCP client |
+| **Find** | [`list`](#list--your-teams-artifacts) | Your team's artifacts, most-recently-updated first |
+| **Make** | [`create`](#create--an-artifact-for-your-code-or-ai-generated) | Import your code, an empty repo, or AI generation |
+| | [`status`](#status--did-generation-finish) | Did generation finish? `--wait` blocks until it has |
+| | [`duplicate`](#duplicate--copy-an-existing-artifact) | Copy an artifact into a new, independent one |
+| **Change** | [`explore`](#explore--read-an-artifacts-files-no-git) | Read files: list, search, read, history |
+| | [`edit`](#edit--change-files-and-commit-them-no-git) | Change files and commit them — one commit |
+| | [`upload-asset`](#upload-asset--add-a-large-image-font-or-media-file) | Add an image, font or media file over 256 KB |
+| | [`get-git-token`](#get-git-token--readedit-an-artifacts-code-over-git) | Mint git access for a real checkout |
+| **Collaborate** | [`review`](#review--the-comments-humans-addressed-to-you) | Read and answer the comments humans left you |
+| **Ship** | [`publish`](#publish--deploy-a-session-to-a-public-url-13-min) | Deploy to a public live URL — only when asked |
+| | [`unpublish`](#unpublish--take-a-published-artifact-offline) | Take a published artifact offline |
+| | [`update`](#update--rename-or-change-visibility-metadata-only) | Rename, or change visibility |
+| | [`delete`](#delete--hide-an-artifact-with-reversible-soft-deletion) | Reversible soft deletion |
+| **Figma** | [`codegen`](#codegen--figma-to-local-files-no-artifact) | Figma → local code files, no artifact |
+| **Settings** | [`config`](#config--store-cli-preferences) | Store CLI preferences (e.g. a default API URL) |
+
 ### `login` — connect this machine
 
 ```bash
@@ -200,6 +223,24 @@ npx @animaapp/cli@latest login --handoff <token>              # ...or name the t
 | `--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 |
 
+### `skill` — install the AgentGrid guide for your agent
+
+```bash
+npx @animaapp/cli@latest skill .claude/skills/agentgrid/SKILL.md   # write it
+npx @animaapp/cli@latest skill                                      # or print it
+```
+
+Writes a `SKILL.md` at the path you give — the whole AgentGrid flow, so an
+agent reading it knows how to connect, create, change, review and publish
+without being told. Parent directories are created; re-running overwrites.
+
+The prose is **fetched from the API** (`/guide.md`), so it does not go stale in
+an installed package, while the command reference inside it is generated from
+this CLI's own commands — meaning the syntax it shows is the syntax your
+version accepts. No credential needed: the guide is public.
+
+Point `--api-url` at another environment to install that one's guide.
+
 ### `mcp-config` — print your MCP server config
 
 ```bash
@@ -216,6 +257,16 @@ authorize when it prompts. No CLI in the loop after that. Your client needs to
 support OAuth for remote MCP servers (`.well-known` discovery); if it cannot,
 use the CLI commands instead.
 
+### `list` — your team's artifacts
+
+```bash
+npx @animaapp/cli@latest list
+```
+
+Most-recently-updated first, so you can resume existing work instead of
+creating a second artifact for the same job. Each row carries its session id
+and `artifactUrl`; `--json` adds them to every row.
+
 ### `create` — an artifact for your code, or AI-generated
 
 ```bash
@@ -235,6 +286,16 @@ or binary ones are zipped and uploaded via a presigned URL automatically.
 returned URL, add your code, and `git push`. Then `publish <sessionId>` for a
 live URL. The other types are AI generation (3–7 min).
 
+**`create -t p2c|l2c|f2c` blocks for 3–7 minutes.** The generation itself is
+asynchronous — the server starts a background job and answers immediately — but
+the command waits it out for you, polling until the app is ready or failed. So
+what `create` prints is a finished app, and a failed generation is a non-zero
+exit rather than a link to nothing. Budget the wall-clock time, and keep the
+default `--timeout` of `600000`.
+
+Pass `--no-wait` to get the session id back in seconds instead and do the
+waiting yourself with [`status --wait`](#status--did-generation-finish).
+
 `--artifact-type` is a separate question from `-t`: `-t` is how the repository
 starts, `--artifact-type` is what the artifact IS, and it decides how a human
 sees it. `app` is a running web page and needs an `index.html`; `markdown` is a
@@ -261,10 +322,133 @@ uploaded as an app produce an artifact with nothing to render.
 | `--language` | `typescript`, `javascript` | `typescript` (react) |
 | `--ui-library` | `shadcn`, `mui`, `antd`, `clean_react` | _(none)_ |
 | `--guidelines` | free text | _(p2c only)_ |
+| `--no-wait` | Return as soon as generation starts, instead of waiting for the finished app | _off (create waits)_ |
+| `--timeout <ms>` | How long to wait for generation | `600000` |
 
 ¹ The valid styling / UI-library set depends on `--type`; the server validates and
 returns a clear error for unsupported combinations.
 
+### `status` — did generation finish?
+
+```bash
+npx @animaapp/cli@latest status <artifactUrl-or-sessionId>           # a snapshot
+npx @animaapp/cli@latest status <artifactUrl-or-sessionId> --wait    # block until ready or failed
+```
+
+Generation runs in the background, so this is how you learn it finished.
+`create` already waits; reach for this after `create --no-wait`, or to pick a
+wait back up after a timeout. `--wait` blocks until the artifact is `ready` or
+`failed` (the underlying tool returns about every 45 seconds and this re-calls
+it), and a `failed` status exits non-zero so a caller checking only the exit
+code cannot mistake it for done.
+
+| Option | Values | Default |
+|--------|--------|---------|
+| `--wait` | block until the artifact settles | off (snapshot) |
+| `--timeout <ms>` | how long `--wait` may block | `600000` |
+
+### `explore` — read an artifact's files (no git)
+
+```bash
+npx @animaapp/cli@latest explore <artifact> --search "buttonColor"     # find the file
+npx @animaapp/cli@latest explore <artifact> --read src/App.tsx          # read it
+npx @animaapp/cli@latest explore <artifact> --tree --path src           # list a directory
+npx @animaapp/cli@latest explore <artifact> --history                   # commits, newest first
+```
+
+Needs no shell, no git and no network of its own. Start with `--search` when
+you do not know which file to change, then `--read` the ones you will edit.
+Every response carries `revision`, the artifact's current commit — pass it to
+`edit --base-revision`.
+
+| Option | Values | Default |
+|--------|--------|---------|
+| `--tree` / `--search <q>` / `--read <paths...>` / `--history` | exactly one is required | — |
+| `--path <prefix>` | tree/search: a literal directory prefix (not a glob) | _(whole artifact)_ |
+| `--range <start,end>` | read: 1-based inclusive line window, single file only | _(whole file)_ |
+| `--revision <rev>` | see the artifact as it was at this commit | _(current)_ |
+| `--regex`, `--case-sensitive` | search behaviour | off |
+| `--include-excluded` | also search `node_modules`, `dist`, `build` | off |
+| `--limit <n>` | maximum rows | _(server default)_ |
+| `--cursor <c>` | history: continue after a previous response's `nextCursor` | — |
+
+A file whose bytes are not text comes back as `asset: true` with its size and
+mime instead of content, and an empty search reports what it skipped — check
+`notSearched` before concluding the text is not there.
+
+### `edit` — change files and commit them (no git)
+
+```bash
+# the shorthands
+npx @animaapp/cli@latest edit <artifact> -m "Blue pill" --replace src/App.tsx --old "red" --new "blue"
+npx @animaapp/cli@latest edit <artifact> -m "Add page" --write src/about.tsx --from-file ./about.tsx
+npx @animaapp/cli@latest edit <artifact> -m "Drop dead code" --delete src/old.ts
+npx @animaapp/cli@latest edit <artifact> -m "Rename" --move src/a.ts --to src/b.ts
+
+# the general door: several operations, one commit
+npx @animaapp/cli@latest edit <artifact> -m "Retheme" --changes '[
+  {"op":"str_replace","path":"src/App.tsx","oldText":"red","newText":"blue"},
+  {"op":"delete","path":"src/legacy.css"}
+]'
+```
+
+Everything in one call lands as **one commit**: either every operation applies
+or none does. The live artifact reflects it immediately.
+
+| Option | Values | Default |
+|--------|--------|---------|
+| `-m, --message` | commit message | _required_ |
+| `--base-revision <rev>` | the revision the edit applies to | _the current head_ |
+| `--changes <json>` / `--changes-file <path>` | the full operation list | — |
+| `--write <path>` + `--content <text>` / `--from-file <path>` | create or replace a file | — |
+| `--delete <path>` | remove a file | — |
+| `--move <path> --to <path>` | rename a file | — |
+| `--replace <path> --old <text> --new <text>` `[--all]` | swap an exact snippet | — |
+
+Without `--base-revision` the edit applies to the artifact's current head, read
+immediately beforehand. Pass a revision from `explore` when you want to be told
+about a concurrent change (`REVISION_CONFLICT`) rather than write over it.
+
+`--move` does not rewrite imports — neither in the files importing the moved
+module nor the relative imports inside it. Read the file first and send the
+`str_replace` operations that fix them in the same commit.
+
+### `upload-asset` — add a large image, font or media file
+
+```bash
+npx @animaapp/cli@latest upload-asset <artifact> ./hero.png --path public/hero.png -m "Add hero"
+npx @animaapp/cli@latest upload-asset <artifact> ./hero.png     # stage only; prints assetUploadId
+```
+
+For files over 256 KB, which is the most `edit` takes inline. This stages the
+upload, performs it, and — when `--path` says where the file belongs — commits
+it in the same run. Files over 10 MB go through Git LFS automatically. Smaller
+files need none of this: send them to `edit` directly.
+
+### `review` — the comments humans addressed to you
+
+```bash
+npx @animaapp/cli@latest review list                       # everything addressed to you
+npx @animaapp/cli@latest review list <artifact>            # just this artifact
+npx @animaapp/cli@latest review reply <commentId> -m "Which pill did you mean?"
+npx @animaapp/cli@latest review resolve <commentId> --note "Left as-is: it matches the spec"
+```
+
+A review is a batch of comments a human pinned to places in an artifact and
+sent as one. Nothing pushes them to you, so `review list` is how the work
+arrives — run it when a human says they left comments, and when starting work
+on an artifact you have been reviewed on before.
+
+Read the replies before acting: a reviewer can keep talking after sending, so
+the comment body is where the request starts, not necessarily where it ends. A
+comment marked `unassigned` was addressed to nobody in particular and is
+anyone's to take.
+
+To close comments, put the review's `resolveTrailer` lines in your commit
+message — that records which commit resolved them. `review resolve` is for what
+a commit cannot carry (a question answered, a change you decided against), and
+`review reply` says something while leaving the comment **open**.
+
 ### `duplicate` — copy an existing artifact
 
 ```bash
@@ -278,8 +462,9 @@ chat or custom domains. The source must be readable and the destination
 workspace must be writable. Without `--name`, the API names it
 `<source name> (Copy)`.
 
-The result includes the new and source session IDs, duplicate name,
-`playgroundUrl`, `previewUrl`, and API-provided next steps. Duplication is not
+The result includes the new and source session IDs, the duplicate's name, its
+`artifactUrl` (plus `playgroundUrl` and `previewUrl` when the copy is an app),
+and API-provided next steps. Duplication is not
 idempotent: if a request times out or its response is lost, run `list` and check
 recent artifacts before retrying.
 
@@ -303,7 +488,7 @@ npx @animaapp/cli@latest codegen --file-key <key-or-url> --nodes 42:15 -o ./comp
 ### `publish` — deploy a session to a public URL (1–3 min)
 
 Publishing makes the app **public to the world**. Sharing usually
-doesn't need it — the artifact is already visible at its `playgroundUrl`.
+doesn't need it — the artifact is already visible at its `artifactUrl`.
 **Agents:** only publish when the human explicitly asked for a public site;
 otherwise share that URL and offer publishing as a follow-up.
 
@@ -325,6 +510,17 @@ The inverse of `publish`: clears the live URL so the deployed site stops being
 reachable. The artifact, its code, and its content are untouched; publishing
 again reuses the same subdomain.
 
+### `delete` — hide an artifact with reversible soft deletion
+
+```bash
+npx @animaapp/cli@latest delete <artifactUrl-or-sessionId>
+```
+
+Run this only when deletion was explicitly requested. Published artifacts must
+be unpublished first. The operation hides the artifact but is reversible and
+does not remove its code, assets, history, database content, or domain
+assignments; it never permanently deletes an artifact.
+
 ### `update` — rename or change visibility (metadata only)
 
 ```bash
@@ -333,28 +529,42 @@ npx @animaapp/cli@latest update <sessionId> --privacy public    # anyone with th
 npx @animaapp/cli@latest update <sessionId> --privacy private   # team only
 ```
 
-Never touches code or content — that's the git flow (`get-git-token`).
+Never touches code or content — that's `edit` (or the git flow via
+`get-git-token`).
 
 ### `get-git-token` — read/edit an artifact's code over git
 
 ```bash
-npx @animaapp/cli@latest get-git-token https://dev.animaapp.com/chat/<sessionId>
+npx @animaapp/cli@latest get-git-token https://app.agentgrid.io/artifacts/<sessionId>
 ```
 
-An artifact **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
-artifact and prints a ready-to-use remote URL — you run git yourself:
+An artifact **is** a git repository. This command mints a short-lived access
+token scoped to that one artifact and prints a ready-to-use remote URL — you
+run git yourself:
 
 ```bash
 git clone <gitRemoteUrl>               # read (and edit locally)
+git config user.name … && git config user.email …   # the identity the grant names
 git push                               # read-write access: updates the live artifact
 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 }`.
+A read-write grant also names the `commitAuthor` your commits should carry —
+the agent behind the credential, or the human. Run the printed `git config`
+pair in the clone before committing: a fresh clone has no identity of its own,
+so without it your pushes are attributed to whatever git identity this machine
+happens to have.
+
+In `--json` mode the output is `{ gitRemoteUrl, access: "ro"|"rw", expiresAt,
+commitAuthor, gitConfigCommand }`.
 The token expires within an hour and cannot be renewed — treat the URL as a
 secret, and re-mint rather than store it.
 
+Git is not the only door: `explore` and `edit` change the same repository with
+no clone, no shell and no git binary. Reach for a checkout when that is what
+the job actually needs — a large refactor, running the project, branches, or
+rewriting history.
+
 ### `logout` — disconnect this machine
 
 ```bash
@@ -402,23 +612,29 @@ is `awaiting_claim` or `expired`, alongside the `artifactUrl` to re-send.
 
 ## Global flags
 
-Available on the network commands (`login`, `create`, `duplicate`, `codegen`,
-`publish`, `get-git-token`):
+| Flag | Description | Available on |
+|------|-------------|--------------|
+| `--json` | Emit a single JSON object to stdout (for agents) | every command |
+| `--api-url <url>` | API base URL — point at local or staging³ | every command except `config` |
+| `--log-file <path>` | Append a JSON debug log of each step to a file | every command that reaches the network |
+| `--verbose` | Stream progress to stderr in JSON mode¹ | `create`, `status`, `duplicate`, `upload-asset`, `publish`, `unpublish`, `update`, `delete`, `codegen`, `get-git-token` |
+| `--timeout <ms>` | How long to wait² | `create`, `status`, `codegen` |
+
+¹ Only the commands that do slow work carry a spinner, so `--verbose` is on
+those. `explore`, `edit`, `list` and `review` are a single round trip and
+report nothing in between.
+
+² Defaults to `600000` (10 min). On `create` and `status --wait` it is the
+budget for the whole generation wait, not one request — don't lower it, since
+generation takes minutes. Running out is a `TIMEOUT` exit that tells you the
+job is still running and how to resume the wait.
 
-| 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://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) |
+³ Falls back to `ANIMA_API_URL`, then `anima config set api-url`, then
+`https://api.agentgrid.io`. Set it once with `config` instead of passing
+`--api-url` every time.
 
-¹ `--verbose` applies to `create` / `duplicate` / `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.
+**Environment variables:** `ANIMA_API_URL`, `ANIMA_LOG_FILE`, and `FIGMA_TOKEN`
+for `codegen` / `create -t f2c`.
 
 ---
 
@@ -430,7 +646,7 @@ default. Set it once with `config` instead of passing `--api-url` every time.
   a clean, parseable result.
 
 ```bash
-npx @animaapp/cli@latest 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 -r .artifactUrl
 ```
 
 ---
@@ -446,7 +662,8 @@ 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
-grant deployed. Point at an API that does (`--api-url`) or use `ANIMA_API_TOKEN`.
+grant deployed. Point at an API that does with `--api-url`, or connect with
+`login --invite` instead.
 
 ---