@animaapp/cli 0.5.1 → 0.7.0

package/README.md

@@ -5,7 +5,7 @@ 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
+(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.
@@ -13,7 +13,8 @@ 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
+**scoped, revocable identity** your human approved, renewed for you as it
+expires. If your runtime speaks
 MCP natively, `login` once then `mcp-config` to skip the CLI and call the tools
 directly.
 
@@ -34,8 +35,11 @@ npx @animaapp/cli@latest create -t p2c -p "SaaS dashboard with sidebar and analy
 ## 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.
+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
+something to show, and it needs neither a token nor an account on their side.
 
 ### 1. Device login — `anima login`
 
@@ -86,6 +90,56 @@ 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
+
+This is the flow where **you** lead: no token, and a human who needs no
+AgentGrid account until the moment they claim. Two commands:
+
+```bash
+# 1. Create it. Prints claimUrl — send your human that link.
+anima create --anonymous -t import --from ./my-project \
+  --client-name "Claude Code" --json
+
+# 2. Wait for them to claim it, then store the credentials that grants.
+anima login --handoff --json
+```
+
+`create --anonymous` needs no credential at all. It returns a `claimUrl` for
+your human, and a **`handoffToken`** for you. The token has two uses:
+
+```bash
+anima login --handoff <token>                       # log in, once they claim it
+anima create --anonymous --handoff <token> --from … # another artifact, same claim
+```
+
+The CLI stores the token, so both commands default to your last one and you can
+leave `<token>` off. Keep it yourself if this machine's config will not outlive
+the process — it is delivered exactly once and can never be re-fetched. Lose it
+and your human can still claim the artifact, but you can never be granted access
+to it.
+
+Once a claim window closes unclaimed, the next `create --anonymous` just starts
+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
+asked to invent a name for an artifact they did not create. Display-only, never
+verified, ≤120 characters.
+
+`login --handoff` blocks until the claim lands. Background it if you have other
+work, and check the state whenever you like:
+
+```bash
+anima login --handoff --json > anima-login.json &
+anima auth --status --json     # pendingHandoff.state: awaiting_claim | expired
+```
+
+Anonymous artifacts are read-only and expire in 24h if nobody claims them. The
+handoff token does **not** claim anything — the human never needs it, and never
+gets it. A claim without agent access grants no token, and `login --handoff`
+says so rather than polling forever.
+
 ### Which do I use?
 
 | Situation | How to connect |
@@ -94,6 +148,8 @@ Resolution priority: `ANIMA_API_TOKEN` env var → stored credentials file → e
 | 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 `claimUrl` → `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 |
 
 ---
 
@@ -115,6 +171,9 @@ 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"
 ```
 
 ---
@@ -129,49 +188,60 @@ npx @animaapp/cli@latest login --client-name "My CI Agent"   # label on the cons
 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
+npx @animaapp/cli@latest login --handoff                      # wait for a claim on your anonymous artifact
+npx @animaapp/cli@latest login --handoff <token>              # ...or name the token explicitly
 ```
 
 | Option | Description | Default |
 |--------|-------------|---------|
+| `--handoff [token]` | Log in with the handoff token from an anonymous create. Waits until a human claims the artifact, then stores the credentials their claim grants — same store as every other door. Defaults to your last one. Blocks; background it with `&` and watch `auth --status`. Stops with a clear message if the window closes unclaimed, or if the human claimed without granting agent access | — |
 | `--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 | `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)
+### `mcp-config` — print your MCP server config
 
 ```bash
 npx @animaapp/cli@latest 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 }`.
+Prints a ready-to-paste remote MCP server entry pointing at `/v1/mcp`. It
+contains **no credential** and needs none: your MCP client authorizes itself
+against the server and holds a credential it can renew on its own. No network
+call, no device flow. `--json` wraps it as `{ success, mcpConfig }`.
 
-**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`.
+**MCP-capable agents:** run `mcp-config`, add the entry to your client, and
+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.
 
-### `create` — a playground for your code, or AI-generated
+### `create` — an artifact for your code, or AI-generated
 
 ```bash
 npx @animaapp/cli@latest create -t import --from ./my-project              # import YOUR code (instant)
+npx @animaapp/cli@latest create -t import --from ./notes --artifact-type markdown  # a readable document
 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
+npx @animaapp/cli@latest create -t import --from ./my-project --anonymous     # no account — hand off later
 ```
 
 `-t import` is the one-step upload path: your folder (or .zip) becomes the
-playground's first commit — small text-only projects are sent inline, larger
+artifact's first commit — small text-only projects are sent inline, larger
 or binary ones are zipped and uploaded via a presigned URL automatically.
 `-t empty` creates an empty repository instead: follow with `git clone` of the
 returned URL, add your code, and `git push`. Then `publish <sessionId>` for a
 live URL. The other types are AI generation (3–7 min).
 
+`--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
+readable document and needs `.md` files. Omit it and the server infers one:
+markdown when your files are `.md`/`.mdx` with no HTML, otherwise app. Getting it wrong is the common mistake — `.md` files
+uploaded as an app produce an artifact with nothing to render.
+
 | Option | Values | Default |
 |--------|--------|---------|
 | `-t, --type` | `import` (your code, with `--from`), `empty` (repo to push to), `p2c` (prompt), `l2c` (URL), `f2c` (Figma) | _required_ |
@@ -182,7 +252,11 @@ live URL. The other types are AI generation (3–7 min).
 | `--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` |
+| `--artifact-type` | `app` (web page, needs an `index.html`), `markdown` (document, needs `.md` files) | _inferred from your files_ |
+| `--anonymous` | Create with no account (`-t import` only). Returns `claimUrl` for your human and a `handoffToken` for you | off |
+| `--handoff <token>` | Add this artifact to an existing claim (`--anonymous` only), so one link covers them all | _your last one_ |
+| `--client-name` | Who to credit as the creator on the claim page (`--anonymous` only) | `AgentGrid CLI` |
+| `--framework` | `react`, `html` — apps only | `react` |
 | `--styling` | `tailwind`, `css`, `plain_css`, `css_modules`, `inline_styles`¹ | `tailwind` |
 | `--language` | `typescript`, `javascript` | `typescript` (react) |
 | `--ui-library` | `shadcn`, `mui`, `antd`, `clean_react` | _(none)_ |
@@ -191,7 +265,25 @@ live URL. The other types are AI generation (3–7 min).
 ¹ 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)
+### `duplicate` — copy an existing artifact
+
+```bash
+npx @animaapp/cli@latest duplicate <artifactUrl-or-sessionId>
+npx @animaapp/cli@latest duplicate <artifactUrl-or-sessionId> --name "My copy"
+```
+
+Creates a new, independent artifact in the current team's Default workspace.
+It copies code, assets, and supported database content, but does **not** copy
+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
+idempotent: if a request times out or its response is lost, run `list` and check
+recent artifacts before retrying.
+
+### `codegen` — Figma to local files (no artifact)
 
 ```bash
 npx @animaapp/cli@latest codegen --file-key <key-or-url> --nodes 42:15 -o ./components
@@ -210,30 +302,27 @@ 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 playground **public to the world**. Sharing usually
-doesn't need it — the playground is already visible at its `playgroundUrl`.
+Publishing makes the app **public to the world**. Sharing usually
+doesn't need it — the artifact is already visible at its `playgroundUrl`.
 **Agents:** only publish when the human explicitly asked for a public site;
-otherwise share the playground URL and offer publishing as a follow-up.
+otherwise share that URL and offer publishing as a follow-up.
 
 ```bash
 npx @animaapp/cli@latest publish <sessionId>
-npx @animaapp/cli@latest publish <sessionId> --mode designSystem --package-name my-ds
 ```
 
-| Option | Values | Default |
-|--------|--------|---------|
-| `--mode` | `webapp`, `designSystem` | `webapp` |
-| `--package-name` | npm package name | _(designSystem)_ |
-| `--package-version` | npm package version | _(designSystem)_ |
+Deploys the artifact's app to a live URL. Publishing as a design-system npm
+package is an enterprise feature and is not reachable over MCP, so this CLI
+does not offer it.
 
-### `unpublish` — take a published playground offline
+### `unpublish` — take a published artifact offline
 
 ```bash
 npx @animaapp/cli@latest unpublish <sessionId>
 ```
 
 The inverse of `publish`: clears the live URL so the deployed site stops being
-reachable. The playground, its code, and its content are untouched; publishing
+reachable. The artifact, its code, and its content are untouched; publishing
 again reuses the same subdomain.
 
 ### `update` — rename or change visibility (metadata only)
@@ -246,19 +335,19 @@ npx @animaapp/cli@latest update <sessionId> --privacy private   # team only
 
 Never touches code or content — that's the git flow (`get-git-token`).
 
-### `get-git-token` — read/edit a playground's code over git
+### `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>
 ```
 
-A playground **is** a git repository, and git is the only way to read or edit
+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
-playground and prints a ready-to-use remote URL — you run git yourself:
+artifact 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 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
 ```
 
@@ -272,11 +361,13 @@ secret, and re-mint rather than store it.
 npx @animaapp/cli@latest logout
 ```
 
-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,
-revoke it from your team settings.
+A full reset: revokes the agent credentials server-side, then 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. Because the revocation is
+server-side, a copy of the token taken from this machine stops working too.
+The agent identity itself remains on your team roster; revoke it there to retire
+it for good.
 
 ### `config` — store CLI preferences
 
@@ -298,17 +389,21 @@ The API URL resolves in this order: **`--api-url` flag → `ANIMA_API_URL` env
 ### `auth` — inspect or manage credentials
 
 ```bash
-npx @animaapp/cli@latest auth --status            # token type + expiry
+npx @animaapp/cli@latest auth --status            # token type + expiry, and any pending claim
 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`
 ```
 
+`--status` also reports a handoff waiting to be claimed — including when you are
+not connected yet, which is exactly when you want to ask. `pendingHandoff.state`
+is `awaiting_claim` or `expired`, alongside the `claimUrl` to re-send.
+
 ---
 
 ## Global flags
 
-Available on the network commands (`login`, `create`, `codegen`, `publish`,
-`get-git-token`):
+Available on the network commands (`login`, `create`, `duplicate`, `codegen`,
+`publish`, `get-git-token`):
 
 | Flag | Description | Default |
 |------|-------------|---------|
@@ -318,7 +413,8 @@ Available on the network commands (`login`, `create`, `codegen`, `publish`,
 | `--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`.
+¹ `--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