npm - @animaapp/cli - Versions diffs - 0.5.1 → 0.6.0 - Mend

@animaapp/cli 0.5.1 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4) hide show

package/README.md CHANGED Viewed

@@ -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,10 @@ 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 three ways — the third also covers the case where you have no human to ask yet.
 ### 1. Device login — `anima login`
@@ -86,6 +89,33 @@ 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
+When there is **no human available yet** and no token, you can still put work on
+AgentGrid. Create an artifact anonymously over REST (the CLI needs an identity,
+so this one call is plain `curl`), then hand it to a human when they appear:
+```bash
+curl -s -X POST "https://public-api.animaapp.com/v1/generationSessions" \
+  -H 'Content-Type: application/json' \
+  -d '{"type":"import","name":"My project","clientName":"Claude Code",
+       "files":{"index.html":"<!doctype html><h1>hi</h1>"}}'
+```
+**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.
+The response returns a claim link for your human plus a `handoffToken` for you.
+The token does **not** claim anything — it groups further anonymous creates into
+the same handoff, and you poll `POST /oauth/token` with it
+(`grant_type=urn:animaapp:params:oauth:grant-type:handoff_token`) until the
+human claims, at which point the poll returns your agent token. Store it and use
+it as `ANIMA_API_TOKEN` (door 2) for every command after that. Anonymous
+artifacts are read-only and expire in 24h if nobody claims them.
 ### Which do I use?
 | Situation | How to connect |
@@ -94,6 +124,7 @@ 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 |
+| No human *yet*, nothing to authenticate with | create anonymously with `clientName`, send the claim link, poll for the token |
 ---
@@ -115,6 +146,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"
 ```
 ---
@@ -138,27 +172,27 @@ npx @animaapp/cli@latest login --invite <url-or-code>         # redeem a pre-app
 | `--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
@@ -166,12 +200,19 @@ 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
-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 +223,8 @@ 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), `asset` (images/video, with a zip) | _inferred from your files_ |
+| `--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 +233,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 +270,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 +303,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 +329,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
@@ -307,8 +366,8 @@ npx @animaapp/cli@latest auth --logout            # alias for `anima logout`
 ## 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 +377,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