# Use a canvas board

Make a canvas board, add and wire its boxes, check it, and make what the boxes describe.

A canvas board is one file of boxes joined by wires. A box holds a picture, a video, a voice, a note or an uploaded file. A wire feeds one box's result into the next. Your agent edits the file with `minicut board` commands, and the open **画布** tab in the MiniCut app redraws by itself.

Before you start, sign in and make a project. See [Quickstart](/docs/cli/quickstart). Every command here needs a signed-in computer. Run them in the project folder, `~/.minicut/projects/rain-shop` here.

## Make the board

1. Make a board for episode 1:

```bash Terminal
minicut board new --project rain-shop --episode ep01 --title "Opening"
```

```text Output
Board: ~/.minicut/projects/rain-shop/episodes/ep01/canvas/opening.board.json
```

The file name comes from the title. Without `--project` and `--episode`, the board gets its own folder in your MiniCut home folder.

## Add and set the boxes

1. Find a model for each box that makes something. `minicut models --kind image` and `minicut models --kind video` list them. No model is chosen for you. Ask the person which one to use.
2. Add a picture box for a character. A box id is `KIND:ID`, so this one is `character:lin`.

```bash Terminal
minicut board add episodes/ep01/canvas/opening.board.json --kind character --id lin --label Lin --prompt "Lin Xia, shop owner, front view, plain background" --model IMAGE_MODEL
```

```text Output
Board add: ok, rev 2, box character:lin.
```

3. Add a video box for a shot:

```bash Terminal
minicut board add episodes/ep01/canvas/opening.board.json --kind video --id s01 --label "Shot 1" --prompt "She walks into the rain." --model VIDEO_MODEL
```

4. Set the length of the shot in seconds:

```bash Terminal
minicut board set episodes/ep01/canvas/opening.board.json --box video:s01 --seconds 5
```

```text Output
Board set: ok, rev 4.
```

The box kinds are `character`, `location`, `prop`, `voice`, `note`, `upload`, `group`, `text`, `image`, `video`, `audio`, `editor`, `director`, `model3d` and `script`. The kinds that make something are `image`, `character`, `location`, `prop`, `video`, `audio` and `voice`. A `note` or `text` box holds words.

## Wire the boxes

1. Feed the character into the shot:

```bash Terminal
minicut board connect episodes/ep01/canvas/opening.board.json --from character:lin --to video:s01
```

```text Output
Board connect: ok, rev 5.
```

2. If a wire is not allowed, the command exits with code 1 and says why. For example, `a video box cannot feed a character box (video:s01 -> character:lin)`.
3. Optional: to remove a wire, run `minicut board disconnect` with the same flags.

## Check the board

1. Check the board for problems:

```bash Terminal
minicut board check episodes/ep01/canvas/opening.board.json
```

```text Output
Board ok: 2 boxes, 1 wires.
```

`check` finds boxes with the same id, wires to missing boxes, wires that are not allowed, and upload files outside the board folder.

It prints one line for each problem and exits with code 1.

## Make the boxes

This step uses credits. It shows what it will do and asks before it spends.

1. Ask to make the character box:

```bash Terminal
minicut board run episodes/ep01/canvas/opening.board.json --box character:lin
```

2. The command sends nothing. It exits with code 3 and prints what it will do and the exact line to run after the person says yes. Show it to the person.
3. After the yes, run the line it printed. Add `--wait SECONDS` to it to wait and save the result.
4. If you did not wait, run `minicut jobs` later. It saves each finished result onto its box.
5. Run the video box the same way. A box whose wired input is not made yet waits. `--box` refuses it and names the box to make first. `--all` makes every box that is empty or failed and leaves the waiting ones for the next run.

A box that is refused keeps its reason on the board, and the other boxes still go. If the board changes after the yes, the command needs a new yes.

## Change the board

| Command | What it does |
|---|---|
| `minicut board move FILE --box BOX --x N --y N` | Moves a box |
| `minicut board set FILE --box BOX [--label L] [--prompt P] [--text T] [--model M] [--seconds N]` | Changes a box |
| `minicut board view FILE --view VIEW` | Sets how the board is laid out. `VIEW` is `workflow` or `storyboard` |
| `minicut board retype FILE --box BOX --kind KIND` | Tells a picture box what it is. `KIND` is `character`, `location` or `prop` |
| `minicut board delete FILE --box BOX` | Removes a box and its wires |

Every edit prints `Board COMMAND: ok, rev N.` and raises the board's revision by 1. The flags are on [Generate](/docs/cli/generate#minicut-board).

## Check it worked

`minicut board check` prints `Board ok`. Each box you made has the state `done` and an `artifactUrl` in the board file.

## If a step fails

| Message | What to do |
|---|---|
| `no box video:nope on the board` | Check the box id. It is `KIND:ID` |
| `no box kind "nope". Kinds: ...` | Use a kind from the list in the message |
| `a video box cannot feed a character box (...)` | Wire the boxes the other way, or add a box between them |
| `box character:lin has no modelId. Ask the user which model to use; ...` | Set a model with `minicut board set FILE --box BOX --model MODEL` |
| `not a board file: FILE. A board is <name>.board.json.` | Give the path of the `.board.json` file |
| `no board at FILE` | Check the path |
| `box video:s01 needs the output of character:lin first: ...` | Make that box, run `minicut jobs`, then run this one |

## Next

[Generate](/docs/cli/generate) [Manage assets](/docs/cli/manage-assets) [Global options](/docs/cli/global-options)