@oiioii/cli 0.1.7 → 0.1.8

package/README.md

@@ -17,14 +17,18 @@ human-readable output and a stable JSON envelope for AI agents and automation.
 | `auth logout` | Remove locally persisted authentication without exposing the API Key | Implemented |
 | `workspace create/set/current/rename` | Create, configure, inspect, and rename workspaces | Implemented |
 | `workspace assets list/download` | List workspace assets and download ready resources | Implemented |
-| `library list/search` | Query and search reusable role, scene, and item assets | Implemented |
+| `workspace canvas create` | Create ordered blank nodes, prompts, references, and groups without client-side layout | Implemented |
+| `workspace canvas node update` | Update prompt, generation parameters, and references on an empty canvas node | Implemented |
+| `workspace canvas group create` | Group two or more existing canvas nodes without changing their layout | Implemented |
+| `library create/list/search/members` | Create and query role, scene, item, and collection assets, including collection members | Implemented |
 | `image text` | Text-to-image generation | Implemented |
 | `image edit` | Image-to-image editing | Implemented |
 | `video text` | Text-to-video generation | Implemented |
 | `video image` | Image-to-video generation | Implemented |
 | `video generate` | Model-validated mixed image/video/audio reference generation | Implemented |
 | `audio generate` | Seed Audio and Suno audio/music generation | Implemented |
-| `upload file` | Upload local image/video/audio resources | Implemented |
+| `upload resource` | Upload image/video/audio resources without a workspace | Implemented |
+| `upload file` | Upload image/video/audio and attach it to a workspace | Implemented |
 | `record get/open` | Query generation metadata and download resources | Implemented |
 | `inspect capabilities/models` | Inspect declared capabilities and live backend models | Implemented |
 | `preview latest/bundle` | Read local preview bundles created by generation commands | Implemented |
@@ -42,14 +46,15 @@ Important current limitations:
 - REST metadata requests time out after 30 seconds; raw resource uploads/downloads use a 5-minute transfer timeout, and VOD transcode polling has a 10-minute overall deadline.
 - Image, video, and audio generation create local preview bundles after a queried task reaches a terminal state.
 - `inspect capabilities` is local metadata; `inspect models` requires authentication and queries the active backend.
-- Asset-library update/delete and style-library commands are not available. Reusable asset query/search and workspace-scoped asset listing/download are available.
+- Style-library mutation commands are not available. Reusable asset creation, query, update, deletion, collection membership management, and workspace-scoped asset listing/download are available.
 
 ## Requirements
 
 - Node.js 18.18 or newer when running from source or the npm package.
 - A Hogi account for browser authorization, or an existing Hogi MCP API Key.
-- A workspace ID for image/video/audio generation and resource upload. It can be
+- A workspace ID for image/video/audio generation and `upload file`. It can be
   created with `oiioii workspace create` or supplied from an existing project.
+  `upload resource` does not require a workspace.
 - `npm` is the repository package manager.
 
 The hosted installer uses Node.js 18.18 or newer when available. If no compatible
@@ -276,17 +281,137 @@ oiioii workspace assets download <asset_id> --output ./downloads --json
 identity to the asset's downloadable `uri`; loading, uploading, empty, failed,
 or URI-less assets fail before the download request.
 
-Query or search reusable library assets before generation:
+Create blank canvas nodes and groups from a JSON file. The file contains only
+composition data; select the workspace with the normal root option, environment
+variable, local default, or the optional command argument:
+
+```json
+{
+  "nodes": [
+    {
+      "client_id": "cover",
+      "type": "image",
+      "title": "Cover",
+      "prompt": "A cat based on @图片1 in a neon street",
+      "generation_config": {
+        "mcp_method_name": "generate_image_nanopro",
+        "model_version": "nano-banana-pro",
+        "ratio": "16:9",
+        "resolution": "2k",
+        "quality": "high"
+      },
+      "references": [
+        { "kind": "media", "media_type": "image", "uri": "hogi://image/cat.png" }
+      ]
+    },
+    { "client_id": "motion", "type": "video", "title": "Motion" }
+  ],
+  "groups": [
+    {
+      "client_id": "story",
+      "title": "Story",
+      "members": [
+        { "client_node_id": "motion" },
+        { "client_node_id": "cover" }
+      ]
+    }
+  ]
+}
+```
 
 ```bash
+oiioii workspace canvas create --input ./composition.json --json
+oiioii workspace canvas create <workspace_id> \
+  --input ./composition.json \
+  --idempotency-key canvas-request-1 \
+  --json
+```
+
+Node order follows `nodes`; `groups[].members` controls group membership order.
+The CLI does not accept coordinates or compute layout. Use the same explicit
+idempotency key only when replaying the same uncertain request. Optional
+`generation_config` caches the empty node's model selection and generation
+parameters for the existing Web editor. It accepts `mcp_method_name`,
+`model_version`, `ratio`, `duration`, `resolution`, and `quality`; a
+`model_version` requires a matching `mcp_method_name`.
+For create and node update, indexed prompt mentions are converted by the CLI to
+the self-contained protocol used by the Web canvas before the request is sent.
+`@图N` / `@图片N` address image and role/scene/item references, while
+`@音频N` and `@视频N` address their own media reference sequences. For example,
+`@图片1` with `hogi://image/cat.png` becomes `[Image:image/cat.png]`.
+Unresolved indexes remain unchanged. OpenAPI/curl callers must send the
+self-contained protocol directly; this shorthand is a CLI-only capability.
+
+Group two or more existing canvas nodes by their asset IDs:
+
+```bash
+oiioii workspace canvas group create <asset_id_1> <asset_id_2> \
+  --title "Story" \
+  --workspace-id <workspace_id> \
+  --idempotency-key group-request-1 \
+  --json
+```
+
+The command rejects duplicate members and nodes that already belong to another
+group. It changes group membership only: it does not move nodes, compute a
+layout, or accept coordinates. Reuse an idempotency key only for the identical
+workspace, member order, and title.
+
+Update an existing empty node with explicit field options:
+
+```bash
+oiioii workspace canvas node update <asset_id> \
+  --workspace-id <workspace_id> \
+  --prompt "Use @图片1: a cat looking through a rainy window" \
+  --model "Nano Pro" \
+  --variant "nano-banana-pro" \
+  --ratio "16:9" \
+  --quality high \
+  --reference 'hogi://image/<reference-id>' 'hogi://role_asset/<role-id>' \
+  --json
+```
+
+`--model` and optional `--variant` resolve through the active model catalog;
+`--model-id` selects the catalog row directly. Use `--clear-prompt`,
+`--clear-model`, `--clear-ratio`, `--clear-duration`, `--clear-resolution`,
+`--clear-quality`, or `--clear-references` for explicit clears. Omitted options
+keep their existing values. The server accepts this operation only when the
+global `enable_cli_empty_canvas_node_update` flag is enabled for the caller and
+the current asset status is `empty`. URI, status, type, position, title, group,
+and raw metadata updates are not accepted. Completed, loading, uploading, and
+failed nodes are rejected.
+
+Create, query, or search reusable library assets before generation:
+
+```bash
+oiioii library create role --name "Hero" --emo-image 'hogi://image/<expression-id>' --json
+oiioii library create collection --name "Cast" --member 'hogi://role_asset/<id>' 'group:<id>' --json
+oiioii library create scene --input ./scene.json --idempotency-key scene-import-001 --json
 oiioii library list role --limit 20 --json
+oiioii library list collection --limit 20 --json
 oiioii library search role "球球" --limit 20 --json
+oiioii library search collection "主要角色" --limit 20 --json
 oiioii library search scene "森林" --cursor '<next_cursor>' --json
+oiioii library members <collection-id> --type role --keyword "主角" --limit 20 --json
+oiioii library members <collection-id> --cursor '<next_cursor>' --json
+oiioii library add-members <collection-id> 'hogi://role_asset/<id>' 'group:<id>' --json
+oiioii library remove-members <collection-id> 'hogi://role_asset/<id>' 'group:<id>' --json
 ```
 
+Collection list items use their `asset_id` as the stable identity and return
+`asset_uri: null`. They include `member_count` without expanding the complete
+member list. Use `next_cursor` with `--cursor` to continue pagination.
+`library members` returns normalized role, scene, item, and group entries. Each
+entry includes an `asset_ref` that can be passed directly to collection member
+commands (`hogi://<type>_asset/<id>` or `group:<id>`).
+`library remove-members` is idempotent and applies removals against the latest
+Backend collection state instead of fetching and replacing the full member list
+from the CLI.
+
 Use the returned `asset_uri` with `--asset`, or bind a prompt mention explicitly
 with `--bind <name=asset-uri>`. Explicit bindings avoid silently selecting the
 wrong asset when the library contains duplicate display names.
+Reuse the returned `idempotency_key` when retrying an uncertain create request.
 
 Workspace resolution order is:
 
@@ -322,6 +447,13 @@ oiioii image edit \
   --json
 ```
 
+For GPT Image 2, add `--transparent` to either `image text` or `image edit`
+to request a transparent-background PNG. Other models reject this option.
+
+```bash
+oiioii image text --prompt "an isolated sticker" --model gpt-image2 --transparent --json
+```
+
 Current behavior:
 
 - Accepts `--model-id <id>` from `inspect models` for exact backend model
@@ -481,6 +613,12 @@ record, and creates the terminal preview bundle. The CLI does not issue a second
 Upload image, video, or audio bytes:
 
 ```bash
+# Pure resource upload for library/collection inputs; no workspace required
+oiioii upload resource ./image.png --json
+oiioii upload resource ./clip.mp4 --json
+oiioii upload resource ./voice.mp3 --json
+
+# Upload and attach to the active workspace
 oiioii upload file ./image.png --json
 oiioii upload file ./clip.mp4 --json
 oiioii upload file ./voice.mp3 --json
@@ -503,6 +641,11 @@ oiioii upload file ./voice.mp3 --after-asset-id <asset_id> --json
 
 Upload behavior:
 
+- `upload resource` uploads small media through `POST /v1/res/uploadFile` and returns
+  only the reusable resource URI; it does not read or update a workspace.
+- MOV files and videos of 10 MB or larger use the standalone VOD flow for
+  `upload resource`: `media_uploads/prepare` -> direct VOD upload -> `commit` -> `status`.
+- `upload file` preserves the original workspace-bound behavior below.
 - Images, audio, and videos smaller than 10 MB use raw `application/octet-stream` bytes at
   `POST /v1/workspace/uploadAsset` with `workspace_id`, `file_type`, and optional
   `file_name` / `after_asset_id` query parameters.
@@ -523,7 +666,7 @@ Upload behavior:
 - `--attach` is retained as a no-op compatibility flag because uploads are now
   always attached.
 - A storage or workspace-write failure fails the upload command.
-- Arbitrary documents and URL uploads are outside the current scope.
+- Arbitrary URL uploads are outside the current scope.
 
 Supported extensions: