@animaapp/cli 0.5.0 → 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
  1. package/README.md +142 -82
  2. package/dist/index.js +408 -269
  3. package/dist/index.js.map +1 -1
  4. package/package.json +1 -1
package/README.md CHANGED
@@ -5,7 +5,7 @@ build, host, publish, and share apps. This CLI is how an agent *uses* AgentGrid
5
5
  from a shell.
6
6
 
7
7
  **What it does.** Connect as a scoped agent identity, then work with **artifacts**
8
- (playgrounds — each one a real git repo): create them from your own code or from a
8
+ (each one a real git repo): create them from your own code or from a
9
9
  prompt/URL/Figma design, edit them over git, publish them to a live URL, and list
10
10
  your team's artifacts to resume recent work. Every command runs an AgentGrid MCP
11
11
  tool for you.
@@ -13,7 +13,8 @@ tool for you.
13
13
  **How it works.** Built for **agents**: any AI tool that can run a shell command
14
14
  can use it — no MCP server to configure, no plugins, just `npx`. Under the hood
15
15
  each command talks to AgentGrid over MCP (`api.agentgrid.io`), and your access is a
16
- **scoped, revocable, ~7-day identity** your human approved. If your runtime speaks
16
+ **scoped, revocable identity** your human approved, renewed for you as it
17
+ expires. If your runtime speaks
17
18
  MCP natively, `login` once then `mcp-config` to skip the CLI and call the tools
18
19
  directly.
19
20
 
@@ -21,11 +22,11 @@ directly.
21
22
  > `api.agentgrid.io`.
22
23
 
23
24
  ```bash
24
- npx @animaapp/cli login
25
- npx @animaapp/cli create -t p2c -p "SaaS dashboard with sidebar and analytics"
25
+ npx @animaapp/cli@latest login
26
+ npx @animaapp/cli@latest create -t p2c -p "SaaS dashboard with sidebar and analytics"
26
27
  ```
27
28
 
28
- > Examples use `npx @animaapp/cli <command>`. If you install the package globally
29
+ > Examples use `npx @animaapp/cli@latest <command>`. If you install the package globally
29
30
  > (`npm i -g @animaapp/cli`), the same commands are available as `anima <command>` —
30
31
  > the shorthand used in prose below.
31
32
 
@@ -34,8 +35,10 @@ npx @animaapp/cli create -t p2c -p "SaaS dashboard with sidebar and analytics"
34
35
  ## Connecting an agent
35
36
 
36
37
  Every command runs as a **scoped agent identity**: it acts only within the
37
- workspaces and capabilities a human approved, your team can see and **revoke** it
38
- at any time, and it expires after ~7 days. You get that identity one of two ways.
38
+ workspaces and capabilities a human approved, and your team can see and
39
+ **revoke** it at any time. The CLI renews it in the background; after a few
40
+ months the consent reaches its renewal limit and a human approves again. You get
41
+ that identity one of three ways — the third also covers the case where you have no human to ask yet.
39
42
 
40
43
  ### 1. Device login — `anima login`
41
44
 
@@ -51,7 +54,7 @@ identity (renewal is just logging in again).
51
54
  **Interactive agent (Claude Code, Cursor, a dev at a terminal):**
52
55
 
53
56
  ```bash
54
- npx @animaapp/cli login
57
+ npx @animaapp/cli@latest login
55
58
  ```
56
59
 
57
60
  In a terminal it also tries to open the verification page for you (disable with
@@ -62,7 +65,7 @@ and relay the verification step. The CLI emits a `verification_required` event t
62
65
  **stderr** so your agent can surface it to its human while stdout stays clean:
63
66
 
64
67
  ```bash
65
- npx @animaapp/cli login --json
68
+ npx @animaapp/cli@latest login --json
66
69
  # stderr:
67
70
  # {"event":"verification_required","verificationUri":"https://.../device",
68
71
  # "verificationUriComplete":"https://.../device?user_code=ABCD-1234",
@@ -86,6 +89,33 @@ export FIGMA_TOKEN=<token> # only for codegen / f2c
86
89
 
87
90
  Resolution priority: `ANIMA_API_TOKEN` env var → stored credentials file → error.
88
91
 
92
+ ### 3. Create first, hand off later — anonymous artifacts
93
+
94
+ When there is **no human available yet** and no token, you can still put work on
95
+ AgentGrid. Create an artifact anonymously over REST (the CLI needs an identity,
96
+ so this one call is plain `curl`), then hand it to a human when they appear:
97
+
98
+ ```bash
99
+ curl -s -X POST "https://public-api.animaapp.com/v1/generationSessions" \
100
+ -H 'Content-Type: application/json' \
101
+ -d '{"type":"import","name":"My project","clientName":"Claude Code",
102
+ "files":{"index.html":"<!doctype html><h1>hi</h1>"}}'
103
+ ```
104
+
105
+ **Send `clientName` — say what product you are** (`"Claude Code"`, `"Cursor"`,
106
+ …), the same name you would pass to `login --client-name`. The human sees it on
107
+ the claim page and it becomes the agent name they approve; without it they are
108
+ asked to invent a name for an artifact they did not create. Display-only, never
109
+ verified, ≤120 characters.
110
+
111
+ The response returns a claim link for your human plus a `handoffToken` for you.
112
+ The token does **not** claim anything — it groups further anonymous creates into
113
+ the same handoff, and you poll `POST /oauth/token` with it
114
+ (`grant_type=urn:animaapp:params:oauth:grant-type:handoff_token`) until the
115
+ human claims, at which point the poll returns your agent token. Store it and use
116
+ it as `ANIMA_API_TOKEN` (door 2) for every command after that. Anonymous
117
+ artifacts are read-only and expire in 24h if nobody claims them.
118
+
89
119
  ### Which do I use?
90
120
 
91
121
  | Situation | How to connect |
@@ -94,6 +124,7 @@ Resolution priority: `ANIMA_API_TOKEN` env var → stored credentials file → e
94
124
  | Interactive agent, human nearby | `anima login` — show the URL + code, human approves on any device |
95
125
  | Headless agent, human reachable | `anima login --json` — relay the `verification_required` event, polling finishes automatically |
96
126
  | Fully headless / CI, no human | set `ANIMA_API_TOKEN` — no login step |
127
+ | No human *yet*, nothing to authenticate with | create anonymously with `clientName`, send the claim link, poll for the token |
97
128
 
98
129
  ---
99
130
 
@@ -101,20 +132,23 @@ Resolution priority: `ANIMA_API_TOKEN` env var → stored credentials file → e
101
132
 
102
133
  ```bash
103
134
  # 1. Connect (once)
104
- npx @animaapp/cli login
135
+ npx @animaapp/cli@latest login
105
136
 
106
137
  # 2. Create from a prompt / URL / Figma
107
- npx @animaapp/cli create -t p2c -p "E-commerce product page with cart"
108
- npx @animaapp/cli create -t l2c -u https://linear.app
109
- npx @animaapp/cli create -t f2c --file-key <key> --nodes 42:15
138
+ npx @animaapp/cli@latest create -t p2c -p "E-commerce product page with cart"
139
+ npx @animaapp/cli@latest create -t l2c -u https://linear.app
140
+ npx @animaapp/cli@latest create -t f2c --file-key <key> --nodes 42:15
110
141
 
111
142
  # 3. Or bring YOUR OWN code: import it in one step -> publish
112
- npx @animaapp/cli create -t import --from ./my-project
113
- npx @animaapp/cli publish <sessionId>
143
+ npx @animaapp/cli@latest create -t import --from ./my-project
144
+ npx @animaapp/cli@latest publish <sessionId>
114
145
 
115
146
  # ...or start empty and push over git
116
- npx @animaapp/cli create -t empty --framework react --name "My project"
117
- npx @animaapp/cli get-git-token <sessionId> # then: git clone <url>, add code, git push
147
+ npx @animaapp/cli@latest create -t empty --framework react --name "My project"
148
+ npx @animaapp/cli@latest get-git-token <sessionId> # then: git clone <url>, add code, git push
149
+
150
+ # ...or create an independent copy of an existing artifact
151
+ npx @animaapp/cli@latest duplicate <artifactUrl-or-sessionId> --name "My copy"
118
152
  ```
119
153
 
120
154
  ---
@@ -124,11 +158,11 @@ npx @animaapp/cli get-git-token <sessionId> # then: git clone <url>, add code,
124
158
  ### `login` — connect this machine
125
159
 
126
160
  ```bash
127
- npx @animaapp/cli login
128
- npx @animaapp/cli login --client-name "My CI Agent" # label on the consent screen
129
- npx @animaapp/cli login --no-open # don't auto-open the browser
130
- npx @animaapp/cli login --print-mcp-config # also emit an MCP server config
131
- npx @animaapp/cli login --invite <url-or-code> # redeem a pre-approved invite — no approval step
161
+ npx @animaapp/cli@latest login
162
+ npx @animaapp/cli@latest login --client-name "My CI Agent" # label on the consent screen
163
+ npx @animaapp/cli@latest login --no-open # don't auto-open the browser
164
+ npx @animaapp/cli@latest login --print-mcp-config # also emit an MCP server config
165
+ npx @animaapp/cli@latest login --invite <url-or-code> # redeem a pre-approved invite — no approval step
132
166
  ```
133
167
 
134
168
  | Option | Description | Default |
@@ -138,40 +172,47 @@ npx @animaapp/cli login --invite <url-or-code> # redeem a pre-approved i
138
172
  | `--no-open` | Don't try to open the verification page in a browser | — |
139
173
  | `--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 |
140
174
 
141
- ### `mcp-config` — print your MCP server config (no new login)
175
+ ### `mcp-config` — print your MCP server config
142
176
 
143
177
  ```bash
144
- npx @animaapp/cli mcp-config
178
+ npx @animaapp/cli@latest mcp-config
145
179
  ```
146
180
 
147
- Prints a ready-to-paste remote MCP server entry (points at `/v1/mcp` with a
148
- bearer header) **from your stored credentials** — no network call, no device
149
- flow. Errors with "run `anima login`" if you are not logged in or the token
150
- expired. `--json` wraps it as `{ success, mcpConfig, expiresAt }`.
181
+ Prints a ready-to-paste remote MCP server entry pointing at `/v1/mcp`. It
182
+ contains **no credential** and needs none: your MCP client authorizes itself
183
+ against the server and holds a credential it can renew on its own. No network
184
+ call, no device flow. `--json` wraps it as `{ success, mcpConfig }`.
151
185
 
152
- **MCP-capable agents:** `login` once, then `mcp-config`. Configure the printed
153
- entry and use native MCP tools directly — no CLI in the loop. The token is
154
- scoped and expires in ~7 days; on auth errors run `login` again, then
155
- `mcp-config` again. The token is never printed by plain `login --json` — only
156
- by `mcp-config` and `--print-mcp-config`.
186
+ **MCP-capable agents:** run `mcp-config`, add the entry to your client, and
187
+ authorize when it prompts. No CLI in the loop after that. Your client needs to
188
+ support OAuth for remote MCP servers (`.well-known` discovery); if it cannot,
189
+ use the CLI commands instead.
157
190
 
158
- ### `create` — a playground for your code, or AI-generated
191
+ ### `create` — an artifact for your code, or AI-generated
159
192
 
160
193
  ```bash
161
- npx @animaapp/cli create -t import --from ./my-project # import YOUR code (instant)
162
- npx @animaapp/cli create -t empty --framework react --name "My project" # empty repo you push to (instant)
163
- npx @animaapp/cli create -t p2c -p "Analytics dashboard with a sidebar"
164
- npx @animaapp/cli create -t l2c -u https://stripe.com
165
- npx @animaapp/cli create -t f2c --file-key <key> --nodes 42:15
194
+ npx @animaapp/cli@latest create -t import --from ./my-project # import YOUR code (instant)
195
+ npx @animaapp/cli@latest create -t import --from ./notes --artifact-type markdown # a readable document
196
+ npx @animaapp/cli@latest create -t empty --framework react --name "My project" # empty repo you push to (instant)
197
+ npx @animaapp/cli@latest create -t p2c -p "Analytics dashboard with a sidebar"
198
+ npx @animaapp/cli@latest create -t l2c -u https://stripe.com
199
+ npx @animaapp/cli@latest create -t f2c --file-key <key> --nodes 42:15
166
200
  ```
167
201
 
168
202
  `-t import` is the one-step upload path: your folder (or .zip) becomes the
169
- playground's first commit — small text-only projects are sent inline, larger
203
+ artifact's first commit — small text-only projects are sent inline, larger
170
204
  or binary ones are zipped and uploaded via a presigned URL automatically.
171
205
  `-t empty` creates an empty repository instead: follow with `git clone` of the
172
206
  returned URL, add your code, and `git push`. Then `publish <sessionId>` for a
173
207
  live URL. The other types are AI generation (3–7 min).
174
208
 
209
+ `--artifact-type` is a separate question from `-t`: `-t` is how the repository
210
+ starts, `--artifact-type` is what the artifact IS, and it decides how a human
211
+ sees it. `app` is a running web page and needs an `index.html`; `markdown` is a
212
+ readable document and needs `.md` files. Omit it and the server infers one:
213
+ markdown when your files are `.md`/`.mdx` with no HTML, otherwise app. Getting it wrong is the common mistake — `.md` files
214
+ uploaded as an app produce an artifact with nothing to render.
215
+
175
216
  | Option | Values | Default |
176
217
  |--------|--------|---------|
177
218
  | `-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).
182
223
  | `--file-key` | Figma file key or URL | _(f2c)_ |
183
224
  | `--nodes` | Figma node IDs, comma-separated | _(f2c)_ |
184
225
  | `--figma-token` | Figma PAT (or `FIGMA_TOKEN` env) | _(f2c)_ |
185
- | `--framework` | `react`, `html` | `react` |
226
+ | `--artifact-type` | `app` (web page, needs an `index.html`), `markdown` (document, needs `.md` files), `asset` (images/video, with a zip) | _inferred from your files_ |
227
+ | `--framework` | `react`, `html` — apps only | `react` |
186
228
  | `--styling` | `tailwind`, `css`, `plain_css`, `css_modules`, `inline_styles`¹ | `tailwind` |
187
229
  | `--language` | `typescript`, `javascript` | `typescript` (react) |
188
230
  | `--ui-library` | `shadcn`, `mui`, `antd`, `clean_react` | _(none)_ |
@@ -191,10 +233,28 @@ live URL. The other types are AI generation (3–7 min).
191
233
  ¹ The valid styling / UI-library set depends on `--type`; the server validates and
192
234
  returns a clear error for unsupported combinations.
193
235
 
194
- ### `codegen` — Figma to local files (no playground)
236
+ ### `duplicate` — copy an existing artifact
195
237
 
196
238
  ```bash
197
- npx @animaapp/cli codegen --file-key <key-or-url> --nodes 42:15 -o ./components
239
+ npx @animaapp/cli@latest duplicate <artifactUrl-or-sessionId>
240
+ npx @animaapp/cli@latest duplicate <artifactUrl-or-sessionId> --name "My copy"
241
+ ```
242
+
243
+ Creates a new, independent artifact in the current team's Default workspace.
244
+ It copies code, assets, and supported database content, but does **not** copy
245
+ chat or custom domains. The source must be readable and the destination
246
+ workspace must be writable. Without `--name`, the API names it
247
+ `<source name> (Copy)`.
248
+
249
+ The result includes the new and source session IDs, duplicate name,
250
+ `playgroundUrl`, `previewUrl`, and API-provided next steps. Duplication is not
251
+ idempotent: if a request times out or its response is lost, run `list` and check
252
+ recent artifacts before retrying.
253
+
254
+ ### `codegen` — Figma to local files (no artifact)
255
+
256
+ ```bash
257
+ npx @animaapp/cli@latest codegen --file-key <key-or-url> --nodes 42:15 -o ./components
198
258
  ```
199
259
 
200
260
  | Option | Values | Default |
@@ -210,55 +270,52 @@ npx @animaapp/cli codegen --file-key <key-or-url> --nodes 42:15 -o ./components
210
270
 
211
271
  ### `publish` — deploy a session to a public URL (1–3 min)
212
272
 
213
- Publishing makes the playground **public to the world**. Sharing usually
214
- doesn't need it — the playground is already visible at its `playgroundUrl`.
273
+ Publishing makes the app **public to the world**. Sharing usually
274
+ doesn't need it — the artifact is already visible at its `playgroundUrl`.
215
275
  **Agents:** only publish when the human explicitly asked for a public site;
216
- otherwise share the playground URL and offer publishing as a follow-up.
276
+ otherwise share that URL and offer publishing as a follow-up.
217
277
 
218
278
  ```bash
219
- npx @animaapp/cli publish <sessionId>
220
- npx @animaapp/cli publish <sessionId> --mode designSystem --package-name my-ds
279
+ npx @animaapp/cli@latest publish <sessionId>
221
280
  ```
222
281
 
223
- | Option | Values | Default |
224
- |--------|--------|---------|
225
- | `--mode` | `webapp`, `designSystem` | `webapp` |
226
- | `--package-name` | npm package name | _(designSystem)_ |
227
- | `--package-version` | npm package version | _(designSystem)_ |
282
+ Deploys the artifact's app to a live URL. Publishing as a design-system npm
283
+ package is an enterprise feature and is not reachable over MCP, so this CLI
284
+ does not offer it.
228
285
 
229
- ### `unpublish` — take a published playground offline
286
+ ### `unpublish` — take a published artifact offline
230
287
 
231
288
  ```bash
232
- npx @animaapp/cli unpublish <sessionId>
289
+ npx @animaapp/cli@latest unpublish <sessionId>
233
290
  ```
234
291
 
235
292
  The inverse of `publish`: clears the live URL so the deployed site stops being
236
- reachable. The playground, its code, and its content are untouched; publishing
293
+ reachable. The artifact, its code, and its content are untouched; publishing
237
294
  again reuses the same subdomain.
238
295
 
239
296
  ### `update` — rename or change visibility (metadata only)
240
297
 
241
298
  ```bash
242
- npx @animaapp/cli update <sessionId> --name "New name"
243
- npx @animaapp/cli update <sessionId> --privacy public # anyone with the link
244
- npx @animaapp/cli update <sessionId> --privacy private # team only
299
+ npx @animaapp/cli@latest update <sessionId> --name "New name"
300
+ npx @animaapp/cli@latest update <sessionId> --privacy public # anyone with the link
301
+ npx @animaapp/cli@latest update <sessionId> --privacy private # team only
245
302
  ```
246
303
 
247
304
  Never touches code or content — that's the git flow (`get-git-token`).
248
305
 
249
- ### `get-git-token` — read/edit a playground's code over git
306
+ ### `get-git-token` — read/edit an artifact's code over git
250
307
 
251
308
  ```bash
252
- npx @animaapp/cli get-git-token https://dev.animaapp.com/chat/<sessionId>
309
+ npx @animaapp/cli@latest get-git-token https://dev.animaapp.com/chat/<sessionId>
253
310
  ```
254
311
 
255
- A playground **is** a git repository, and git is the only way to read or edit
312
+ An artifact **is** a git repository, and git is the only way to read or edit
256
313
  its code. This command mints a short-lived access token scoped to that one
257
- playground and prints a ready-to-use remote URL — you run git yourself:
314
+ artifact and prints a ready-to-use remote URL — you run git yourself:
258
315
 
259
316
  ```bash
260
317
  git clone <gitRemoteUrl> # read (and edit locally)
261
- git push # read-write access: updates the live playground
318
+ git push # read-write access: updates the live artifact
262
319
  git remote set-url origin <new url> # after expiry: re-run get-git-token, re-point the clone
263
320
  ```
264
321
 
@@ -269,14 +326,16 @@ secret, and re-mint rather than store it.
269
326
  ### `logout` — disconnect this machine
270
327
 
271
328
  ```bash
272
- npx @animaapp/cli logout
329
+ npx @animaapp/cli@latest logout
273
330
  ```
274
331
 
275
- A full local reset: clears **all** stored credentials (AgentGrid token, Figma
276
- token, agent metadata) **and the CLI config** (including an `api-url` persisted
277
- by `login --invite`) — the machine ends up pristine, as if the CLI was never
278
- used. This only forgets the token locally — to actually disable an agent,
279
- revoke it from your team settings.
332
+ A full reset: revokes the agent credentials server-side, then clears **all**
333
+ stored credentials (AgentGrid token, Figma token, agent metadata) **and the CLI
334
+ config** (including an `api-url` persisted by `login --invite`) — the machine
335
+ ends up pristine, as if the CLI was never used. Because the revocation is
336
+ server-side, a copy of the token taken from this machine stops working too.
337
+ The agent identity itself remains on your team roster; revoke it there to retire
338
+ it for good.
280
339
 
281
340
  ### `config` — store CLI preferences
282
341
 
@@ -286,10 +345,10 @@ Note: `logout` removes this file too (full machine reset); `login --invite`
286
345
  writes `api-url` automatically from the invite URL's origin.
287
346
 
288
347
  ```bash
289
- npx @animaapp/cli config set api-url http://localhost:3789
290
- npx @animaapp/cli config get api-url
291
- npx @animaapp/cli config list
292
- npx @animaapp/cli config unset api-url
348
+ npx @animaapp/cli@latest config set api-url http://localhost:3789
349
+ npx @animaapp/cli@latest config get api-url
350
+ npx @animaapp/cli@latest config list
351
+ npx @animaapp/cli@latest config unset api-url
293
352
  ```
294
353
 
295
354
  The API URL resolves in this order: **`--api-url` flag → `ANIMA_API_URL` env →
@@ -298,17 +357,17 @@ The API URL resolves in this order: **`--api-url` flag → `ANIMA_API_URL` env
298
357
  ### `auth` — inspect or manage credentials
299
358
 
300
359
  ```bash
301
- npx @animaapp/cli auth --status # token type + expiry
302
- npx @animaapp/cli auth --figma-token <T> # save a Figma token for codegen / f2c
303
- npx @animaapp/cli auth --logout # alias for `anima logout`
360
+ npx @animaapp/cli@latest auth --status # token type + expiry
361
+ npx @animaapp/cli@latest auth --figma-token <T> # save a Figma token for codegen / f2c
362
+ npx @animaapp/cli@latest auth --logout # alias for `anima logout`
304
363
  ```
305
364
 
306
365
  ---
307
366
 
308
367
  ## Global flags
309
368
 
310
- Available on the network commands (`login`, `create`, `codegen`, `publish`,
311
- `get-git-token`):
369
+ Available on the network commands (`login`, `create`, `duplicate`, `codegen`,
370
+ `publish`, `get-git-token`):
312
371
 
313
372
  | Flag | Description | Default |
314
373
  |------|-------------|---------|
@@ -318,7 +377,8 @@ Available on the network commands (`login`, `create`, `codegen`, `publish`,
318
377
  | `--log-file <path>` | Append a JSON debug log of each step to a file | off |
319
378
  | `--timeout <ms>` | Request timeout² | `600000` (10 min) |
320
379
 
321
- ¹ `--verbose` applies to `create` / `codegen` / `publish` / `get-git-token`.
380
+ ¹ `--verbose` applies to `create` / `duplicate` / `codegen` / `publish` /
381
+ `get-git-token`.
322
382
  ² `--timeout` applies to `create` / `codegen`. Don't lower it — generation takes
323
383
  minutes.
324
384
  ³ Falls back to `ANIMA_API_URL`, then `anima config set api-url`, then the
@@ -334,7 +394,7 @@ default. Set it once with `config` instead of passing `--api-url` every time.
334
394
  a clean, parseable result.
335
395
 
336
396
  ```bash
337
- npx @animaapp/cli create -t p2c -p "dashboard" --json 2>/dev/null | jq .playgroundUrl
397
+ npx @animaapp/cli@latest create -t p2c -p "dashboard" --json 2>/dev/null | jq .playgroundUrl
338
398
  ```
339
399
 
340
400
  ---
@@ -346,7 +406,7 @@ HTTP requests/responses, MCP connect and tool calls, and errors — to a file yo
346
406
  can inspect or share. Tokens and auth headers are redacted.
347
407
 
348
408
  ```bash
349
- npx @animaapp/cli login --log-file ./anima-debug.log
409
+ npx @animaapp/cli@latest login --log-file ./anima-debug.log
350
410
  ```
351
411
 
352
412
  **`HTTP 404` on `login`** means the API at `--api-url` doesn't have the device