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.

minicut new

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

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, and the project lists them by id.

Options

Examples

Make a project with a title

minicut new rain-shop --title "Rain shop"

Add the next episode

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:

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

created is episode or timeline.

Files

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

See also

minicut save, minicut shots, Overview

minicut save

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

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

Examples

Keep a character picture and list it in a project

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

Keep a video as the take of shot 3

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.

Errors

See also

minicut asset, minicut new

minicut asset

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

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

Examples

Add a character with one picture

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

Use take 2 for shot 3

minicut asset pick rain-shop ep01 c03 t02

Output

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

See also

minicut save, minicut shots

minicut shots

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

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

Examples

List the shots of episode 1

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:

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

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

Errors

See also

minicut now, 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

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, and a shot folder path gives both.

Options

Examples

Show that the agent is writing shot 3

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:

{"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 script

minicut script

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

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

Examples

Open the editor on episode 1

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

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, Checks and loops