canvas-operations

name	canvas-operations
description	Use when the user wants to read, modify, search, add, or delete nodes on a project's canvas. Triggers on "canvas", "scene", "node", "add a clip", "edit the timeline", "what's in the canvas", "rearrange", "remove the X". Use the `clash canvas` CLI subcommands; always pass `--json` for parseable output.

Canvas operations

The canvas is a Loro CRDT-backed graph of nodes that represent scenes, generated assets, prompts, and other primitives in the user's video project. Edits sync back to the user's browser in real time.

First step: connect to the project

Before any read/write, establish the canvas connection in this terminal:

clash canvas connect --project <project-id>

This starts a daemon-mode sync session for that project. Subsequent canvas commands can resolve the project from the managed cwd marker, but pass --project in reusable scripts and examples so the target is unambiguous. When you're done with a project (e.g. switching to a different one), run clash canvas disconnect --project <project-id>.

Reading the canvas

clash canvas list --project <project-id> --json
clash canvas list --project <project-id> --type text --json
clash canvas search --project <project-id> --query "<text>" --json
clash canvas get --project <project-id> --node <node-id> --json
clash canvas edges --project <project-id> --json
clash canvas delete-plan --project <project-id> --node <node-id> --node <node-id> --json

Use list (or filtered list --type) for an overview, search when the user references something by content rather than id, and get when you need a node's full payload (e.g. inputs to an action node). get --json records the observed node version in .clash/observed.json and exposes whether the node is immutable. edges and delete-plan record their graph versions the same way. Versions are internal CLI state, not command arguments.

The user can see the canvas live in their browser — don't paraphrase its full state back to them. Cite what's relevant to the question.

Adding a node

clash canvas add --project <project-id> --type text --label "<label>" --content "<text>" --json
clash canvas add --project <project-id> --type text --label "<label>" --content "<text>" --parent <group-id> --json

Without --parent, the node lands at the root. Choose an explicit node type instead of relying on inference. Returns the new id.

Editing

clash canvas update --project <project-id> --node <node-id> --label "<new label>" --json
clash canvas update --project <project-id> --node <node-id> --content "<new content>" --json
clash canvas copy --project <project-id> --node <node-id> --json
clash canvas replace-asset --project <project-id> --node <media-node-id> --asset <asset-id> --json

Update only the fields you want to change. For agents, always read with clash canvas get --json first. The CLI checks the cwd observation and current canvas version automatically; on STALE_READ, re-read and reconcile before retrying. If the read reports immutable: true, an in-place update returns IMMUTABLE_NODE; use canvas copy, then edit the copy. Use replace-asset for fulfilled image/video/audio asset changes; it creates a copy-on-write node and leaves existing downstream references on the old node. Re-get after if you need to verify the result.

Executing an action node

clash canvas execute --project <project-id> --node <node-id> --json

Some nodes are "actions" (image generation, edit ops). Executing returns a task id you can hand to the generation skill (clash tasks wait) to track the result.

Deleting

clash canvas delete --project <project-id> --node <node-id> --yes --json
clash canvas delete-batch --project <project-id> --node <node-id> --node <node-id> --yes --json

Always confirm with the user before deleting. Quote the node's label back so they can verify which one you mean. The CLI requires --yes as the machine-readable confirmation flag. Read the node first. For multiple nodes, run delete-plan --json before delete-batch; the CLI uses the recorded graph version automatically. If the CLI reports downstream references or STALE_READ, do not retry with an overwrite bypass. Re-read and reconcile the newer state. Remove or rewire downstream references first, or use the explicit copy-on-write replacement workflow when existing outputs must stay pinned.

Conventions

• Concurrent edits: the user can edit the canvas in the browser at the same time. Re-get before direct or destructive writes and use delete-plan before delete-batch. The CLI performs CAS from cwd state.
• Don't loop list to poll for changes — Loro syncs in the background; the next read picks up everything.
• Keep your output terse. The user can see the canvas; they want what changed and what's next, not a node-by-node enumeration.