<!-- enhance-docs page=reference/cli/canvas/edit -->
<!-- enhance-docs release-sha256=8a804cfc9a6fc6b942b8daf6a82266ad6e308291ae4351abee3346bc696d1258 -->

# enhance-dev canvas edit

```text
enhance-dev canvas edit [options]
```

## Arguments

This command takes no positional arguments.

## Options

| Option | Required | Default | Meaning |
| --- | --- | --- | --- |
| `--canvas <url-or-id>` | Yes | None | Canvas or selection URL, or canvas UUID. |
| `--base-version <integer>` | Yes | None | Document version returned by `enhance canvas document get`. |
| `--edits <json-or-@path>` | Yes | None | Array of edits with kind set_text, set_styles, rename, duplicate or move. |
| `--client-token <uuid>` | No | None | Stable UUID to reuse when retrying the exact same mutation. |

## Input

This command presents the capability `canvas.edit`. It has write effect and single idempotency.

<details class="reference-schema">
<summary>Show complete input JSON Schema</summary>

```json
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"canvas":{"type":"string","minLength":1,"description":"Canvas UUID or full canvas/selection URL; selection limits the entire edit batch."},"baseVersion":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Exact version to edit, including the version returned by a previous successful write."},"edits":{"minItems":1,"type":"array","items":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","const":"set_text"},"nodeId":{"type":"string","minLength":1},"text":{"type":"string"}},"required":["kind","nodeId","text"]},{"type":"object","properties":{"kind":{"type":"string","const":"set_styles"},"nodeIds":{"minItems":1,"type":"array","items":{"type":"string","minLength":1}},"styles":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"null"}]}}},"required":["kind","nodeIds","styles"]},{"type":"object","properties":{"kind":{"type":"string","const":"rename"},"nodeId":{"type":"string","minLength":1},"name":{"type":"string","minLength":1}},"required":["kind","nodeId","name"]},{"type":"object","properties":{"kind":{"type":"string","const":"duplicate"},"nodeIds":{"minItems":1,"type":"array","items":{"type":"string","minLength":1}},"parentId":{"type":"string","minLength":1}},"required":["kind","nodeIds"]},{"type":"object","properties":{"kind":{"type":"string","const":"move"},"nodeId":{"type":"string","minLength":1},"destination":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","const":"before"},"nodeId":{"type":"string","minLength":1}},"required":["kind","nodeId"]},{"type":"object","properties":{"kind":{"type":"string","const":"after"},"nodeId":{"type":"string","minLength":1}},"required":["kind","nodeId"]},{"type":"object","properties":{"kind":{"type":"string","const":"parent"},"parentId":{"type":"string","minLength":1},"index":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["kind","parentId"]}]}},"required":["kind","nodeId","destination"]}]},"description":"Sequential text, style, rename, duplicate or move edits, committed atomically. Target existing node IDs."}},"required":["canvas","baseVersion","edits"]}
```
</details>


## Output

This command writes JSON records to standard output. Returns a typed canvas.edit result from the Enhance API without transport-specific prose.

[Show complete output JSON Schema (JSON file)](/docs/reference/mcp/canvas-edit.output-schema.json)


## Examples

```bash
enhance-dev canvas edit --canvas <url-or-id> --base-version <integer> --edits <json-or-@path>
```

<details class="reference-schema">
<summary>Show example input</summary>

```json
{
 "canvas": "00000000-0000-4000-8000-000000000010",
 "baseVersion": 1,
 "edits": [
  {
   "kind": "set_text",
   "nodeId": "text_title",
   "text": "Today"
  }
 ]
}
```
</details>

<details class="reference-schema">
<summary>Show example output</summary>

```json
{
 "canvasId": "00000000-0000-4000-8000-000000000010",
 "mutationId": "00000000-0000-4000-8000-000000000010",
 "previousVersion": 1,
 "version": 2,
 "operations": [
  {
   "op": "setText",
   "nodeId": "text_title",
   "text": "Today"
  }
 ],
 "insertedNodeIds": [],
 "changedNodeIds": [
  "text_title"
 ],
 "removedNodeIds": [],
 "boxes": {},
 "affectedBounds": null,
 "next": []
}
```
</details>

## Exit behaviour

| Exit code | Meaning |
| --- | --- |
| `0` | The command succeeded. |
| `1` | The command failed for another reason (`INTERNAL`). A write may have an unknown outcome. |
| `2` | The command line was malformed. Nothing ran. |
| `3` | The API refused the input (`BAD_REQUEST`). |
| `4` | The credential is missing or expired (`UNAUTHORIZED`). |
| `5` | The API refused the request (`FORBIDDEN`, `NOT_FOUND`, `CONFLICT`, `RATE_LIMITED`). |
| `6` | A batch finished only in part. Retry with the same `--client-token`. |

## Versions

Minimum tested versions: Enhance CLI and MCP runtime 0.1.40, plugin 1.0.38, Node.js 24. No older floor is published.