# Driving DesignCraft from agents and scripts

Every user-visible action in DesignCraft is a command (`crates/engine/src/cmd`), and every command is reachable
three ways — pick whichever fits the agent:

| Surface | Use it when | Entry point |
|---|---|---|
| **CLI** | One-shot jobs, shell pipelines, CI: build or edit a document and export it | `designcraft-cli run`, `script`, `app`, `describe`, `commands` |
| **MCP** | Claude and other MCP clients; images of pages and the window come back as content | `designcraft-cli mcp` ([mcp.md](mcp.md)) |
| **Control channel** | Your own client driving the running app (JSON lines over TCP) | `designcraft --control 7979` ([control-protocol.md](control-protocol.md)) |

## Discover commands

```sh
designcraft-cli commands footnote        # every command whose id/label/menu mentions "footnote"
designcraft-cli describe xref.insert     # label, menu path, shortcut and parameters of one command
```

Parameters are documented on each command (`params`), e.g. `{anchor? | paragraph?: text to find | story? + para?, format?}`.

## Scripts: several commands, later ones using earlier results

A script is one command per line (`command.id {json params}`; `#` comments), JSON lines, or a JSON array of
`{command, params}`. A parameter string `"$N.path"` becomes that value of step N's result (0-based, `$last` for the
previous step); `"${N.path}"` interpolates inside longer strings.

```sh
cat > page.dcs <<'DCS'
frame.create {"rect": [72, 72, 540, 300], "content": "text", "text": "Results of the survey"}
text.select  {"story": "$0.story", "anchor": 0, "focus": 0}
footnote.insert {"text": "Survey run in 2026."}
frame.create {"rect": [72, 320, 540, 500], "content": "text", "text": "See ."}
text.select  {"story": "$3.story", "anchor": 4, "focus": 4}
xref.insert  {"paragraph": "Results", "format": "Paragraph Text & Page Number"}
DCS
designcraft-cli script page.dcs --save page.designcraft --export page.pdf --export page.png
designcraft-cli script page.dcs --connect 7979      # the same steps, live in the running app
```

The result is JSON: `{"completed": n, "results": [...]}`, plus `failedIndex` / `failedCommand` / `error` when a step
fails (the exit status is non-zero; `--keep-going` records errors and continues). `run --cmd ID=JSON` accepts the
same references, and MCP's `batch` tool takes `commands` or `script` text with them.

## The running app

```sh
designcraft --sample --control 7979 &
designcraft-cli app type.changeCase '{"case": "title"}'            # any command
designcraft-cli app --method ui.screenshot '{"path": "/tmp/w.png"}' # any control-channel method
```

`ui.menu.invoke {command}` without params acts like choosing the menu item: a command labelled "…" opens its
dialog, which `ui.dialog.set` / `ui.dialog.confirm` fill in and close like a user would.