# Projects

Commands that make a project, keep pictures and takes in it, and show its shots and its script.

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).

## minicut new

Makes a project folder, adds an episode to a project, or writes an empty timeline into an episode.

### Usage

```text Usage
minicut new ID [--title TITLE] [--dir PARENT] [--episodes COUNT]
minicut new ID --add-episode [--dir PARENT] [--json]
minicut new ID --timeline EPISODE [--dir PARENT] [--json]
```

Replace the following:

- `ID`: the project id. Lowercase letters, digits and `-`, up to 24 characters, starting with a letter or digit.
- `TITLE`: the title people read. Any language.
- `PARENT`: the folder the project goes in.
- `COUNT`: how many episodes you plan, a whole number from 1 to 9999.
- `EPISODE`: an episode id such as `ep01`.

### Details

One project is one series. `minicut new` makes the project folder with its first episode, `ep01`. The episode starts with an empty timeline that the editor opens as it is. With no `--dir`, the project goes in the `projects` folder of your MiniCut home folder.

`--add-episode` adds the next free episode (`ep02`, `ep03`, and on) and lists it in `series.json`. `--timeline` writes the empty timeline into an episode folder that has none.

Characters, locations, props and styles are not kept in the project folder. They go in your library with [minicut save](#minicut-save), and the project lists them by id.

### Options

| Flag | Type | Default | Description |
|---|---|---|---|
| `--title` | text | the id | The title people read, saved in `series.json` |
| `--dir` | folder | the `projects` folder | The folder the project goes in |
| `--episodes` | number | none | How many episodes you plan. Over 99 makes episode ids with three digits, such as `ep001` |
| `--add-episode` | switch | off | Add the next episode to an existing project |
| `--timeline` | episode id | none | Write the empty timeline into this episode |
| `--json` | switch | off | Print one JSON object. Works with `--add-episode` and `--timeline` |

### Examples

#### Make a project with a title

```bash Terminal
minicut new rain-shop --title "Rain shop"
```

#### Add the next episode

```bash Terminal
minicut new rain-shop --add-episode
```

### Output

`minicut new` prints the project folder and the files it made. With `--json`, `--add-episode` and `--timeline` print:

```json JSON shape
{"ok": true, "project": "rain-shop", "episode": "ep02", "dir": "~/.minicut/projects/rain-shop/episodes/ep02", "created": "episode"}
```

`created` is `episode` or `timeline`.

| Exit code | Meaning |
|---|---|
| 0 | It made the folder |
| 2 | The id, episode or count is wrong, or the folder already exists |
| 5 | `--dir` is outside your work folders |

### Files

```text Project
rain-shop/
  series.json            title, id, screen shape, episodes and library ids
  source/
    sources.json         the sources the story comes from, empty at first
  episodes/
    ep01/
      clips/             one folder per shot, with its takes
      music/             the episode's music
      index.html         the episode timeline, empty until the first cut
      minicut.json       the editor settings for this episode
```

### Errors

| Message | What to do |
|---|---|
| `"<id>" cannot be a project id.` | Use lowercase letters, digits and `-`, up to 24, and put the real title in `--title` |
| `already exists: <folder>` | Pick another id, or work in the project that is there |
| `--episodes is the planned episode count, a number.` | Give a whole number such as `--episodes 12` |
| `no project at <folder> (no readable series.json)` | Check the id, or add `--dir` with the folder the project is in |
| `--timeline needs an episode id such as ep01.` | Give the episode id after `--timeline` |
| `<episode> already has a timeline` | Nothing to do: the episode has its timeline |

### See also

[minicut save](#minicut-save), [minicut shots](#minicut-shots), [Overview](/docs/cli/overview)

## minicut save

Keeps a picture in your library, or keeps a generated file as a take of one shot.

### Usage

```text Usage
minicut save KIND FILE --id ID [--name NAME] [--as STEM] [--project PROJECT]
minicut save take FILE --project PROJECT --episode EPISODE --clip CLIP [--kind {model|code|placeholder}] [--model MODEL] [--seconds SECONDS]
```

Replace the following:

- `KIND`: `character`, `location`, `prop` or `style`.
- `FILE`: the file to keep. A picture is `.png`, `.jpg`, `.jpeg` or `.webp`. A take is `.mp4`, `.mov`, `.webm`, `.wav`, `.mp3` or `.m4a`.
- `ID`: the item's id. Lowercase letters, digits and `-`, up to 32 characters, such as `lin-xia`.
- `NAME`: the name people read for the item.
- `STEM`: the file name to save the picture as, without the extension, such as `face-01`.
- `PROJECT`: a project id, or the path to a project folder.
- `EPISODE`: an episode id such as `ep01`.
- `CLIP`: a shot id such as `c01`.
- `MODEL`: the name of the model that made the take.
- `SECONDS`: the length of the clip a placeholder picture becomes.

### Details

Your library holds characters, locations, props and styles, and every project can use them. `minicut save KIND` copies the picture into the item's folder in the library. With `--project`, it also lists the item's id in that project's `series.json`. It never writes over a file that is already in the library.

`minicut save take` keeps a file as the shot's next take: `t01`, `t02`, and on. The file goes in the library, and the shot's folder gets the same file, as a hard link when the disk allows it. A take record goes beside it. The first take of a shot becomes its pick.

With `--kind placeholder`, a `.png` or `.jpg` picture becomes a clip as long as the shot. The length is `--seconds`, else the shot's length on the shot sheet.

### Options

| Flag | Type | Default | Description |
|---|---|---|---|
| `--id` | id | none | The item's id. Needed for a library picture |
| `--name` | text | the id | The name people read for the item |
| `--as` | name | `sheet-NN` for a character, else `image-NN` | The file name the picture is saved as |
| `--project` | id or folder | none | The project to list the item in. Needed for a take |
| `--episode` | episode id | none | The episode of the shot. Needed for a take |
| `--clip` | shot id | none | The shot the take is for. Needed for a take |
| `--kind` | `model`, `code` or `placeholder` | `model` | How the take was made: by a model, by code, or from a still picture |
| `--model` | name | none | The model that made the take |
| `--seconds` | number | the shot's length | The clip length for `--kind placeholder` |

### Examples

#### Keep a character picture and list it in a project

```bash Terminal
minicut save character lin-xia.png --id lin-xia --name "Lin Xia" --project rain-shop
```

#### Keep a video as the take of shot 3

```bash Terminal
minicut save take take.mp4 --project rain-shop --episode ep01 --clip c03
```

### Output

`minicut save` prints `Saved` and the path of the saved file, then each project file it changed.

| Exit code | Meaning |
|---|---|
| 0 | It saved the file |
| 2 | A flag or the file is wrong, or the file is already in the library |
| 5 | The file is outside your work folders |

### Errors

| Message | What to do |
|---|---|
| `no such file: <file>` | Check the path to the file |
| `--id must be a short ASCII id` | Use lowercase letters, digits and `-`, up to 32 |
| `already in the library, not overwritten: <file>` | Save it with another `--as`, or use the file that is there |
| `--episode is ep01 (or ep001) and --clip is c01 (or c001).` | Give both ids in that form |
| `no episode folder <folder>.` | Use an episode that `series.json` lists |
| `no length for <clip>: add --seconds S` | Add `--seconds`, or give the shot a length on the shot sheet |

### See also

[minicut asset](#minicut-asset), [minicut new](#minicut-new)

## minicut asset

Adds, renames, sets the cover of, or removes an item in a project, and picks a shot's take.

### Usage

```text Usage
minicut asset add PROJECT {characters|locations|props} NAME [--note NOTE] [PICTURE ...]
minicut asset rename PROJECT KIND ITEM NEW_NAME
minicut asset cover PROJECT KIND ITEM PICTURE_NAME
minicut asset remove PROJECT KIND ITEM
minicut asset pick PROJECT EPISODE CLIP TAKE
```

Replace the following:

- `PROJECT`: a project id, `.` for the project you are in, or the path to a project folder.
- `NAME`: the name of the new item.
- `NOTE`: a short description of the item.
- `PICTURE`: a picture file for the item. Give more than one to add more.
- `KIND`: `characters`, `locations` or `props`.
- `ITEM`: the item to change.
- `NEW_NAME`: the item's new name.
- `PICTURE_NAME`: the file name of one of the item's pictures.
- `EPISODE`, `CLIP`, `TAKE`: the episode, shot and take, such as `ep01 c03 t02`.

### Details

These are the same actions as the **资产** tab in the MiniCut app, and they keep the same rules. A name that is already taken is refused. `rename` changes every `@name` mention of the item in the project. `remove` moves the item's folder to the system Trash. `pick` sets the take the shot uses.

### Options

| Flag | Type | Default | Description |
|---|---|---|---|
| `--note` | text | none | A short description of the item. Works with `add` |

### Examples

#### Add a character with one picture

```bash Terminal
minicut asset add rain-shop characters "Lin Xia" --note "shop owner" lin-xia.png
```

#### Use take 2 for shot 3

```bash Terminal
minicut asset pick rain-shop ep01 c03 t02
```

### Output

`minicut asset` prints one line of JSON: the result of the action, or an `error`.

| Exit code | Meaning |
|---|---|
| 0 | The action ran |
| 1 | The action was refused |
| 2 | The words after `asset` are wrong |
| 5 | A picture is outside your work folders |

### See also

[minicut save](#minicut-save), [minicut shots](#minicut-shots)

## minicut shots

Lists every shot of an episode with its state, the same states the shot sheet shows in the app.

### Usage

```text Usage
minicut shots [--episode EPISODE] [--project PROJECT] [--json]
```

Replace the following:

- `EPISODE`: an episode id such as `ep01`.
- `PROJECT`: a project id or the path to a project folder.

### Details

The project is `--project`, else the project folder you run the command in. The episode is `--episode`, else the project's only episode. The command reads the episode's files and changes nothing.

### Options

| Flag | Type | Default | Description |
|---|---|---|---|
| `--episode` | episode id | the only episode | The episode to list |
| `--project` | id or folder | the folder you are in | The project to read |
| `--json` | switch | off | Print a JSON list |

### Examples

#### List the shots of episode 1

```bash Terminal
minicut shots --episode ep01
```

### Output

Each line is one shot: its id, its state, then its take, its job id and the reason when there are any. The states print in Chinese, as in the app.

With `--json`, the command prints a list with one object per shot:

```json JSON shape
[{"clip": "c01", "state": "done", "take": "t01", "job_id": null, "reason": null}]
```

| State | Meaning |
|---|---|
| `sheet` | On the shot sheet, no prompt yet |
| `writing` | The agent is writing the prompt |
| `promptFail` | The prompt failed its check |
| `ready` | Ready to generate |
| `queued` | The job is waiting to start |
| `running` | The job is running |
| `saving` | The result is being saved |
| `failed` | The job failed |
| `stopped` | The job was stopped |
| `unchecked` | The take is not checked yet |
| `fail` | The take failed its check |
| `done` | The take is made |

Exit codes: 0 when it listed the shots, 5 when it found no project or episode.

### Errors

| Message | What to do |
|---|---|
| `No project here: run this inside a series folder, or add --project <id or folder>.` | Run it in the project folder, or add `--project` |
| `Which episode? Add --episode epNN` | Add `--episode` with one of the episodes it lists |

### See also

[minicut now](#minicut-now), [minicut asset](#minicut-asset)

## minicut now

Tells the shot sheet in the app which shot your agent is writing. The app shows it for 120 seconds.

### Usage

```text Usage
minicut now STEP CLIP [--episode EPISODE] [--project PROJECT] [--json]
```

Replace the following:

- `STEP`: the number of the step your agent is working on, a whole number from 1.
- `CLIP`: a shot id such as `c03`, or the path to the shot's folder.
- `EPISODE`: an episode id such as `ep01`.
- `PROJECT`: a project id or the path to a project folder.

### Details

The command writes one small file in the episode folder. The app reads it and shows which shot the agent is on. After 120 seconds the note goes away by itself. The project and episode are found the same way as for [minicut shots](#minicut-shots), and a shot folder path gives both.

### Options

| Flag | Type | Default | Description |
|---|---|---|---|
| `--episode` | episode id | the shot folder's episode, else the only episode | The episode of the shot |
| `--project` | id or folder | the folder you are in | The project |
| `--json` | switch | off | Print one JSON object |

### Examples

#### Show that the agent is writing shot 3

```bash Terminal
minicut now 6 c03 --episode ep01
```

### Output

The command prints the step, the shot number and the episode, and says it shows for the next 120 seconds. With `--json` it prints:

```json JSON shape
{"type": "mh.now", "step": 6, "clip": "c03", "at": "2026-10-29T10:00:00.000Z"}
```

Exit codes: 0 when it wrote the note, 2 when `STEP` or `CLIP` is wrong, 5 when it found no project or episode.

### See also

[minicut shots](#minicut-shots), [minicut script](#minicut-script)

## minicut script

Opens the script and shot sheet editor on one episode, on your own computer.

### Usage

```text Usage
minicut script PROJECT [--episode EPISODE] [--port PORT] [--no-open]
```

Replace the following:

- `PROJECT`: a project id or the path to a project folder.
- `EPISODE`: an episode id such as `ep01`.
- `PORT`: the port number the editor page uses on your computer.

### Details

The editor is a page in your browser that reads and writes the episode's own files. It edits `script.md` and `shots.md`, and shows `assets.md` and `prompts.md`. Each save runs that file's check with [minicut check](/docs/cli/checks-and-loops#minicut-check-step). Nothing is uploaded and nothing syncs: the files in the episode folder are the only copy. When your agent edits a file, the page reloads it.

### Options

| Flag | Type | Default | Description |
|---|---|---|---|
| `--episode` | episode id | `ep01` | The episode to open |
| `--port` | number | a free port | The port the editor page uses |
| `--no-open` | switch | off | Print the address and do not open the browser |

### Examples

#### Open the editor on episode 1

```bash Terminal
minicut script rain-shop --episode ep01
```

### Output

The command prints the episode folder, each of the four files and whether it is written yet, then `URL:` and the editor address. It keeps running until you stop it with Ctrl+C.

### Files

```text Episode
ep01/
  script.md       the episode script
  shots.md        the shot sheet
  assets.md       the characters, places and props the shots use
  prompts.md      the prompt for each shot
```

### See also

[minicut shots](#minicut-shots), [Checks and loops](/docs/cli/checks-and-loops)