# Checks and loops

Commands that check each file and take against the standard, and run the 5 loops that make, check and fix the episode.

Every command on this page needs a signed-in computer. Signed out, each one prints `You are not signed in. Ask your agent to run minicut login.` and exits with code 10. Flags every command takes, and every exit code, are on [Global options](/docs/cli/global-options).

The checks run on your own computer. Each check prints every failure with its fix, so your agent can fix it and run the check again. The loops run these checks in rounds, as the [Overview](/docs/cli/overview) shows.

## minicut check STEP

Checks one step's file against its standard and writes the result beside it.

### Usage

```text Usage
minicut check STEP FILE [OPTIONS] [--ignore CHECKS]
```

Replace the following:

- `STEP`: the step number, from the table below.
- `FILE`: the file or folder that step checks.
- `OPTIONS`: the options for that step, from the table below.
- `CHECKS`: the names of the failing checks to ignore, separated by commas.

### Details

Each step of an episode has its own check. Your agent runs it after it writes the step's file, and fixes what fails.

| Step | Loop | Checks | `FILE` | Options |
|---|---|---|---|---|
| 1 | Script | Researched idea | the idea document, `.md` | none |
| 2 | Script | Story and world document | the story document, `.md` | `--format {one-off\|series-episode\|series}` |
| 3 | Script | Episode script | `script.md` | `--soft-only` |
| 4 | Shot sheet | Shot sheet | `shots.md` | `--model MODEL` |
| 5 | Shot sheet | Asset list and sheet prompts | `assets.md` | `--sheet shots.md`, `--version VERSION`, `--model MODEL` |
| 6 | Shot sheet | Shot prompts | `prompts.md` | `--assets assets.md`, `--sheet shots.md`, `--model MODEL`, `--root FOLDER`, `--strict` |
| 10 | Mock and Edit | Editor timeline | the episode folder | `--target SECONDS`, `--tol SECONDS` |

Steps 4, 5 and 6 need `--model` with the video model you picked, because each video model has its own shortest and longest shot. No model is a default. `minicut models --kind video` lists them.

`--ignore` lets you keep a failing check on purpose. Only the checks you name stop counting, and the ignore is written to the step's checks file with the date. A missing sheet or picture that a video take needs can never be ignored.

### Options

| Flag | Type | Default | Description |
|---|---|---|---|
| `--model` | name | none | The video model. Needed for steps 4, 5 and 6 |
| `--sheet` | file | none | Steps 5 and 6: the shot sheet |
| `--assets` | file | none | Step 6: the asset list |
| `--format` | format | none | Step 2: one episode, an episode of a series, or a whole series |
| `--soft-only` | switch | off | Step 3: show only the soft checks |
| `--strict` | switch | off | Step 6: a picture file named in a prompt that is not on disk yet is a FAIL, not a note. Use it before a real paid run |
| `--target` | seconds | none | Step 10: the episode's target length |
| `--tol` | seconds | none | Step 10: how far from the target the length may be |
| `--ignore` | check names | none | Keep these failing checks on purpose |

### Examples

#### Check the shot sheet

```bash Terminal
minicut check 4 shots.md --model MODEL
```

Replace `MODEL` with the video model you picked.

### Output

One line per check that failed, with its fix, then a result line and the path of the checks file:

| Result line | Meaning | Exit code |
|---|---|---|
| `RESULT: PASS` | Every hard check passed. Soft warnings are counted on the same line | 0 |
| `RESULT: FAIL` | Hard checks failed. The line gives how many | 1 |
| `RESULT: NOT RUN` | The check could not run. The reason is above it | 2 |
| `RESULT: REFUSED` | `--ignore` named a check that can never be ignored | 5 |

### Errors

| Message | What to do |
|---|---|
| `not a step: <step>.` | Use a step number from the table, or one of the named checks below |
| `file not found: <file>` | Check the path |
| `no Python 3 found. Run: minicut setup` | Run `minicut setup` |

### See also

[minicut loop run](#minicut-loop-run), [minicut script](/docs/cli/projects#minicut-script)

## minicut check take

Checks one video take of a shot and prints each failure with its fix.

### Usage

```text Usage
minicut check take CLIP_FOLDER [--take TAKE] [--json]
```

Replace the following:

- `CLIP_FOLDER`: the shot's folder, such as `episodes/ep01/clips/c03`.
- `TAKE`: a take id such as `t02`.

### Details

With no `--take`, the command checks the newest take. It saves the result beside the take. A shot with no take fails, and the fix names the `minicut gen video` command to make one.

### Options

| Flag | Type | Default | Description |
|---|---|---|---|
| `--take` | take id | the newest take | The take to check |
| `--json` | switch | off | Print the result as one JSON object |

### Examples

#### Check the newest take of shot 3

```bash Terminal
minicut check take episodes/ep01/clips/c03
```

### Output

The shot, the take, its kind and its length, then one `FAIL` line per failure with a `fix:` line under it, then `RESULT: PASS` or `RESULT: FAIL`. With `--json`, the result is one object with `result` and a `failures` list, each with `check`, `message` and `fix`. Exit codes: 0 when it passes, 1 when it fails, 2 when the folder is not a shot folder.

### See also

[minicut gen video](/docs/cli/generate#minicut-gen-video), [minicut check zoom](#minicut-check-zoom)

## minicut check mock

Checks the whole mock of an episode: every shot's picture, every line's voice, and the music.

### Usage

```text Usage
minicut check mock EPISODE_FOLDER [--json]
```

Replace the following:

- `EPISODE_FOLDER`: the episode folder, such as `episodes/ep01`.

### Details

The mock is the whole episode as still pictures with voices, music and captions. The check compares its length with the target, and saves the result in the episode folder. It also asks for a person to look at one frame of every shot and answer its questions.

### Options

| Flag | Type | Default | Description |
|---|---|---|---|
| `--json` | switch | off | Print the result as one JSON object |

### Examples

#### Check the mock of episode 1

```bash Terminal
minicut check mock episodes/ep01
```

### Output

The episode's length against its target, the failures with their fixes, then `RESULT: PASS` or `RESULT: FAIL`. Exit codes: 0 when it passes, 1 when it fails, 2 when the folder is not an episode folder.

### See also

[minicut loop run](#minicut-loop-run), [minicut check captions](#minicut-check-captions)

## minicut check render

Checks a finished video file of an episode.

### Usage

```text Usage
minicut check render EPISODE_FOLDER RENDER_FILE [--json]
```

Replace the following:

- `EPISODE_FOLDER`: the episode folder, such as `episodes/ep01`.
- `RENDER_FILE`: the finished video file, such as `renders/ep01.mp4`.

### Details

The check saves its result beside the video file, with the same name and `.verdict.json` on the end.

### Options

| Flag | Type | Default | Description |
|---|---|---|---|
| `--json` | switch | off | Print the result as one JSON object |

### Examples

#### Check the finished episode

```bash Terminal
minicut check render episodes/ep01 episodes/ep01/renders/ep01.mp4
```

### Output

The failures with their fixes, then `RESULT: PASS` or `RESULT: FAIL`. Exit codes: 0 when it passes, 1 when it fails, 2 when a path is wrong.

### See also

[minicut loop run](#minicut-loop-run)

## minicut check captions

Checks that every caption is placed, split, timed and readable to the standard.

### Usage

```text Usage
minicut check captions EPISODE_FOLDER [--json]
```

Replace the following:

- `EPISODE_FOLDER`: the episode folder, such as `episodes/ep01`.

### Details

The Mock and Edit loops run this check. The standard is captions at the bottom centre, at most 2 lines, each timed to its spoken line.

### Options

| Flag | Type | Default | Description |
|---|---|---|---|
| `--json` | switch | off | Print the result as JSON and save it in the episode folder |

### Examples

#### Check the captions of episode 1

```bash Terminal
minicut check captions episodes/ep01
```

### See also

[minicut check mock](#minicut-check-mock), [minicut check labels](#minicut-check-labels)

## minicut check labels

Checks that every mock shot has a labeled copy for people to review.

### Usage

```text Usage
minicut check labels EPISODE_FOLDER [--json]
```

Replace the following:

- `EPISODE_FOLDER`: the episode folder, such as `episodes/ep01`.

### Details

The Mock loop runs this check. In each labeled copy, every asset of the shot carries a tag with its `@name`. The tags are on screen, apart from each other and off faces. The clean copy of the picture stays untouched.

### Options

| Flag | Type | Default | Description |
|---|---|---|---|
| `--json` | switch | off | Print the result as one JSON object |

### Examples

#### Check the labels of episode 1

```bash Terminal
minicut check labels episodes/ep01
```

### See also

[minicut check mock](#minicut-check-mock)

## minicut check lengths

Checks each shot on the timeline against the length of its take, and the music against the episode.

### Usage

```text Usage
minicut check lengths EPISODE_FOLDER [--json]
```

Replace the following:

- `EPISODE_FOLDER`: an episode folder that has a timeline, such as `episodes/ep01`.

### Details

A take shorter than its shot leaves the last frame held on screen. The check finds each of those and checks that the music fits the episode.

### Options

| Flag | Type | Default | Description |
|---|---|---|---|
| `--json` | switch | off | Print the result as one JSON object |

### Examples

#### Check the lengths of episode 1

```bash Terminal
minicut check lengths episodes/ep01
```

### Output

The number of shots checked, then one `FAIL` line per problem with its fix. Exit code 2 means the folder has no timeline.

### See also

[minicut check render](#minicut-check-render)

## minicut check zoom

Makes full-size pictures of every part of a take, so a person or an agent can look at the detail.

### Usage

```text Usage
minicut check zoom TAKE_FILE [--prev PREVIOUS_TAKE] [--box NAME=X,Y,W,H@FRAME ...] [--out FOLDER] [--json]
```

Replace the following:

- `TAKE_FILE`: the take's video file, such as `t02.mp4`.
- `PREVIOUS_TAKE`: the take of the shot before, to check the cut between them.
- `NAME=X,Y,W,H@FRAME`: one area to look at closely: a name, its position and size in pixels, and the frame number.
- `FOLDER`: the folder to save the pictures in.

### Details

The pictures show every part of the frame, every hand and face, and the places where something changes. With `--prev`, they also show the cut from the shot before.

### Options

| Flag | Type | Default | Description |
|---|---|---|---|
| `--prev` | file | none | The take of the shot before |
| `--box` | area | none | One area to look at closely. Repeat it for more |
| `--out` | folder | none | Where to save the pictures |
| `--json` | switch | off | Print the result as one JSON object |

### Examples

#### Look closely at a take and the cut before it

```bash Terminal
minicut check zoom episodes/ep01/clips/c03/t02.mp4 --prev episodes/ep01/clips/c02/t01.mp4
```

### See also

[minicut check take](#minicut-check-take)

## minicut loop

Shows each loop's round, its limit and its last result, and the one command to run next.

### Usage

```text Usage
minicut loop [status] [--episode EPISODE] [--json]
```

Replace the following:

- `EPISODE`: an episode id such as `ep01`.

### Details

The loops run in a project folder, or any folder under it. There are 5 loops, and the CLI names them `script`, `sheet`, `mock`, `videos` and `edit`:

| Loop | CLI name | What it makes |
|---|---|---|
| Script | `script` | The story and the episode script |
| Shot sheet | `sheet` | Every shot in the episode, and pictures of its characters and places |
| Mock | `mock` | The whole episode as still pictures with voices, music and captions |
| Videos | `videos` | A video take for every shot |
| Edit | `edit` | The finished episode as a video file |

Each loop makes its part, checks it, fixes what fails and checks again. A loop stops after 3 rounds by default and shows you what still fails, and you decide. The order is a suggestion: a loop run out of order prints one warning and runs.

To change the limit for a project, add `"loops"` to its `series.json`, such as `"loops": {"mock": 4, "takes": 5}`. The key for the Videos loop is `takes`.

### Options

| Flag | Type | Default | Description |
|---|---|---|---|
| `--episode` | episode id | the episode you are in | The episode to show |
| `--json` | switch | off | Print one JSON object |

### Examples

#### Show where every loop stands

```bash Terminal
minicut loop
```

### Output

The project title and episode, then one row per loop with the steps it covers, its limit, its rounds and its state. The last two lines are `next:` with the one command to run, and `why:`.

### Errors

| Message | What to do |
|---|---|
| `minicut loop runs inside a project folder` | Run it in the project folder, the one with `series.json`, or a folder under it |

### See also

[minicut loop next](#minicut-loop-next), [Overview](/docs/cli/overview)

## minicut loop next

Prints the one command to run next, and why.

### Usage

```text Usage
minicut loop next [--json]
```

### Details

Your agent runs this to find out what to do. It never has to guess the order of the steps.

### Options

| Flag | Type | Default | Description |
|---|---|---|---|
| `--json` | switch | off | Print one JSON object |

### Examples

#### Ask what to do next

```bash Terminal
minicut loop next
```

### Output

The command on the first line, then `why:` with the reason and `read:` with the files to read first.

### See also

[minicut loop run](#minicut-loop-run)

## minicut loop run

Runs one loop's checks once and records the round.

### Usage

```text Usage
minicut loop run {script|sheet|mock|videos|edit} [--max ROUNDS] [--json]
```

Replace the following:

- `ROUNDS`: the most rounds this loop may take.

### Details

Before it uses a round, the command checks that the loop's files exist. For the Mock loop, every shot needs its mock picture, every line its voice, and the music its file. Someone also has to look at the mock's picture sheet first. For the Script and Shot sheet loops, every step file must be written. When something is missing, the command lists it, exits with code 3 and uses no round.

### Options

| Flag | Type | Default | Description |
|---|---|---|---|
| `--max` | number | 3, or the limit in `series.json` | The most rounds for this loop |
| `--json` | switch | off | Print one JSON object |

### Examples

#### Run the Shot sheet loop's checks

```bash Terminal
minicut loop run sheet
```

### See also

[minicut check STEP](#minicut-check-step), [minicut loop approve](#minicut-loop-approve)

## minicut loop approve

Records that you said yes to what a loop showed you.

### Usage

```text Usage
minicut loop approve {script|sheet|mock|videos|edit}
```

### Details

Approve a loop after you look at what it made. If the loop's last round did not pass, the command records your yes anyway and prints a note. It then prints the next command.

### Examples

#### Approve the mock

```bash Terminal
minicut loop approve mock
```

### See also

[minicut loop done](#minicut-loop-done)

## minicut loop done

Ends a loop because you decided to, whether it passed or not.

### Usage

```text Usage
minicut loop done {script|sheet|mock|videos|edit} --reason REASON
```

Replace the following:

- `REASON`: your words for why the loop ends, in quotes.

### Details

Use this when a loop stops at its limit and you decide the result is good enough. Your reason is kept with the loop.

### Examples

#### End the Videos loop

```bash Terminal
minicut loop done videos --reason "Good enough, ship it"
```

### See also

[minicut loop approve](#minicut-loop-approve)

## minicut loop pause

Makes every loop go quiet, until `minicut loop resume` brings them back.

### Usage

```text Usage
minicut loop pause [--reason REASON]
minicut loop resume
```

Replace the following:

- `REASON`: why you pause, in quotes.

### Details

While the loops are paused, your agent can stop work and nothing asks it to go on.

### Examples

#### Pause for the day

```bash Terminal
minicut loop pause --reason "Back tomorrow"
```

### See also

[minicut loop stop-at](#minicut-loop-stop-at)

## minicut loop stop-at

Tells the loops to go only as far as one loop, such as the mock.

### Usage

```text Usage
minicut loop stop-at {script|sheet|mock|videos|edit|none} --reason REASON
```

Replace the following:

- `REASON`: your words for the stop, in quotes. Not needed with `none`.

### Details

After a stop, `minicut loop next` names no loop or step past it. `none` clears the stop, and every loop is open again.

### Examples

#### Go only as far as the mock

```bash Terminal
minicut loop stop-at mock --reason "Show me the mock first"
```

### See also

[minicut loop next](#minicut-loop-next)

## minicut loop guard

Sends your coding agent back to work while a loop or a job is still open.

### Usage

```text Usage
minicut loop guard [--hook | --pre-tool]
```

### Details

This command is for your coding agent's hooks. It exits with code 2, which sends the agent back to work, in three cases:

- a loop is mid-round
- real video takes wait for the Videos loop
- a job of the project still runs

Outside a project, or while the loops are paused, it exits with code 0.

### Options

| Flag | Type | Default | Description |
|---|---|---|---|
| `--hook` | switch | off | Run as the agent's stop hook, reading what the agent app sends |
| `--pre-tool` | switch | off | Run before the agent writes a file. It refuses a direct write to the episode timeline and names the `minicut timeline` command to use |

### See also

[minicut loop pause](#minicut-loop-pause)