# MiniCut docs Every page also lives at https://www.minicut.ai/docs, and as Markdown at the same address plus .md. # Docs Docs for the MiniCut CLI. Pick the task you have, and each line takes you to the page for it. ## Install with your agent Paste one prompt into your coding agent, and it installs MiniCut, signs you in and checks every tool. This is the usual way. [Install with your agent](/docs/cli/install-with-your-agent) ## Install in a terminal Run the same install yourself, one command at a time, on macOS, Linux or Windows. [Install in a terminal](/docs/cli/install-in-a-terminal) ## Make a first project Go from nothing to a first short drama project in four steps. [Quickstart](/docs/cli/quickstart) ## Learn the loops See the 5 loops that take your idea to a finished episode, in the order your agent runs them. [Overview](/docs/cli/overview) --- # Overview The MiniCut CLI makes a short drama episode in 5 loops that your coding agent runs, and each loop checks its own work. The MiniCut CLI is the `minicut` command. Your coding agent runs it to turn your idea into a finished episode. On the way it makes a script, a shot sheet, pictures, video takes, music and an edited cut. Fig. 1: your coding agent runs Script, Shot sheet, Mock, Videos, Edit in this order. Each loop checks its own work and redoes what fails, up to 3 rounds (Videos: up to 3 takes a shot). Between loops, you can change the shot sheet after the mock. Edit renders the episode, a video file. ## Loops Your agent runs the loops in this order: - **Script**: the story and the episode script. - **Shot sheet**: every shot in the episode, and pictures of its characters and places. - **Mock**: the whole episode as still pictures with voices, music and captions, so you see it before any video. - **Videos**: a video take for every shot. - **Edit**: the finished episode as a video file. Your agent runs `minicut loop next`, and the CLI prints the one command to run next. If something still fails after 3 rounds, the loop stops and shows you what fails, and you decide. ## Next [Quickstart](/docs/cli/quickstart) [Install with your agent](/docs/cli/install-with-your-agent) --- # Quickstart Four steps from nothing to a first short drama project, with your coding agent running every command. ## Install MiniCut Open a new chat in your coding agent and paste the install prompt for your computer. The install downloads a few GB and can take 30 minutes. ```text macOS, Linux Install Minicut on this computer (macOS or Linux), region Global. Run each line in the background and wait for it to finish. 1. curl -fsSL https://minicut.ai/install.sh | bash -s -- --region global (a few GB, can take 30 minutes) 2. ~/.minicut/bin/minicut setup. It downloads the tools Minicut brings. If it says Python 3.12 or ffmpeg is missing, download it from its site (Python 3.12: https://www.python.org/downloads/, ffmpeg: https://ffmpeg.org/download.html), install it, then run ~/.minicut/bin/minicut setup again. Ask me for my password only if the computer needs it. 3. If you are Claude Code or Codex: ~/.minicut/bin/minicut agent-rules 4. ~/.minicut/bin/minicut login --device --lang en. Show me the address and code. Then run ~/.minicut/bin/minicut login --complete every 10 seconds until it says signed in, up to 15 minutes. Do not wait for me to say done. 5. ~/.minicut/bin/minicut doctor 6. Read SKILL.md in the miniharness-short-drama skill folder step 1 made, and use it in this chat. Do not ask me to restart. 7. ~/.minicut/bin/minicut. Tell me what is installed, what is missing and why, and the app address. If a line fails, run it once more; if it fails again, tell me the error and stop. Download Python and ffmpeg only from the sites in step 2. ``` On Windows, or in China mainland, take the prompt for your computer and region from [Install with your agent](/docs/cli/install-with-your-agent). ## Sign in Your agent shows you an address and a code. Open the address, sign in to minicut.ai or make an account, and confirm the code. Your agent sees the sign-in within 10 seconds and goes on with the install. Until this computer is signed in, most commands stop with exit code 10: ```bash Terminal minicut me ``` ```text Output You are not signed in. Ask your agent to run minicut login. ``` ## Make your first project Tell your agent your idea in one or two sentences. It runs `minicut new` with a short id and a title: ```bash Terminal minicut new snow-bus --title "Snow bus" ``` MiniCut makes one folder for the project. Every loop saves its work there, so you and your agent can open any of it. ## Run the loops Your agent runs `minicut loop next` and follows the one command it prints. The Script loop goes first. It writes the story and the episode script, then shows you the script. ```bash Terminal minicut loop next ``` Your agent writes the script in its own chat, and every check runs on your computer. ## Next [Overview](/docs/cli/overview) [Install in a terminal](/docs/cli/install-in-a-terminal) --- # Install with your agent Paste one prompt into your coding agent. It installs MiniCut, signs you in, checks every tool and loads the MiniCut skill. ## Requirements | Requirement | Value | |---|---| | Computer | macOS, Linux or Windows, on ARM64 or x64 | | Free disk | 5 GB | | Network | An internet connection for the install and for sign-in | | Agent app | One of the 11 coding agent apps MiniCut supports, such as Claude Code, Codex, Cursor, OpenCode, TRAE, Kimi Code or Qoder | ## Run the prompt 1. Open a new chat in your agent app. 2. Copy the prompt for your computer from Prompts below. If you are in China mainland, copy it from China mainland instead. 3. Paste it into the chat and send it. 4. When your agent shows an address and a code, open the address, sign in to minicut.ai, and confirm the code. 5. Wait for your agent's last message. It names what is installed, what is missing and why, and the address of the MiniCut app. The install downloads a few GB and can take 30 minutes. Your agent asks for your computer password only if the computer needs it. ## Prompts The prompt is the same in every agent app. On Windows, `minicut` in the prompt means the full path the install prints at the end of line 1. ```text macOS, Linux Install Minicut on this computer (macOS or Linux), region Global. Run each line in the background and wait for it to finish. 1. curl -fsSL https://minicut.ai/install.sh | bash -s -- --region global (a few GB, can take 30 minutes) 2. ~/.minicut/bin/minicut setup. It downloads the tools Minicut brings. If it says Python 3.12 or ffmpeg is missing, download it from its site (Python 3.12: https://www.python.org/downloads/, ffmpeg: https://ffmpeg.org/download.html), install it, then run ~/.minicut/bin/minicut setup again. Ask me for my password only if the computer needs it. 3. If you are Claude Code or Codex: ~/.minicut/bin/minicut agent-rules 4. ~/.minicut/bin/minicut login --device --lang en. Show me the address and code. Then run ~/.minicut/bin/minicut login --complete every 10 seconds until it says signed in, up to 15 minutes. Do not wait for me to say done. 5. ~/.minicut/bin/minicut doctor 6. Read SKILL.md in the miniharness-short-drama skill folder step 1 made, and use it in this chat. Do not ask me to restart. 7. ~/.minicut/bin/minicut. Tell me what is installed, what is missing and why, and the app address. If a line fails, run it once more; if it fails again, tell me the error and stop. Download Python and ffmpeg only from the sites in step 2. ``` ```text Windows PowerShell Install Minicut on this computer (Windows PowerShell), region Global. Run each line in the background and wait for it to finish. From step 2 on, minicut means the full path of minicut the install printed at the end of step 1. 1. & ([scriptblock]::Create((irm https://minicut.ai/install.ps1))) -Region global (a few GB, can take 30 minutes) 2. minicut setup. It downloads the tools Minicut brings. If it says Python 3.12 or ffmpeg is missing, download it from its site (Python 3.12: https://www.python.org/downloads/, ffmpeg: https://ffmpeg.org/download.html), install it, then run minicut setup again. Ask me for my password only if the computer needs it. 3. If you are Claude Code or Codex: minicut agent-rules 4. minicut login --device --lang en. Show me the address and code. Then run minicut login --complete every 10 seconds until it says signed in, up to 15 minutes. Do not wait for me to say done. 5. minicut doctor 6. Read SKILL.md in the miniharness-short-drama skill folder step 1 made, and use it in this chat. Do not ask me to restart. 7. minicut. Tell me what is installed, what is missing and why, and the app address. If a line fails, run it once more; if it fails again, tell me the error and stop. Download Python and ffmpeg only from the sites in step 2. ``` ```text Windows CMD Install Minicut on this computer (Windows CMD), region Global. Run each line in the background and wait for it to finish. From step 2 on, minicut means the full path of minicut the install printed at the end of step 1. 1. curl -fsSL https://minicut.ai/install.cmd -o install.cmd && install.cmd -Region global && del install.cmd (a few GB, can take 30 minutes) 2. minicut setup. It downloads the tools Minicut brings. If it says Python 3.12 or ffmpeg is missing, download it from its site (Python 3.12: https://www.python.org/downloads/, ffmpeg: https://ffmpeg.org/download.html), install it, then run minicut setup again. Ask me for my password only if the computer needs it. 3. If you are Claude Code or Codex: minicut agent-rules 4. minicut login --device --lang en. Show me the address and code. Then run minicut login --complete every 10 seconds until it says signed in, up to 15 minutes. Do not wait for me to say done. 5. minicut doctor 6. Read SKILL.md in the miniharness-short-drama skill folder step 1 made, and use it in this chat. Do not ask me to restart. 7. minicut. Tell me what is installed, what is missing and why, and the app address. If a line fails, run it once more; if it fails again, tell me the error and stop. Download Python and ffmpeg only from the sites in step 2. ``` ## China mainland These prompts install from the China mainland region and name download sites that load there. ```text macOS, Linux Install Minicut on this computer (macOS or Linux), region China mainland. Run each line in the background and wait for it to finish. 1. curl -fsSL https://minicut.ai/install.sh | bash -s -- --region cn (a few GB, can take 30 minutes) 2. ~/.minicut/bin/minicut setup. It downloads the tools Minicut brings. If it says Python 3.12 or ffmpeg is missing, download it from its site (Python 3.12: https://registry.npmmirror.com/binary.html?path=python/3.12.10/, ffmpeg: https://registry.npmmirror.com/binary.html?path=ffmpeg-static/b6.1.1/), install it, then run ~/.minicut/bin/minicut setup again. Ask me for my password only if the computer needs it. 3. If you are Claude Code or Codex: ~/.minicut/bin/minicut agent-rules 4. ~/.minicut/bin/minicut login --device --lang en. Show me the address and code. Then run ~/.minicut/bin/minicut login --complete every 10 seconds until it says signed in, up to 15 minutes. Do not wait for me to say done. 5. ~/.minicut/bin/minicut doctor 6. Read SKILL.md in the miniharness-short-drama skill folder step 1 made, and use it in this chat. Do not ask me to restart. 7. ~/.minicut/bin/minicut. Tell me what is installed, what is missing and why, and the app address. If a line fails, run it once more; if it fails again, tell me the error and stop. Download Python and ffmpeg only from the sites in step 2. ``` ```text Windows PowerShell Install Minicut on this computer (Windows PowerShell), region China mainland. Run each line in the background and wait for it to finish. From step 2 on, minicut means the full path of minicut the install printed at the end of step 1. 1. & ([scriptblock]::Create((irm https://minicut.ai/install.ps1))) -Region cn (a few GB, can take 30 minutes) 2. minicut setup. It downloads the tools Minicut brings. If it says Python 3.12 or ffmpeg is missing, download it from its site (Python 3.12: https://registry.npmmirror.com/binary.html?path=python/3.12.10/, ffmpeg: https://registry.npmmirror.com/binary.html?path=ffmpeg-static/b6.1.1/), install it, then run minicut setup again. Ask me for my password only if the computer needs it. 3. If you are Claude Code or Codex: minicut agent-rules 4. minicut login --device --lang en. Show me the address and code. Then run minicut login --complete every 10 seconds until it says signed in, up to 15 minutes. Do not wait for me to say done. 5. minicut doctor 6. Read SKILL.md in the miniharness-short-drama skill folder step 1 made, and use it in this chat. Do not ask me to restart. 7. minicut. Tell me what is installed, what is missing and why, and the app address. If a line fails, run it once more; if it fails again, tell me the error and stop. Download Python and ffmpeg only from the sites in step 2. ``` ```text Windows CMD Install Minicut on this computer (Windows CMD), region China mainland. Run each line in the background and wait for it to finish. From step 2 on, minicut means the full path of minicut the install printed at the end of step 1. 1. curl -fsSL https://minicut.ai/install.cmd -o install.cmd && install.cmd -Region cn && del install.cmd (a few GB, can take 30 minutes) 2. minicut setup. It downloads the tools Minicut brings. If it says Python 3.12 or ffmpeg is missing, download it from its site (Python 3.12: https://registry.npmmirror.com/binary.html?path=python/3.12.10/, ffmpeg: https://registry.npmmirror.com/binary.html?path=ffmpeg-static/b6.1.1/), install it, then run minicut setup again. Ask me for my password only if the computer needs it. 3. If you are Claude Code or Codex: minicut agent-rules 4. minicut login --device --lang en. Show me the address and code. Then run minicut login --complete every 10 seconds until it says signed in, up to 15 minutes. Do not wait for me to say done. 5. minicut doctor 6. Read SKILL.md in the miniharness-short-drama skill folder step 1 made, and use it in this chat. Do not ask me to restart. 7. minicut. Tell me what is installed, what is missing and why, and the app address. If a line fails, run it once more; if it fails again, tell me the error and stop. Download Python and ffmpeg only from the sites in step 2. ``` ## Each line of the prompt 1. Line 1 downloads MiniCut and adds the MiniCut skill to every agent app it finds. 2. Line 2 runs `minicut setup`, which downloads the tools MiniCut brings. Your agent downloads Python 3.12 or ffmpeg from the sites in the prompt only if setup says they are missing. 3. Line 3 runs `minicut agent-rules` in Claude Code or Codex. It writes that app's allow and ask-first rules for MiniCut commands. 4. Line 4 signs this computer in with a code you confirm on minicut.ai. 5. Line 5 runs `minicut doctor`, which lists every tool, its version and where it is. 6. Line 6 loads the MiniCut skill into the chat you are in, so you do not restart the app. 7. Line 7 runs `minicut`, which opens the MiniCut app in your browser. ## Errors | Message or state | What to do | |---|---| | Your agent says a line failed twice and stops | Read the error it shows. Fix what it names, then send the prompt again. | | `minicut setup` says Python 3.12 or ffmpeg is missing | Your agent downloads it from the site in line 2 and runs setup again. If it cannot, install it from that site yourself. | | The code expired before you confirmed it | Ask your agent to run line 4 again. A code lasts 15 minutes. | | `You are not signed in. Ask your agent to run minicut login.` | Sign-in did not finish. Ask your agent to run line 4 again. | ## Check it worked Ask your agent to run `minicut status`. A signed-in computer shows the account it is signed in as, where its key is kept and the CLI version. ## Next [Quickstart](/docs/cli/quickstart) [Install in a terminal](/docs/cli/install-in-a-terminal) [Overview](/docs/cli/overview) --- # Install in a terminal Install MiniCut yourself, one command at a time: download it, set up its tools, sign in and connect your agent app. You need macOS, Linux or Windows on ARM64 or x64, 5 GB of free disk and an internet connection. To have your coding agent run these steps for you, see [Install with your agent](/docs/cli/install-with-your-agent). ## Install the CLI 1. Optional: install Python 3.12 and ffmpeg first with your package manager. `minicut setup` asks for them later if they are missing. ```bash macOS brew install python@3.12 ffmpeg ``` ```bash Linux sudo apt install python3.12-venv ffmpeg ``` ```powershell Windows winget install Python.Python.3.12 Gyan.FFmpeg ``` 2. Run the install line for your computer. In China mainland, replace `global` with `cn`. ```bash macOS, Linux curl -fsSL https://minicut.ai/install.sh | bash -s -- --region global ``` ```powershell Windows PowerShell & ([scriptblock]::Create((irm https://minicut.ai/install.ps1))) -Region global ``` ```bat Windows CMD curl -fsSL https://minicut.ai/install.cmd -o install.cmd && install.cmd -Region global && del install.cmd ``` 3. Wait for it to finish. It downloads a few GB and can take 30 minutes. At the end it prints `minicut:` and the full path of the command. 4. If you are on macOS or Linux, open a new terminal window. The install adds `~/.minicut/bin` to your PATH in `.zshrc`, `.bashrc` or `.profile`, and a new window reads it. 5. If you are on Windows, use the full path the install printed wherever these steps say `minicut`. The install also adds the MiniCut skill to every agent app it finds on the computer. ## Set up the tools 1. Run setup. It makes the home folder and downloads the tools MiniCut brings. In China mainland, add `--china` to use download mirrors. ```bash Terminal minicut setup ``` 2. If setup says Python 3.12 or ffmpeg is missing, download it from [python.org/downloads](https://www.python.org/downloads/) or [ffmpeg.org/download](https://ffmpeg.org/download.html), install it, and run `minicut setup` again. 3. Optional: run `minicut setup --local-speech` to add the 1 GB of speech models. With them, the step 8 read-back runs on your computer for free. ## Sign in 1. Run the sign-in command. It opens minicut.ai in your browser and waits. ```bash Terminal minicut login ``` 2. Sign in on the page, or make an account. The command ends with `Signed in.` and the email of your account. 3. If the computer has no browser, for example over SSH, run `minicut login --device` instead. It prints an address and a code. 4. Open that address in a browser, sign in, and confirm the code. 5. Run `minicut login --complete` to finish. A code lasts 15 minutes. ## Connect your agent app 1. Run `minicut install-skill` with no flag to list the agent apps on this computer and their skill folders. 2. Add the skill to every app it found, or to one app by its name: ```bash Terminal minicut install-skill --all-found ``` 3. If you use Claude Code or Codex, write that app's allow and ask-first rules for MiniCut commands: ```bash Terminal minicut agent-rules --app claude-code ``` ## Check it worked 1. Run `minicut doctor`. It shows the free disk and the home folder, then every tool with its state, version and folder. If a tool is missing, its last line names the setup command to run. 2. Run `minicut status`. A signed-in computer shows `Signed in as` with your account, where its key is kept, and the CLI version. ## Errors | Message | What to do | |---|---| | `You are not signed in. Ask your agent to run minicut login.` | Run `minicut login`. This command needs a signed-in computer. | | `Could not reach minicut.ai` | Connect to the internet and run the same command again. A signed-in computer works offline for 7 days. | | `minicut: command not found` on macOS or Linux | Open a new terminal window, or run `~/.minicut/bin/minicut`. | | Setup says Python 3.12 or ffmpeg is missing | Install it from the site setup names, then run `minicut setup` again. | ## Next [Quickstart](/docs/cli/quickstart) [Overview](/docs/cli/overview) --- # Steps and loops An episode takes 5 loops. Each loop makes a part, checks it, fixes what fails, and stops after 3 rounds. A step is one piece of work with its own file and its own check, such as the episode script or the shot prompts. A loop groups the steps for one part of the episode. It makes the part, checks it on your computer, fixes what fails and checks again. When the part passes, or the loop reaches its limit, your agent stops and shows you the result. ## Loops Your agent runs the loops in this order. The order is a suggestion: a loop run out of order prints one warning and runs. | Loop | Name in the CLI | What you look at | |---|---|---| | Script | `script` | The episode script, `script.md` | | Shot sheet | `sheet` | The [shot sheet](/docs/cli/shot-sheet) | | Mock | `mock` | The picture sheet of the mock and its video, in the **剪辑** tab of the app | | Videos | `videos` | The video take picked for each shot | | Edit | `edit` | The finished cut, in the **剪辑** tab of the app | What each loop makes is on the [Overview](/docs/cli/overview). `minicut loop` shows where every loop stands, and `minicut loop next` prints the one command to run next. ## Rounds One run of a loop is one round. The round checks the loop's files and saves the result in `loops.json` in the episode folder. A round that finds problems prints one `FAIL` line for each, with the fix under it. Your agent makes the fixes and runs the loop again. A round that finds nothing prints `PASSED`. The loop then waits for your yes. You look at what it made and your agent records your answer with `minicut loop approve`. In the Script, Shot sheet and Mock loops, a missing file stops the run. It lists what is missing, exits with code 3 and uses no round. ## Limits A loop stops after a fixed number of rounds, so a problem it cannot fix does not repeat without end. | Loop | The limit counts | Default | |---|---|---| | Script, Shot sheet, Mock, Edit | Rounds | 3 | | Videos | Video takes for one shot | 3 | To change a limit, add `"loops"` to `series.json`, such as `"loops": {"mock": 4, "takes": 5}`. The key for the Videos loop is `takes`. `minicut loop run` also takes `--max`. See [minicut loop](/docs/cli/checks-and-loops#minicut-loop). ## When a loop fails Under the limit, your agent fixes what the round printed and runs the loop again. If you change a file after a failed round, `minicut loop next` tells your agent to run the loop again. At the limit, the loop prints `CAP REACHED` and your agent stops and shows you what still fails. You decide: - Approve it as it is with `minicut loop approve`. - End the loop with `minicut loop done`, and give your reason. - Raise the limit and let your agent try again. In the Videos loop, only the failing shot is made again. At a shot's limit, your agent picks the best take and tells you what is still wrong with it. Nothing keeps that take for you. ## When something changes A loop that passed is out of date once the files it is built from change. `minicut loop` then shows `out of date, re-run suggested`. You can also tell the loops to go only as far as one loop with `minicut loop stop-at`, or to go quiet with `minicut loop pause`. Claude Code and Codex have a stop hook that `minicut install-skill` adds. It runs `minicut loop guard`. It sends the agent back to work while a loop is mid-round or a job of the project still runs. It also holds the agent while video takes wait for the Videos loop. ## Next [Checks and loops](/docs/cli/checks-and-loops) [Shot sheet](/docs/cli/shot-sheet) [Project directory](/docs/cli/project-directory) --- # Shot sheet The shot sheet (分镜表) is one table that lists every shot of an episode. Pictures, prompts and video takes are made from it. The shot sheet is a table in `shots.md` in the episode folder. One row is one shot, and one shot is one video that the video model makes in one call. Your agent writes it from the episode script in the Shot sheet loop. You can change any cell in the **分镜表** tab of the app. Open it with `minicut open PROJECT --episode EPISODE --tab shots`, or edit the sheet with [minicut script](/docs/cli/projects#minicut-script). Each save in the `minicut script` editor runs checks 4 to 6. ## One shot A shot has an id such as `C01`. The same id names its folder, `clips/c01`. The table has one column for each thing a shot holds: | Column | What it holds | |---|---| | `Clip` | The shot's id, such as `C01` | | `Sec` | The shot's length in seconds, a number | | `Size` | The shot size | | `Angle/move` | The camera angle and move | | `Action` | What happens in the shot | | `Line (speaker)` | The spoken line and who says it | | `Sound` | The sound of the shot | | `Who` | The characters in the shot, as `@name` tags, or `-` | | `Where` | The place of the shot, as an `@name` tag, or `-` | | `Props` | The props in the shot, as `@name` tags, or `-` | | `On-screen text` | Words written inside the picture, such as a sign | | `Cut` | | Camera cuts inside one video go in its `Action` cell, never in extra rows. A card made by the editor, such as an end card, is a row with an id like `E01`. Above the table, the plan gives the target length of the episode on its own line. Under the table, a `Screen order:` line lists every shot once, in the order they play. `Sec` has to fit the video model you chose, because each model has its own shortest and longest shot. See [minicut check STEP](/docs/cli/checks-and-loops#minicut-check-step). ## Shot states A shot is in one state at a time. The app shows the state in Chinese and `minicut shots` prints the same words. The state is worked out from the shot's files each time you look, so the app and the CLI always agree. | State | Shown as | Meaning | |---|---|---| | `sheet` | 待写提示词 | The shot is on the sheet and has no prompt yet | | `writing` | 写提示词 | Your agent is writing the prompt now | | `promptFail` | 提示词未通过 | The prompt failed its check | | `ready` | 生成 | The prompt is written and the shot is ready to generate | | `queued` | 排队中 | A job for the shot is waiting to start | | `running` | 生成中 | A job for the shot is running | | `saving` | 保存中 | The result is being saved as a take | | `failed` | 生成失败 | The job failed, and the row shows why | | `stopped` | 已停止 | The job was stopped | | `unchecked` | 待检查 | The shot has a take that is not checked yet | | `fail` | 未通过 | The take failed a check, and the row shows the first reason | | `done` | 已生成 | The take is made and passed its checks | `minicut shots` lists every shot with its state. See [minicut shots](/docs/cli/projects#minicut-shots). ## Next [Steps and loops](/docs/cli/steps-and-loops) [Project directory](/docs/cli/project-directory) [Project files](/docs/cli/project-files) --- # Project directory A project is one folder. It holds the series, one folder for each episode and one folder for each shot. One project is one series. `minicut new` makes the project folder with its first episode, `ep01`. The loops then add their files to it, so you and your agent can open any of the work. Characters, locations, props and styles are not in the project folder. They live in your [home folder](/docs/cli/home-folder), and the project lists them by id in `series.json`. With no `--dir`, a project goes in the `projects` folder of your home folder. Each episode is `epNN`, and `ep001` with three digits when you plan more than 99 episodes. Each shot is `cNN`. ```text Project folder rain-shop/ series.json title, screen shape, episode list and library ids source/ sources.json the sources the story comes from, empty at first research.md the researched idea script.md the story and world document episodes/ ep01/ script.md the episode script shots.md the shot sheet assets.md the asset list and the picture prompts prompts.md the video prompts, one section for each shot loops.json the round of each loop mock.sheet.jpg one frame of every shot, made for the Mock loop index.html the episode timeline, empty until the first cut minicut.json the editor settings for this episode music/ the episode's music scenes/ scene files canvas/ canvas boards of this episode clips/ c01/ one folder for each shot prompt.md the video prompt of the shot clip.json the shot's model, settings and picked take lines/ the voice of each spoken line t01.mp4 a take, saved as t01, t02, and on t01.json the record of the take ``` ## Created by minicut new `minicut new` makes `series.json`, `source/sources.json`, and in `ep01` the `clips` and `music` folders, `index.html` and `minicut.json`. Every other entry appears when the step that makes it runs. See [Steps and loops](/docs/cli/steps-and-loops). The fields of each file are on [Project files](/docs/cli/project-files). ## Next [Project files](/docs/cli/project-files) [Home folder](/docs/cli/home-folder) [Shot sheet](/docs/cli/shot-sheet) --- # Home folder MiniCut keeps your settings, library, projects and tools in one home folder. Set MINICUT_HOME to use another folder. The home folder holds everything you own in MiniCut: your settings, the pictures and takes you saved, and your projects. It also holds the programs MiniCut brings. `minicut doctor` shows the folder and whether each part exists. ## Location | Computer | Home folder | |---|---| | macOS and Linux | `~/.minicut` | | Windows | `%LOCALAPPDATA%\minicut` | On Windows, a `%LOCALAPPDATA%` path with non-ASCII characters is not used. The home folder is then `C:\minicut-` plus 8 characters taken from your Windows user. Set `MINICUT_HOME` to a folder to use that folder instead. Every `minicut` command then reads and writes it. See [Global options](/docs/cli/global-options). ## Contents ```text Home folder ~/.minicut/ settings.json your defaults: language, screen shape, resolution, frame rate, projects folder auth.json your sign-in key on Windows and Linux. macOS keeps it in the Keychain library/ characters/ one folder for each saved character, with its pictures locations/ one folder for each saved location props/ one folder for each saved prop styles/ one folder for each saved style takes/ every take you saved, in one folder for each project projects/ your projects, one folder for each canvas/ canvas boards that belong to no project tools/ the programs MiniCut brings. Run minicut setup to download them again cache/ downloads and the model list bin/ the minicut launcher versions/ the installed copies of MiniCut install.log what the last install or update did minicut-home.json the list of names MiniCut made here ``` `minicut setup` makes the folders and `settings.json`. A project folder is described on [Project directory](/docs/cli/project-directory). ## Settings `settings.json` holds the defaults `minicut new` copies into a new project. `"projects_dir"` sets the folder new projects go in. `"auto_update": false` and `"error_reports": false` turn off the automatic update and crash reports. ## Uninstall `minicut uninstall` removes the tools and the app, signs the computer out, stops the app and removes the skill folder. It keeps `projects`, `library`, `canvas` and `settings.json`. With `--all` it removes those too. It removes only the names listed in `minicut-home.json`, so a file of yours in the home folder stays. It refuses a folder with no `minicut-home.json`. See [minicut uninstall](/docs/cli/setup#minicut-uninstall). ## Next [Project directory](/docs/cli/project-directory) [Setup](/docs/cli/setup) [Global options](/docs/cli/global-options) --- # Connect your agent app Add the MiniCut skill and its allow and ask-first rules to your coding agent app, then check that the app has them. MiniCut supports 11 coding agent apps: 10 with a skill folder, and WorkBuddy by upload. Do this for each one you use. The install prompt in [Install with your agent](/docs/cli/install-with-your-agent) already adds the skill and runs `minicut agent-rules`. Use this page to add another app later, or to repair one. Every command here needs MiniCut installed. `minicut install-skill` and `minicut agent-rules` work on a computer that is not signed in. ## Check which apps have the skill 1. Run this command: ```bash Terminal minicut install-skill --status ``` It lists every agent app whose home folder is on this computer. Each line says `installed` with the skill folder, or `not installed` with the command to run. 2. For a script, add `--json`. It prints every app below, with `found`, `installed` and `path`. With no agent app on this computer, `--status --json` prints JSON. The line `No agent app home folder found under` your home folder is printed without `--json`. ## Add the skill to one app 1. Pick the app from the table. The id is the value for `--app`. | App | Id | Skill folder in your home folder | |---|---|---| | Claude Code | `claude-code` | `.claude/skills` | | Codex | `codex` | `.agents/skills` | | OpenCode | `opencode` | `.agents/skills` | | CodeBuddy Code | `codebuddy` | `.codebuddy/skills` | | TRAE | `trae` | `.trae-cn/skills` | | Qoder and Qoder CN | `qoder` | `.qoder/skills` | | Qwen Code | `qwen` | `.qwen/skills` | | Kimi Code | `kimi` | `.agents/skills` | | Cursor | `cursor` | `.agents/skills` | | Cline | `cline` | `.cline/skills` | | WorkBuddy | `workbuddy` | none, it loads skills by upload | 2. Run the command with that id: ```bash Terminal minicut install-skill --app claude-code ``` 3. If the app is open, restart it so it loads the skill. The command copies the skill into a folder named `miniharness-short-drama` in the skill folder. If that folder holds your own earlier copy, add `--force` to replace it. If it holds a different skill, the command does not touch it. Several apps share `.agents/skills`. One copy there serves all of them. For WorkBuddy, `minicut install-skill --app workbuddy` prints the command that builds a ZIP file. Upload that ZIP in WorkBuddy under 技能 > 添加技能 > 上传技能. ## Add the skill to every app on this computer 1. Run this command: ```bash Terminal minicut install-skill --all-found ``` ```text Output Claude Code: skill written to ~/.claude/skills/miniharness-short-drama. Restart Claude Code if it is open, so it loads the skill. Codex: skill written to ~/.agents/skills/miniharness-short-drama. Restart Codex if it is open, so it loads the skill. Claude Code: added the loop hooks (Stop, PreToolUse) to ~/.claude/settings.json Codex: added the loop hooks (Stop, PreToolUse) to ~/.codex/hooks.json Codex: open Codex and type /hooks once to trust the two MiniCut hooks; until then Codex skips them. ``` 2. Restart each app that is open. 3. In Codex, open Codex and type `/hooks` once to trust the two MiniCut hooks. Codex skips them until you do. ## Hooks for Claude Code and Codex For Claude Code and Codex, the install adds two hooks next to the skill. They keep your agent inside the [loops](/docs/cli/checks-and-loops): | Hook | Runs | What it does | |---|---|---| | Stop | `minicut loop guard --hook` | Sends your agent back to work while a loop is mid-round, a job of the project still runs, or real video takes wait for the Videos loop | | Before a write or a command | `minicut loop guard --pre-tool` | Refuses a direct write to the episode timeline and names the `minicut timeline` command to use | Claude Code keeps its hooks in `~/.claude/settings.json`, and Codex in `~/.codex/hooks.json`. The install merges them with your other hooks, and a second run changes nothing. OpenCode has no stop hook, so it gets no loop guard. The skill tells its agent to run `minicut loop next` instead. ## Add the rules for Claude Code and Codex 1. Run this command: ```bash Terminal minicut agent-rules ``` ```text Output Claude Code: added to ~/.claude/settings.json: permissions.allow: Bash(~/.minicut/bin/minicut *) permissions.ask: Bash(~/.minicut/bin/minicut uninstall*) permissions.ask: Bash(~/.minicut/bin/minicut * --yes*) sandbox.excludedCommands: ~/.minicut/bin/minicut * Codex: added to ~/.codex/rules/default.rules: prefix_rule(pattern=["~/.minicut/bin/minicut"], decision="allow") prefix_rule(pattern=["~/.minicut/bin/minicut", "uninstall"], decision="prompt") prefix_rule(pattern=["~/.minicut/bin/minicut", "gen"], decision="prompt") prefix_rule(pattern=["~/.minicut/bin/minicut", "board", "run"], decision="prompt") prefix_rule(pattern=["~/.minicut/bin/minicut", "check", "8"], decision="prompt") prefix_rule(pattern=["~/.minicut/bin/minicut", "write"], decision="prompt") Codex reads its rules when it starts: restart Codex to use them. ``` 2. Restart Codex if it is open. The command writes one edit for each app it finds, with the full path of `minicut` on this computer. It keeps everything already in the file and never writes a rule twice. Run again, it prints `already has every Minicut rule. Nothing changed.` | App | File | Runs without asking | Asks first | |---|---|---|---| | Claude Code | `~/.claude/settings.json` | Every `minicut` command | `uninstall`, and any command with `--yes` | | Codex | `~/.codex/rules/default.rules` | Every `minicut` command | `uninstall`, `gen`, `board run`, `check 8` and `write` | On macOS and Linux, the Claude Code rules also list `minicut` as a command that runs outside the app's sandbox. To see the rules without writing them, add `--dry-run`. To write for one app, add `--app claude-code` or `--app codex`. Add `--json` for one JSON object. ## Check it worked Run `minicut install-skill --status` again. ```text Output Claude Code: installed, ~/.claude/skills/miniharness-short-drama Codex: installed, ~/.agents/skills/miniharness-short-drama ``` ## Errors | Message | What to do | |---|---| | `unknown app "". Apps:` and a list | Use an id from the table above. Exit code 2 | | ` already exists. Add --force to copy the pack over it.` | Add `--force` to replace the earlier copy | | ` exists and is not this skill ... Not touching it.` | Move or rename that folder, then run the command again | | `No agent app home folder found under . Nothing written.` | Start the app once so it makes its home folder, or use `--app` | | `agent-rules writes rules for claude-code and codex only. Got: ` | Use `--app claude-code` or `--app codex`, or leave `--app` out | | ` is not valid JSON (...), so it was not changed. Add these by hand:` | Fix the file, or add the lines the command prints | | A line that starts with `这一行需要你自己运行：` | Your agent app's sandbox blocks the write. The line is Chinese for "run this line yourself". Run the command after it in your own terminal | ## Next [Make the mock](/docs/cli/make-the-mock) [Checks and loops](/docs/cli/checks-and-loops) [Overview](/docs/cli/overview) --- # Make the mock Run three loops, Script, Shot sheet and Mock, to get the whole episode as stills with voices, music and captions. The mock is the whole episode as still pictures with voices, music and captions. You watch it before any video take is made. Your agent runs the loops. You read what each one shows you and say yes. Before you start, sign in and connect your agent app. See [Connect your agent app](/docs/cli/connect-your-agent-app). Every command here needs a signed-in computer. ## Make the project 1. Make the project folder: ```bash Terminal minicut new rain-shop --title "Rain shop" ``` 2. Work inside the `rain-shop` folder from now on. The `minicut loop` commands run in the project folder, or in any folder under it. 3. Pick the video model. Run `minicut models --kind video` and tell your agent which one to use. It writes your pick into `series.json` under `models.video`. The Shot sheet loop does not run without it. ## Run the Script loop 1. Tell your agent your idea. It writes the idea document, the story document and the episode script. 2. Your agent runs: ```bash Terminal minicut loop run script ``` 3. If a file is not written yet, the command lists each missing file, exits with code 3 and uses no round. 4. If a check fails, the command prints each failure with its fix. Your agent fixes the file and runs the command again. A loop stops after 3 rounds. 5. When the loop passes, it prints `PASSED, show the user:` and the script to read. Read `episodes/ep01/script.md`. 6. Say yes. Your agent runs `minicut loop approve script`. ## Run the Shot sheet loop 1. Your agent writes the shot sheet, the asset list and the shot prompts, and makes the pictures of your characters and places with `minicut gen image`. This command uses credits. It shows what it will do and asks before it spends. 2. Your agent runs `minicut loop run sheet`. It checks the three files. If one is missing, it exits with code 3 and uses no round. 3. Open the shot sheet: ```bash Terminal minicut script rain-shop --episode ep01 ``` 4. Read every shot. Say yes. Your agent runs `minicut loop approve sheet`. ## Make the mock pieces The Mock loop needs three things before it runs. `minicut loop run mock` checks for them first. 1. A picture for every shot. Your agent keeps a still as the shot's take: ```bash Terminal minicut save take still.png --kind placeholder --project . --episode ep01 --clip c01 ``` The picture becomes a clip as long as the shot. For a shot in 3D, your agent uses `minicut scene render` with `--clip` instead. See [Scene and music](/docs/cli/scene-and-music). 2. A voice for every spoken line. Your agent makes each line with `minicut gen voice`. This command uses credits. It shows what it will do and asks before it spends. Then it saves the finished lines: ```bash Terminal minicut jobs --wait 300 ``` 3. The music for the episode. Your agent writes the song and runs `minicut music render` on it. See [Scene and music](/docs/cli/scene-and-music). Your agent then lays the pictures, voice lines and captions on the episode timeline. ## Run the Mock loop 1. Your agent runs: ```bash Terminal minicut loop run mock ``` 2. First the command checks, for free, that every shot has a picture, every line has its voice and the music has its file. If something is missing, it lists each one with its fix, exits with code 3 and uses no round. 3. Then it makes the mock's picture sheet, one frame of every shot. A person or a fresh agent looks at the sheet and answers its questions. Until the answers are in, the command exits with code 3 and uses no round. A `no` answer fails the round, and your agent makes a new picture for those shots. 4. Then it renders the mock to `episodes/ep01/renders/mock-r1.mp4`. The number is the round. It plays the render back to check that every spoken line is said. 5. The loop also checks captions, the labeled copy of each picture, the look and the length against the target. See [minicut check mock](/docs/cli/checks-and-loops#minicut-check-mock). 6. Each failure comes with a fix. Your agent applies it and runs the command again. After 3 rounds the loop prints `CAP REACHED, stop and show the user what is still failing`, and you decide. ## Watch the mock 1. Open the episode in the MiniCut app, on the editor tab: ```bash Terminal minicut open rain-shop --episode ep01 --tab editor ``` 2. Watch the mock. It is also the file `episodes/ep01/renders/mock-r1.mp4`. 3. If you want it changed, tell your agent. It fixes the files and runs `minicut loop run mock` again. 4. If it is right, say yes. Your agent runs: ```bash Terminal minicut loop approve mock ``` To stop the loops here, tell your agent to run `minicut loop stop-at mock --reason "Show me the mock first"`. After that, `minicut loop next` names nothing past the mock until you clear the stop with `minicut loop stop-at none`. ## Check it worked Run `minicut loop`. The table shows the Script, Shot sheet and Mock loops as approved. The last line, `next:`, names the next command, followed by a `why:` line. Continue with [Generate and pick video takes](/docs/cli/generate-and-pick-video-takes). ## Errors | Message | What to do | |---|---| | `minicut loop runs inside a project folder (the one with series.json, or any folder under it).` | Run the command in the project folder | | `series.json has no models.video` | Pick a video model and write it into `series.json` under `models.video` | | `NOT RUN, no round used` and a list of missing files | Make each thing on the list, then run the loop again | | `You are not signed in. Ask your agent to run minicut login.` | Sign in. See [Account](/docs/cli/account) | ## Next [Generate and pick video takes](/docs/cli/generate-and-pick-video-takes) [Checks and loops](/docs/cli/checks-and-loops) [Overview](/docs/cli/overview) --- # Generate and pick video takes Make a video take for every shot, check each take, make a failing shot again, and keep the take you want. A take is one video made for one shot. A shot can have several takes, and one of them is the pick, the take the cut uses. Your agent runs the Videos loop. You look at the takes and say which to keep. Start after you approve the mock. See [Make the mock](/docs/cli/make-the-mock). A video take made before the mock is approved prints a warning and is recorded. To go ahead anyway, add `--reason` with your words. Every command here needs a signed-in computer. ## Make a take 1. Your agent makes the take for one shot from its folder: ```bash Terminal minicut gen video episodes/ep01/clips/c01 ``` This command uses credits. It shows what it will do and asks before it spends. After your yes it sends the job. 2. For many shots at once, your agent uses `minicut gen batch`. See [Generate](/docs/cli/generate). 3. Your agent saves the finished takes into the project: ```bash Terminal minicut jobs --wait 300 ``` 4. Each take is saved in its shot's folder as `t01`, then `t02`, and on. A shot has one job at a time. If the shot already has a job, the command names it. Add `--again` to make another take beside it. 5. To see where every shot stands, run: ```bash Terminal minicut shots --episode ep01 ``` A shot reads `queued`, `running` or `saving` while its job runs. It reads `failed` if the job failed. It reads `unchecked` until its take is checked, `fail` if the take failed, and `done` when the take is made. See [minicut shots](/docs/cli/projects#minicut-shots). ## Check the takes 1. Your agent runs: ```bash Terminal minicut loop run videos ``` 2. For each shot, the loop checks the picked take. If the shot has no pick, it checks the newest take. A shot with no video take fails with `no video take yet`. 3. The loop prints one line for each failure, with its fix: | Failure | What it means | |---|---| | `the take has N s and the shot is N s` | The take is more than 0.3 s shorter than its shot, so the cut would hold the last frame still | | `the picture stops moving N to N s` | The picture is still for 1 s or more | | `the light drops from N s and stays down` | The take goes dark and stays dark | | `the picture changes to another shot at N s` | The take holds a cut the shot sheet did not ask for | | `the words heard do not match` | The speech in the take does not match the shot's lines | | `nobody has looked at this take yet` | A person or a fresh agent has not yet looked at the take's picture sheet and answered its questions | 4. For a cut inside a take, the fix can be `TRIM: keep this take, end the shot at N s`. Your agent keeps the take and trims the shot where the line says. 5. For other failures, the fix is another take: `minicut gen video` on that shot, with `take 2 of 3` in the line. Only that shot is made again. ## Say what is wrong When a take fails its look, your agent writes the problem into the shot's prompt, so the next take changes: ```bash Terminal minicut fix episodes/ep01/clips/c01 --take t01 --frame 48 --object "the cup" --problem "the cup floats above the table" --instead "the cup rests on the table" ``` The shot then reads as changed, and the Videos loop runs again. To see a take in detail, your agent runs `minicut check zoom` on it. See [Checks and loops](/docs/cli/checks-and-loops#minicut-check-zoom). To check one take without the loop, run `minicut check take episodes/ep01/clips/c01`. With `--take t02` it checks that take. ## Stop at the take limit A shot gets 3 takes by default. At the limit, the failure line reads `take cap reached (3 of 3): pick the best take of c01 and tell the user what is still wrong`. You decide: pick the best take, or raise the limit. The limit is the `takes` key in `series.json`, such as `"loops": {"takes": 5}`. You can also run `minicut loop run videos --max 5`. ## Pick the take to keep 1. Look at the takes for a shot in the MiniCut app: ```bash Terminal minicut open rain-shop --episode ep01 --tab shots ``` 2. When a take passes and the shot has no pick, the loop sets the pick to that take. It does the same when the pick is a mock picture. A pick you made stays. 3. To pick a take yourself, run: ```bash Terminal minicut asset pick rain-shop ep01 c01 t02 ``` 4. Run `minicut shots --episode ep01` again. Every shot shows `done`. ## Approve the takes 1. Look at the picked take of every shot. When the loop passes, it prints `PASSED, show the user:` and the command to list the picks. 2. Say yes. Your agent runs: ```bash Terminal minicut loop approve videos ``` 3. To end the loop with a failure you accept, run `minicut loop done videos --reason "Good enough, ship it"`. ## Check it worked Run `minicut loop`. The Videos loop shows as approved or done. The `next:` line names the next command, followed by a `why:` line. Continue with [Edit an episode](/docs/cli/edit-an-episode). ## Errors | Message | What to do | |---|---| | `Shot already has job .` | Stop the job with `minicut jobs --stop `, or add `--again` | | `no clip.json in ` | Give the path to a shot folder in an episode | | `take cap reached` | Pick the best take, or raise the limit | | `You are not signed in. Ask your agent to run minicut login.` | Sign in. See [Account](/docs/cli/account) | ## Next [Edit an episode](/docs/cli/edit-an-episode) [Generate](/docs/cli/generate) [Checks and loops](/docs/cli/checks-and-loops) --- # Edit an episode Run the Edit loop, change the cut with the timeline commands, and render the finished episode as a video file. The edit turns the picked takes into one cut: the shots in order, the voice lines, the captions and the music. Your agent runs the Edit loop. You watch the cut and say yes. Start after you approve the Videos loop. See [Generate and pick video takes](/docs/cli/generate-and-pick-video-takes). Every command here needs a signed-in computer. The commands that change or render the cut run in the episode folder, so start with: ```bash Terminal cd rain-shop/episodes/ep01 ``` ## Open the cut 1. Open the episode in the MiniCut app, on the editor tab. The project is `rain-shop`: ```bash Terminal minicut open rain-shop --episode ep01 --tab editor ``` 2. Open the address it prints. The editor shows the cut. 3. If the app does not start, run `minicut edit rain-shop --episode ep01`. See [Editor](/docs/cli/editor). ## Change the cut Change the cut in the editor, or with `minicut timeline`. Never write the cut file `index.html` by hand. The Edit loop fails a hand-written cut, and in Claude Code and Codex a hook refuses the write. 1. List the cut: every track and clip, with its start and end. ```bash Terminal minicut timeline ``` 2. Change the words of a caption, title or card: ```bash Terminal minicut timeline set '#cap-c05-l01' --text "I never left." ``` 3. Fix the captions after you change words or timing. This keeps the words, splits them again and times them to the voice: ```bash Terminal minicut captions ``` 4. If a take is shorter than its shot, the cut holds the take's last frame still. Cut the shot down to its take. Look at the plan first, then apply it: ```bash Terminal minicut timeline fit --plan minicut timeline fit ``` 5. To undo the fit, run `minicut timeline fit --undo`. To undo another change, run `minicut timeline undo RECEIPT`. `RECEIPT` is the undo receipt that the change printed. 6. To look at the cut without a render, save stills: ```bash Terminal minicut snapshot --at 1,3,5 -o snapshots ``` ## Run the Edit loop 1. Your agent runs this: ```bash Terminal minicut loop run edit ``` 2. The command renders the cut to `renders/edit-r1.mp4` in the episode folder. The number is the round. Then it checks the cut and the render. 3. Each failure prints as `FAIL` with a label and a fix: | Label | What it means | |---|---| | `hand edit` | `index.html` was changed by hand. Change the cut with `minicut timeline` or in the editor | | `held frame` | A shot is longer than its take. Run `minicut timeline fit` | | `music fit` | The music was written for a cut more than 1 s longer or shorter than this one. Run `minicut music cuts` for the new shot times, write the song again, then run `minicut music render` | | `repeat` | The same picture plays in two shots. The fix is `minicut timeline trim` | | `cut` | The picture changes inside a shot the shot sheet did not ask for. The fix is `minicut timeline trim` | | `read-back` | The speech in the render does not say a line | | `render` | The cut did not render. The fix is `minicut render lint` | The loop also checks the captions and the timeline itself. 4. Your agent applies each fix and runs the command again. After 3 rounds the loop prints `CAP REACHED, stop and show the user what is still failing`, and you decide. ## Render the finished episode 1. Render the final file from the episode folder: ```bash Terminal minicut render -o renders/ep01.mp4 --quality delivery ``` `--quality` is `draft`, `looks` or `delivery`. 2. Check the finished file from the project folder: ```bash Terminal minicut check render episodes/ep01 episodes/ep01/renders/ep01.mp4 ``` It prints each failure with its fix, then `RESULT: PASS` or `RESULT: FAIL`, and saves the result beside the video file. ## Approve the cut 1. Open the cut with `minicut open rain-shop --episode ep01 --tab editor` and watch it. 2. If it is right, say yes. Your agent runs: ```bash Terminal minicut loop approve edit ``` ## Check it worked Run `minicut loop` in the project folder. Every loop shows as approved or done. The file `episodes/ep01/renders/ep01.mp4` is the finished episode. ## Errors | Message | What to do | |---|---| | `no index.html yet` | The episode has no cut. Your agent lays the first cut, then runs the loop again | | `index.html was changed by hand` | Undo with `minicut timeline undo RECEIPT`, or redo the change with `minicut timeline` or in the editor | | `minicut loop runs inside a project folder (the one with series.json, or any folder under it).` | Run the loop in the project folder | | `You are not signed in. Ask your agent to run minicut login.` | Sign in. See [Account](/docs/cli/account) | ## Next [Editor](/docs/cli/editor) [Checks and loops](/docs/cli/checks-and-loops) [Overview](/docs/cli/overview) --- # Build a 3D scene Write a scene file, check that no body goes through a prop, and draw a still from its camera on your computer. A 3D scene is one file that holds people, props, cameras and a timeline. Your agent writes it, and MiniCut checks it and draws it on your computer. Distances are in metres, the floor is at 0 and turns are in degrees. 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. ## Write the scene 1. Make the folder `episodes/ep01/scenes` in the project if it is not there. A scene for shot 1 is named `c01`, for shot 2 `c02`, and on. 2. Write an operations file in that folder, `c01.scene.ops.json`. It is data: a list of scene operations with their arguments, and no code. ```json c01.scene.ops.json { "ops": [ { "op": "setWorld", "args": [{ "aspect": "9:16" }] }, { "op": "addCharacter", "args": [{ "name": "Lin", "body": "female", "position": [-0.8, 0, 0] }], "as": "lin" }, { "op": "addCharacter", "args": [{ "name": "Chen", "body": "male", "position": [0.8, 0, 0], "facing": "$lin" }] }, { "op": "addProp", "args": [{ "name": "Table", "shape": "table", "position": [0, 0, 0.9] }] }, { "op": "addCamera", "args": ["front_medium", { "name": "Front" }], "as": "cam" }, { "op": "setCamera", "args": ["$cam", { "position": [0, 1.6, 6], "lookAt": [0, 1.4, 0], "fov": 40 }] }, { "op": "setDuration", "args": [4] } ] } ``` `as` names the id that an operation makes, and `$lin` uses it in a later operation. An operation name that does not exist makes `build` print the names it takes. 3. Optional: if your agent writes code, run `minicut scene api`. It prints one import line for a Node.js script. The script ends with `await api.save("episodes/ep01/scenes/c01.scene.json")`, which checks the scene and writes it. MiniCut never runs the script. Your agent runs it with `node`. ## Build the scene file 1. Build the file: ```bash Terminal minicut scene build episodes/ep01/scenes/c01.scene.ops.json ``` It prints `Wrote` with the path of `c01.scene.json`, the count of objects and cameras, the length, and each camera's id and name. 2. Read the camera id in the output. Every build makes new ids, so a camera id from an earlier build no longer fits. `build` checks the scene before it writes. If a check fails, it prints each problem, says `Not written`, and leaves the old file as it was. A file that holds code is refused. ## Check the scene 1. Check that no body goes through a prop or the floor: ```bash Terminal minicut scene check episodes/ep01/scenes/c01.scene.json ``` ```text Output OK ~/.minicut/projects/rain-shop/episodes/ep01/scenes/c01.scene.json: 3 object(s), 1 camera(s), 4 s. Cameras: cam_a6tl (Front). No body goes through a prop or the floor. ``` 2. If it prints problems, change the operations file and build again. Each line names the body part, the prop, how deep and at which second, and how far to move. For example, `Lin's left thigh goes 9 cm into "Table" (p_kg3w), at 0 s`. 3. To go back to the file before the last build, run `minicut scene undo episodes/ep01/scenes/c01.scene.json`. The last 20 versions are kept. ## Draw a still 1. Draw the middle second of the scene: ```bash Terminal minicut scene render episodes/ep01/scenes/c01.scene.json --still middle ``` The command prints `Drawing` with the camera and the second, then `Rendered` with the size in bytes, then the path. With no `--camera`, it uses the scene's own camera. 2. Open the picture. Without `--project` or `--id`, it is in the `cache/stills` folder of your MiniCut home folder, and the command prints its path. A copy in the `labeled` folder beside it has a name tag on every asset, for people to read. 3. Optional: to keep the still in your library as a location, add `--project rain-shop`. 4. Optional: for a smaller picture, add `--draft` for half of each side, or `--size WIDTH` with an even width. 5. Optional: to draw the middle second of every shot scene in an episode, run: ```bash Terminal minicut scene render --project rain-shop --episode ep01 --still middle ``` It draws each `cNN.scene.json` in turn. The last line says how many it drew and how many it did not draw. ## Check it worked The still is a `.png` that shows the scene from the camera. A scene that fails `minicut scene check` is not drawn. The command prints `Not rendered` and the problems. To draw a clip instead of a still, see [minicut scene render](/docs/cli/scene-and-music#minicut-scene-render). ## If a step fails | Message | What to do | |---|---| | `ops[1].op: "NAME" is not a composer op.` | Use one of the operation names the message lists | | `this text reads as code. An ops file holds names, numbers and text, never code.` | Write the value itself, not code that makes it | | `scene build reads data only, never a script.` | Build a file named `NAME.scene.ops.json` | | `Not written: N problem(s).` | Fix the problems printed above it, then build again | | `No camera in c01.scene.json: add one to the scene.` | Add an `addCamera` operation, then build again | | `--still is a second from 0 to 4 (the timeline).` | Give a second inside the scene's length | | `Use --draft or --size , not both.` | Pick one of the two | | `The render page is not on this computer ...` | Run `minicut update`, then render again | | `No headless browser (chrome-headless-shell) on this computer.` | Run `minicut setup`, then render again | ## Next [Scene and music](/docs/cli/scene-and-music) [Write the music](/docs/cli/write-the-music) [Checks and loops](/docs/cli/checks-and-loops) --- # Write the music Read the episode's timing, write a score as a song file, check it, and play it into a music track on your computer. Your agent writes the music as a short Python script. The script saves a song file, which is data: instrument names, notes and times in seconds. MiniCut checks the song file and plays it with the instruments it brings. MiniCut never runs your script. Before you start, sign in and make a project with a shot sheet for the episode, `episodes/ep01/shots.md`. See [Shot sheet](/docs/cli/shot-sheet). The script needs Python 3.9 or newer. To play a song, run `minicut setup` once. It installs the music tools and the instrument samples. The samples are about 396 MB. Run the commands in the project folder, `~/.minicut/projects/rain-shop` here. ## Read the timing 1. List the shots, the cuts and the spoken lines of the episode, in seconds: ```bash Terminal minicut music cuts episodes/ep01 ``` ```text Output ~/.minicut/projects/rain-shop/episodes/ep01: 15.0 s, 3 shot(s), 2 cut(s) C01 0.00 to 5.00 s street sound: rain C02 5.00 to 11.00 s shop sound: C03 11.00 to 15.00 s shop SILENT sound: silence cut 5.00 s into C02 scene change cut 11.00 s into C03 into silence line 5.00 to 11.00 s Lin: Are you open? lines from: shots.md Line (speaker) cells (whole row, rough) ``` The spoken lines come from the `Line (speaker)` column of `shots.md`, rough to the whole shot. When the episode has a `transcript.json`, they come from its word times. Add `--json` to get the same facts as JSON. 2. List the instruments: ```bash Terminal minicut music instruments ``` It prints one line for each instrument with its note range, then the knobs and the reverb presets. A drum instrument lists its pieces instead of notes. ## Write the score 1. Print the import lines for your script: ```bash Terminal minicut music api ``` 2. Make the file `episodes/ep01/music/score.py`. Paste the two lines the command printed at the top. Then write the score. Every time is in seconds. ```python score.py # Paste the two lines that minicut music api printed here. ep = read_episode("episodes/ep01") song = Song(length_s=ep["length_s"], title="ep01 score", tempo=72) strings = song.track("violins", volume_db=-8) strings.chord(chord("D3", "minor"), at=0, length=4, velocity=60) drum = song.track("timpani") for cut in ep["cuts"]: if cut["scene_change"]: drum.hit("low", at=cut["t"], velocity=110) song.duck_under(ep["lines"], db=-8) song.save("episodes/ep01/music/score.song.json") ``` `duck_under` turns the score down under each spoken line. `save` checks the song and writes it. On a problem it writes nothing, prints each problem and exits with code 5. 3. Run the script with your own Python: ```bash Terminal python3 episodes/ep01/music/score.py ``` ```text Output Wrote episodes/ep01/music/score.song.json: 15.0 s, 2 track(s), 4 note(s). Next: minicut music render episodes/ep01/music/score.song.json ``` A song is up to 15 minutes long and has up to 64 tracks. ## Check and play the song 1. Check that the song file can be played: ```bash Terminal minicut music check episodes/ep01/music/score.song.json ``` ```text Output PASS: 15.0 s, 2 track(s), 4 note(s). Next: minicut music render ~/.minicut/projects/rain-shop/episodes/ep01/music/score.song.json ``` If it fails, it prints each problem and `FAIL`, and exits with code 5. Fix the script, run it again and check again. 2. Play the song into audio files: ```bash Terminal minicut music render episodes/ep01/music/score.song.json ``` It writes `score.wav`, `score.mp3`, `score.beats.json`, `score-waveform.png` and `score.report.json` beside the song file. 3. Optional: to play one stretch while you work on it, add `--from 9 --to 12`. To also write each instrument as its own file, add `--stems`. To skip the `.mp3`, add `--no-mp3`. 4. Measure the result against the episode: ```bash Terminal minicut music measure episodes/ep01/music/score.wav --episode episodes/ep01 ``` It reports loudness, peaks, hits on the cuts and the music level under the spoken lines. Change the script and play again until the numbers fit the shot sheet. ## Optional: start from a MIDI file 1. Write a map file that says which instrument plays each MIDI track. A key is `TRACK:CHANNEL` or the track's name. A `drums` key maps a MIDI note to `INSTRUMENT/PIECE`. ```json map.json { "tracks": { "0:0": { "instrument": "piano", "volume_db": -6 } } } ``` 2. Turn the MIDI file into a song file: ```bash Terminal minicut music from-midi episodes/ep01/music/theme.mid --map episodes/ep01/music/map.json ``` It prints `Wrote` with the path of the new `.song.json` file, its length, tracks and notes, and the next command to run. A track or drum note that is not in the map is left out, and the command prints `left out:` with its name. Then check and play the song file as above. ## Check it worked `score.wav` and `score.mp3` are in `episodes/ep01/music`, and the `measure` numbers match what the shot sheet asks for. The waveform picture `score-waveform.png` shows where the music is loud and quiet. ## If a step fails | Message | What to do | |---|---| | `shots.md is missing` | Write the shot sheet first. See [Shot sheet](/docs/cli/shot-sheet) | | `no Python found. Run: minicut setup` | Run `minicut setup`, then run the command again | | `the music tools are not set up (...). Run: minicut setup` | Run `minicut setup`, then run the command again | | `no instrument samples in .... Run: minicut setup (about 396 MB, once). Nothing was rendered.` | Run `minicut setup`, then render again | | `FAIL: N problem(s).` | Fix the problems printed above it in your script, then run it again | | `the song file is over 32 MB` | Make the song smaller | | `Stopped: it ran past the time limit.` | Render a shorter part with `--from` and `--to` | ## Next [Scene and music](/docs/cli/scene-and-music) [Checks and loops](/docs/cli/checks-and-loops) [Setup](/docs/cli/setup) --- # 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 .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) --- # Manage assets Add, rename, set the cover of and remove the characters, locations and props of a project, and keep pictures in your library. An asset is a character, a location or a prop that a project uses. Each one has a name, a description and pictures. Scripts and prompts point at an asset by its name, such as `@Lin Xia`. These commands do what the **资产** tab in the MiniCut app does, with the same rules. Before you start, sign in and make a project. See [Quickstart](/docs/cli/quickstart). Every command here needs a signed-in computer. Each `minicut asset` command prints one line of JSON. Run the commands in the project folder, `~/.minicut/projects/rain-shop` here. ## Add an asset 1. Put a picture of the character in the project folder, `lin.png`. A picture is PNG, JPG or WebP, up to 25 MB, and a command takes up to 12. 2. Add the character with its picture and a note: ```bash Terminal minicut asset add rain-shop characters "Lin Xia" --note "shop owner" lin.png ``` ```json Output {"id":"lin-xia","kind":"characters","name":"Lin Xia","folder":"library/characters/lin-xia"} ``` The `id` comes from the name, in lowercase Latin letters and `-`. A name with no Latin letters gets an id such as `character-01`. Use the `id` in the commands below. The pictures are saved as `image-01`, `image-02`, and on, with their own extension. 3. Optional: add a location or a prop. They need no picture. ```bash Terminal minicut asset add rain-shop locations "Night shop" minicut asset add rain-shop props "Umbrella" ``` A name is 1 to 40 characters and cannot hold `/`, `\`, `@` or a vertical bar. A name that the project already uses is refused with `name_taken`. ## Rename an asset 1. Rename the item by its `id`: ```bash Terminal minicut asset rename rain-shop characters lin-xia "Lin" ``` ```json Output {"name":"Lin","files_changed":0} ``` `rename` changes every `@Lin Xia` in `script.md` and `story.md`, and in `script.md`, `shots.md`, `assets.md` and `prompts.md` of each episode, in every project that uses the item. `files_changed` is how many files it rewrote. ## Set the cover 1. Set the picture that stands for the item, by its file name: ```bash Terminal minicut asset cover rain-shop characters lin-xia image-01.png ``` ```json Output {"cover":"image-01.png"} ``` ## Pick a take 1. Set the take that a shot uses. The arguments are the project, the episode, the shot and the take: ```bash Terminal minicut asset pick rain-shop ep01 c03 t02 ``` ```json Output {"pick":"t02"} ``` ## Remove an asset 1. Remove the item from the project: ```bash Terminal minicut asset remove rain-shop props umbrella ``` ```json Output {"moved":true,"name":"Umbrella"} ``` The item's folder goes to the system Trash. When another project still uses the item, the folder stays in your library, and `moved` is `false`. ## Keep a picture in your library 1. Keep a picture you already have as a character, location, prop or style picture, and list it in the project: ```bash Terminal minicut save character lin.png --id lin-xia --as sheet-02 --project rain-shop ``` It prints `Saved` with the path in your library, and says whether the project already lists the item. When the file is already there, it prints `already in the library, not overwritten`. `minicut save` never writes over a file that is already in the library. To keep a finished video as the take of a shot, see [minicut save](/docs/cli/projects#minicut-save). To make pictures with a model, see [Generate](/docs/cli/generate). ## Check it worked Each command prints its result and exits with code 0. The folder `~/.minicut/library/characters/lin-xia` holds the pictures, and the project's `series.json` lists `lin-xia` under `library.characters`. ## If a step fails The `error` field holds a fixed code. The exit code is 1 when the action is refused. It is 2 when the words after `asset` are wrong. It is 5 when a picture is outside your work folders. | Error | What to do | |---|---| | `name_taken` | Pick a name the project does not use yet | | `bad_name` | Use 1 to 40 characters, with no `/`, `\`, `@` or vertical bar | | `no_project` | Check the project id, or use `.` inside the project folder | | `no_asset` | Use an `id` that the project lists in `series.json` | | `no_file` | Use the file name of one of the item's pictures | | `no_clip` | Check the episode and shot ids. The shot needs a folder in `clips` | | `no_take` | Use a take that the shot has, such as `t02` | | `bad_type` | Give a PNG, JPG or WebP picture | | `too_large` | Give a picture of 25 MB or less | | `bad_request` | Check the kind. It is `characters`, `locations` or `props` | | `path_outside` | Move the picture into your project folder, then add it again | ## Next [Projects](/docs/cli/projects) [Generate](/docs/cli/generate) [Use a canvas board](/docs/cli/use-a-canvas-board) --- # Sign in without a browser Sign in to MiniCut on a computer with no browser, such as over SSH, by confirming a code on your phone or another computer. `minicut login` opens minicut.ai in a browser on the same computer, and the browser sends you back to that computer when you are done. That needs a browser there. In an SSH session, or on Linux with no display, `minicut login` switches to a code sign-in by itself. On any other computer, add `--device` to ask for it. ## Sign in with a code 1. Run the sign-in command on the computer that has no browser. ```bash Terminal minicut login --device ``` 2. Read the address and the code it prints. The lines are `Open this address in your browser:`, the address, and `Code:` with the code. 3. On any computer or phone, open that address. Sign in to minicut.ai, or make an account, and confirm the code. A code lasts 15 minutes. 4. Finish the sign-in. If you typed step 1 in your own terminal, it waits for you and finishes by itself, so skip this step. If your agent ran step 1, the command returned at once and printed `When you have confirmed it, run:` with the line to run. Run that line on the computer where you ran step 1. ```bash Terminal minicut login --complete ``` The code is kept on the computer that asked for it, so `--complete` must run there, not on the phone or computer where you confirmed. ## Wait for the confirmation `minicut login --complete` checks for up to 7 seconds, once every 5 seconds. If you have not confirmed the code yet, it prints `Waiting for you to confirm on minicut.ai.` and the line to run again, and exits with code 0. Confirm the code, then run it again. When the code is confirmed, it prints `Signed in.` and your account. The key is saved as described on [Account](/docs/cli/account). ## Check the sign-in Run `minicut status`. A signed-in computer shows `Signed in as` and your account. ```bash Terminal minicut status ``` ## Errors | Message | Exit code | What to do | |---|---|---| | `Sign-in was cancelled on minicut.ai.` | 10 | Run `minicut login --device` again and confirm the code | | `This sign-in code expired. Run minicut login again.` | 10 | Run `minicut login --device` for a new code. This also appears when no code is waiting on this computer | | `Could not reach minicut.ai.` | 7 | Connect to the internet and run the same command again. Behind a proxy, see [Use MiniCut in China mainland](/docs/cli/use-minicut-in-china-mainland) | More messages and fixes are on [Troubleshooting](/docs/cli/troubleshooting). ## Next [Account](/docs/cli/account) [Troubleshooting](/docs/cli/troubleshooting) --- # Use MiniCut in China mainland Install MiniCut with the China mainland region, download tools from mirrors, set a proxy, and switch MiniCut to Chinese. MiniCut has one setting for the region, `region` in `settings.json`, and it is `global` or `cn`. The region decides which download sites the install, `minicut update` and `minicut setup` use. A proxy and the language are two more settings you can change on your own. ## Install with the cn region 1. Run the install line with `--region cn`. On Windows, use `-Region cn`. The lines are on [Install in a terminal](/docs/cli/install-in-a-terminal). 2. If you give no region, the install times both download sites for up to 5 seconds each and uses the faster one. The install saves the region. `minicut update` and `minicut setup` read it from `settings.json`, so you do not repeat it. ## Download tools from mirrors With the cn region saved, `minicut setup` prints `region: cn (settings.json), so every host uses its mirror, as with --china` and uses a mirror for every download. On another region, add `--china` to get the same. ```bash Terminal minicut setup --china ``` Without the flag or the cn region, setup times each download site first. It uses the mirror for any site that does not answer within 4 seconds. To see every download, its source and its size first, add `--dry-run`. It downloads nothing and writes nothing. ```bash Terminal minicut setup --china --dry-run ``` Setup does not bring Python 3.12 or ffmpeg. When one is missing, setup prints a line starting `MISSING:` with the download site for your region, then exits with code 4. Install it and run `minicut setup` again. With `--china`, files from GitHub come through a third-party proxy, and MiniCut checks each file's SHA256 before it uses it. ## Set a proxy 1. Save the proxy. Every `minicut` command and the MiniCut app then use it. ```bash Terminal minicut network --proxy http://192.0.2.10:7890 ``` ```text Output Proxy saved: http://192.0.2.10:7890 ``` 2. Check what is saved. ```bash Terminal minicut network ``` ```text Output Proxy: http://192.0.2.10:7890 ``` 3. To stop using it, remove it. ```bash Terminal minicut network --direct ``` ```text Output No proxy: every command connects directly. ``` If your proxy needs a login, put it in the address: `http://USER:PASSWORD@HOST:PORT`. MiniCut saves the address and the user name in `settings.json`. It saves the password in the key store, never in a file. If `HTTPS_PROXY` is set when you install MiniCut, the install saves that proxy for you. A proxy you set in `HTTPS_PROXY`, `HTTP_PROXY` or `NO_PROXY` in your shell is used as it is. The saved proxy is used only when `HTTPS_PROXY` is not set. Calls to the MiniCut app on your own computer (`127.0.0.1` and `localhost`) skip the proxy. If the saved proxy refuses the connection, the command connects directly once and prints this line on stderr. Run the command it names to stop using the proxy. ```text Message 代理 HOST 连不上，已直接连接；运行 minicut network --direct 可以不再用它 ``` An address that is not `http://HOST:PORT` prints `Invalid URL` or `a proxy is http://host:port, got` with what you typed, and exits with code 5. ## Switch the language The MiniCut app opens in Chinese until you choose a language. `minicut lang` shows the language and `minicut lang en` switches it. The open app picks the change up within a few seconds. ```bash Terminal minicut lang en ``` ```text Output English (ui_language en) ``` ```bash Terminal minicut lang zh ``` ```text Output 中文 (ui_language zh) ``` Any other value prints `Usage: minicut lang [zh|en] [--json]` and exits with code 2. `minicut login --lang zh` saves the same setting and opens the sign-in page in Chinese. Without `--lang` and with no saved language, the sign-in page opens in English. ## Reach minicut.ai Sign-in, your account and every command that makes a picture, a voice or a video go through minicut.ai. If a command cannot reach it, it exits with code 7. A computer that signed in keeps working offline for 7 days, and each command prints one `Offline:` line on stderr. See [Account](/docs/cli/account). ## Next [Install in a terminal](/docs/cli/install-in-a-terminal) [Setup](/docs/cli/setup) [Troubleshooting](/docs/cli/troubleshooting) --- # Update and uninstall Update MiniCut yourself or let it update by itself, turn the automatic update off, and remove MiniCut with or without your projects. MiniCut keeps your projects, library, canvas and `settings.json` through every update. An uninstall keeps them too, unless you ask it not to. ## Update MiniCut 1. Check your version. The line `Minicut CLI` shows it. ```bash Terminal minicut status ``` 2. Run the update. ```bash Terminal minicut update ``` 3. Wait for it to finish. It ends with `updated to` and the new version. If you already had the newest version, it ends with `ready`. Then it prints `Log:` with the path of the install log and `minicut:` with the full path of the command. The update installs the newest version beside the one you have, for the region saved at install. You stay signed in. The MiniCut app restarts on the new files, which ends the session of an open app page. Commands that are already running finish on the old files. MiniCut keeps the old version for one more update, so it can go back to it. If the new app does not start within 10 seconds, MiniCut goes back to your old version and the update exits with code 2. If Python 3.12 or ffmpeg is missing, the update still finishes. It prints a `MISSING:` line. Install the tool, then run `minicut setup`. If another update is running, the command prints `Another Minicut update is running on this computer. Run minicut update again when it has finished.` and exits with code 75. The command is described in [Setup](/docs/cli/setup#minicut-update). If another command prints `This Minicut is too old. Run minicut update, then the same command again.`, run the update first. That message comes with exit code 12. ## Automatic updates Automatic updates are on. Any `minicut` command starts a check in the background, and no command waits for it. A check runs at most once a day. The first one runs a day after the first command that follows the install. `minicut update`, `minicut uninstall` and `minicut setup` start no check. MiniCut updates by itself only when all of these are true: - The newest version is higher than yours. MiniCut never goes back to a lower version. - It is your computer's turn. A new version reaches computers in stages. - No MiniCut app page was used in the last 10 minutes. If your computer's turn has not come, an app page was in use, or the check cannot reach minicut.ai, MiniCut tries again in an hour. After an automatic update, your next command prints one line on stderr, once: ```text Message Minicut updated to VERSION. ``` ## Turn off automatic updates Do any one of these. The update then happens only when you run `minicut update`. - Set the environment variable `MINICUT_NO_AUTOUPDATE` to `1`. - Add `"auto_update": false` to `settings.json` in your MiniCut home folder, `~/.minicut` on macOS and Linux. Keep the other keys in the file. - Set `CI`. MiniCut makes no automatic update when `CI` is set to anything except `0` or `false`. ```json settings.json { "auto_update": false } ``` To check, run `minicut status`. Its last line shows `auto_update` and, when it is off, the reason. ```bash Terminal MINICUT_NO_AUTOUPDATE=1 minicut status ``` ```text Output auto_update: {"on":false,"off_because":"MINICUT_NO_AUTOUPDATE is set","last_check":null,"last_result":null,"next_check":null} ``` ## Uninstall MiniCut 1. Run the uninstall. It asks nothing and starts at once. If your agent runs it, Claude Code and Codex ask you first when you have run `minicut agent-rules`. ```bash Terminal minicut uninstall ``` 2. To remove your projects, library, canvas and settings too, add `--all`. ```bash Terminal minicut uninstall --all ``` 3. Check the exit code. 0 means MiniCut is removed. 7 means it is removed, but minicut.ai did not answer. Then this computer stays on the **Devices** page of your account until you remove it there. The uninstall prints one line for each step it did, such as `signed out`, `removed the login item` and `removed the tools and the app; kept projects, library, canvas, settings.json`. The steps are listed under `minicut uninstall` on [Setup](/docs/cli/setup#minicut-uninstall). ## Left behind | Item | `minicut uninstall` | `minicut uninstall --all` | |---|---|---| | Sign-in key of this computer | Removed | Removed | | The MiniCut app, the login item, the tools and old versions | Removed | Removed | | The `minicut` line in your shell profile, or in your Path on Windows | Removed | Removed | | The MiniCut skill folder in every agent app, and the MiniCut hooks in Claude Code and Codex | Removed | Removed | | `projects`, `library`, `canvas` and `settings.json` | Kept | Removed | | The rules `minicut agent-rules` wrote | Kept | Kept | | Other skills and other hooks | Kept | Kept | | Files in the home folder that MiniCut did not make | Kept, and the command says how many | Kept, and the command says how many | | The home folder | Kept | Removed, only if the install made it and nothing else is left in it | If the home folder has no `minicut-home.json`, the uninstall changes nothing. It prints `FOLDER has no Minicut install marker (minicut-home.json), so it may hold files that are not Minicut's. Nothing was removed.` and exits with code 1. `FOLDER` is the path of the home folder. To install again, run the install line from [Install in a terminal](/docs/cli/install-in-a-terminal). The install keeps the `projects`, `library`, `canvas` and `settings.json` it finds in the home folder. ## Next [Setup](/docs/cli/setup) [Troubleshooting](/docs/cli/troubleshooting) [Changelog](/docs/cli/changelog) --- # Account Commands that sign this computer in to minicut.ai, sign it out, and show which account it uses. Most commands need this computer signed in to minicut.ai. Signed out, they print `You are not signed in. Ask your agent to run minicut login.` and exit with code 10. Flags every command takes, and every exit code, are on [Global options](/docs/cli/global-options). These commands run signed out: `minicut` with no command, `open`, `login`, `logout`, `status`, `lang`, `doctor`, `setup`, `update`, `network`, `uninstall`, `install-skill` and `agent-rules`. The CLI confirms the sign-in with minicut.ai at most once a day. Offline, a confirmed sign-in keeps working for 7 days. Each command then prints one line on stderr, such as: ```text Output Offline: minicut.ai was last reached 2 days ago. Minicut keeps working offline for 5 more days. ``` After 7 days offline, commands stop with exit code 7 until minicut.ai answers again. ## minicut login Signs this computer in to minicut.ai and saves its key. ### Usage ```text Usage minicut login [--lang {en|zh}] [--device] [--json] minicut login --complete [--json] ``` ### Details `minicut login` opens minicut.ai in your browser and waits up to 10 minutes while you sign in. When you are back, it saves the key for this computer and prints your account. With `--device`, nothing has to open on this computer. The command prints an address and a code, then returns. Open the address on any computer or phone, sign in, and confirm the code. Then run `minicut login --complete` to finish. In an SSH session, or on Linux with no display, `minicut login` uses this code sign-in by itself. `minicut login --complete` checks for up to 7 seconds. If you have not confirmed the code yet, it prints `Waiting for you to confirm on minicut.ai.` and the line to run again. Your agent runs it every 10 seconds until it says signed in. If you type `minicut login --device` in your own terminal, it waits for the code itself, with no second command. A computer that is already signed in prints `Already signed in.` and the account, and changes nothing. The sign-in records this computer's name, its system and the CLI version. You see them on the **Devices** page of your account on minicut.ai. On macOS the key goes in the Keychain. On Windows and Linux it goes in `auth.json` in your MiniCut home folder, readable only by you. ### Options | Flag | Type | Default | Description | |---|---|---|---| | `--lang` | `en` or `zh` | the saved language, else `en` | The language of the sign-in page and the MiniCut app. Saved in `settings.json`, also on a computer that is already signed in | | `--device` | switch | off | Sign in with an address and a code instead of opening a browser here | | `--complete` | switch | off | Finish a `--device` sign-in after you confirm the code | | `--json` | switch | off | Print one JSON line for each state | ### Examples #### Sign in from your agent's shell ```bash Terminal minicut login --device --lang en ``` It prints `Open this address in your browser:` (or `Opened minicut.ai in your browser.`), the address, `Code:` with the code, and the line to run when you have confirmed it. #### Finish a code sign-in ```bash Terminal minicut login --complete ``` When you have confirmed the code, it prints `Signed in.` and your account. Before that, it prints `Waiting for you to confirm on minicut.ai.` ### Output With `--json`, each state is one line on stdout with a `state` field: | `state` | When | Other fields | |---|---|---| | `waiting` | The browser sign-in started | `url`, `browser_opened`, `expires_in` (seconds) | | `code_sent` | `--device` printed a code | `user_code`, `verification_uri`, `verification_uri_complete`, `expires_in`, `browser_opened`, `next_step` | | `pending` | `--complete` found the code not yet confirmed | `next_step`, the command to run again | | `signed_in` | The key is saved | `key_store` (`keychain` or `file`), `account`, and `already: true` when it was signed in before | Exit code 0 means signed in, or waiting as planned. A refusal prints the error and exits with code 10: | Message | What to do | |---|---| | `Sign-in was cancelled on minicut.ai.` | Run `minicut login` again and confirm on minicut.ai | | `This sign-in code expired. Run minicut login again.` | Run `minicut login --device` again for a new code | | `This computer was signed out on minicut.ai.` | Run `minicut login` again | Exit code 7 means MiniCut could not reach minicut.ai. Connect to the internet and run the same command again. ## minicut logout Signs this computer out and deletes its key. ### Usage ```text Usage minicut logout [--json] ``` ### Details `minicut logout` asks minicut.ai to remove this computer's key, then deletes the key here, whatever the answer. Your projects, library and settings stay on this computer. If minicut.ai does not answer, this computer stays on the **Devices** page until you remove it there. ### Examples #### Sign out ```bash Terminal minicut logout ``` On a computer that is not signed in: ```text Output Not signed in. ``` Signed in, it prints `Signed out.` #### Sign out with JSON ```bash Terminal minicut logout --json ``` ```json Output {"state":"signed_out","revoked":false,"was_signed_in":false} ``` ### Output `revoked` is `true` when minicut.ai removed the key. `was_signed_in` is `true` when this computer had a key. The exit code is always 0. ## minicut status Shows the account, where the key is kept, the CLI version and whether the MiniCut app is running. ### Usage ```text Usage minicut status [--json] ``` ### Details `minicut status` runs signed out. Signed in, it asks minicut.ai for the account each time. It also shows the last line of the install log, the MiniCut app's address on this computer, and whether automatic updates are on. ### Examples #### Show the status ```bash Terminal minicut status ``` It prints one line for each item in Details. Signed in, the first lines show your account. #### Show the status as JSON ```bash Terminal minicut status --json ``` It prints one JSON object with the fields below. ### Output | Field | Description | |---|---| | `signed_in` | `true` when minicut.ai accepted this computer's key | | `account` | The account, the same object `minicut me --json` prints, or `null` | | `key_store` | `keychain`, `file`, or `null` when there is no key | | `cli_version` | The installed CLI version | | `install_log` | The last line of the install log, or `null` | | `overrides` | Settings that change where the CLI connects. `[]` on a normal install | | `app_address` | The address of the MiniCut app on this computer | | `app_running` | `true` when the MiniCut app answers at that address | | `auto_update` | `on`, the reason it is off when it is off, and the last and next update check | | `error` | Only when minicut.ai refused the key or could not be reached | Exit code 0, or 7 when this computer is signed in and minicut.ai could not be reached. ## minicut me Shows the signed-in account. ### Usage ```text Usage minicut me [--json] ``` ### Details `minicut me` asks minicut.ai every time, so it shows the account as it is now. It prints your account and this computer's name. A value minicut.ai did not send prints as `unknown`. ### Examples #### Show the account ```bash Terminal minicut me ``` On a computer that is not signed in: ```text Output You are not signed in. Ask your agent to run minicut login. ``` #### Show the account as JSON ```bash Terminal minicut me --json ``` On a computer that is not signed in: ```json Output {"error":{"code":"signed_out","message":"You are not signed in. Ask your agent to run minicut login.","url":null,"request_id":null}} ``` ### Output Signed in, `--json` prints the account object. Exit code 0 when signed in, 10 when not, 7 when minicut.ai could not be reached. ## See also [Setup](/docs/cli/setup) [Global options](/docs/cli/global-options) [Quickstart](/docs/cli/quickstart) --- # Setup Commands that open the MiniCut app, check and install the tools MiniCut needs, connect your agent app, and update or remove MiniCut. Every command on this page runs signed out. Flags every command takes, and every exit code, are on [Global options](/docs/cli/global-options). Your MiniCut home folder is `~/.minicut` on macOS and Linux, and `%LOCALAPPDATA%\minicut` on Windows. Set `MINICUT_HOME` to use another folder. ## minicut Opens the MiniCut app in your browser, and starts it first if it is not running. ### Usage ```text Usage minicut ``` ### Details The MiniCut app runs on your computer at `http://127.0.0.1:7311/`, or at the port in `MINICUT_PORT`. If the app is not running, `minicut` starts it through the login item. The login item starts the app when you log in to your computer. It waits up to 10 seconds for the app to answer, then prints the address and opens it. If an app page is already open, it prints the address and opens no second tab. Inside an agent's sandbox, where the command cannot reach the app, it prints the address for you to open. ### Output | Message | Exit code | What to do | |---|---|---| | `Opened the Minicut app in your browser.` | 0 | Nothing | | `The Minicut app is already open in your browser.` | 0 | Switch to that tab | | `Open this address in your browser.` | 0 | Open the address printed above it | | `The Minicut app is running. Open this address in your browser.` | 0 | Open the address yourself | | `Port 7311 is used by another program. Set MINICUT_PORT to a free port, then run minicut again.` | 2 | Set `MINICUT_PORT`, then run `minicut` again | | `The Minicut app did not start.` | 2 | Run `minicut doctor`, then `minicut` again | ## minicut open Opens the MiniCut app at one episode of a project, on the tab you name, and prints that address. ### Usage ```text Usage minicut open PROJECT [--episode EPISODE] [--tab {editor|script|shots|checks|assets}] [--no-open] ``` Replace the following: - `PROJECT`: the project id from `minicut new`. - `EPISODE`: an episode id such as `ep01`. ### Details `minicut open` starts the app the same way `minicut` does, then opens the project at the episode and tab you name. A link to a project tab opens even when another app page is already open. ### Options | Flag | Type | Default | Description | |---|---|---|---| | `--episode` | episode id | `ep01` | The episode to open | | `--tab` | `editor`, `script`, `shots`, `checks` or `assets` | `editor` | The tab to open. `editor` is the 剪辑 tab | | `--no-open` | switch | off | Print the address and open nothing | ### Examples #### Open the editor on the first episode ```bash Terminal minicut open snow-bus ``` On a computer with no project of that id: ```text Output No project snow-bus in ~/.minicut/projects. ``` #### Open with a project id that is not valid ```bash Terminal minicut open "Snow Bus" ``` ```text Output Not a project id: Snow Bus. Use the id from minicut new (letters, digits and -). ``` ### Output Exit code 0 when the app opened or printed its address. Exit code 2 when the project, episode or tab is wrong, or the app did not start. With no `PROJECT`, it prints the usage line and exits with code 2. ## minicut doctor Shows your system, your MiniCut home folder, free disk space and every tool MiniCut uses, with its state and version. ### Usage ```text Usage minicut doctor ``` ### Details `minicut doctor` reads your computer and changes nothing. It never downloads anything. It prints: 1. Your system and the tools folder. 2. The Node and Python versions it found. 3. The free disk space, against the 5 GB that setup needs. 4. Each folder of your MiniCut home folder, and whether it exists. 5. A table of tools with the columns **Tool**, **State**, **Version** and **Where**. 6. How many tools are missing, and the command to run next. The exit code is 0, also when tools are missing. ## minicut setup Makes your MiniCut home folder, then installs the tools it is missing. ### Usage ```text Usage minicut setup [--china] [--dry-run] [--local-speech] [--no-tools] ``` ### Details `minicut setup` makes the home folder with `settings.json` and the `library`, `projects`, `tools` and `cache` folders. Then it downloads each missing tool into the `tools` folder. Tools that are already installed are skipped. Setup needs 5 GB of free disk. Without `--china`, it times each download site first and uses its mirror when the site does not answer within 4 seconds. With `--china`, it uses the mirrors for everything. If the install saved the China mainland region, setup uses the mirrors without the flag. Setup does not bring Python 3.12 or ffmpeg. When one is missing, it prints a line starting `MISSING:` with the official download site for your region. It does every other step, then exits with code 4. Install the missing one, then run `minicut setup` again. Only one setup runs at a time. A second one waits, then skips what the first one installed. Setup ends with `Done. Run: minicut doctor`. ### Options | Flag | Type | Default | Description | |---|---|---|---| | `--china` | switch | off | Use the China mainland mirrors for every download | | `--dry-run` | switch | off | List every download, its source and its size. Downloads nothing and writes nothing | | `--local-speech` | switch | off | Also install the 1 GB local speech models | | `--no-tools` | switch | off | Make the home folder only. Install no tools | ### Examples #### See what setup would download ```bash Terminal minicut setup --dry-run ``` It ends with the total size of known downloads and `Dry run: nothing downloaded, nothing written.` #### Install the tools in China mainland ```bash Terminal minicut setup --china ``` ### Output | Exit code | Meaning | What to do | |---|---|---| | 0 | Every tool is installed | Run `minicut doctor` | | 1 | A download failed. The line starts with `FAILED` and names the tool | Run `minicut setup` again | | 2 | The tools folder cannot be written from here, such as inside an agent's sandbox. Setup prints the command for you to run | Run that command in your own terminal | | 3 | `REFUSED: under 5 GB free. Free some space and run again.` | Free disk space, then run setup again | | 4 | Python 3.12 or ffmpeg is missing. The `MISSING:` line names the download site | Install it, then run setup again | ## minicut update Installs the newest MiniCut version beside the one you have. ### Usage ```text Usage minicut update ``` ### Details `minicut update` downloads the newest version for the region saved at install, and installs it beside the current one. The MiniCut app restarts on the new files. Commands that are already running finish on the old files. MiniCut also checks for an update by itself, at most once a day, as a second program that no command waits for. It never updates while an app page is in use. After it updates, the next command prints one line on stderr. To turn the automatic update off, see [Global options](/docs/cli/global-options#environment-variables). ### Output The update prints its progress as it runs. Exit code 0 when it finished. If another update is running, it prints this line and exits with code 75: ```text Output Another Minicut update is running on this computer. Run minicut update again when it has finished. ``` ## minicut network Saves a proxy that every command and the MiniCut app use, or removes it. ### Usage ```text Usage minicut network [--proxy URL | --direct] [--json] ``` Replace the following: - `URL`: the proxy address, in the form `http://HOST:PORT`. ### Details `minicut network --proxy` saves the proxy in `settings.json`. A password in the address goes into the key store, not the file. `--direct` removes the proxy. With no flag, it shows the saved proxy. If `HTTPS_PROXY` is set when you install MiniCut, the install saves that proxy for you. ### Options | Flag | Type | Default | Description | |---|---|---|---| | `--proxy` | URL | none | Save this proxy | | `--direct` | switch | off | Remove the saved proxy and connect directly | | `--json` | switch | off | Print one JSON object | ### Examples #### Save a proxy ```bash Terminal minicut network --proxy http://192.0.2.10:8080 ``` ```text Output Proxy saved: http://192.0.2.10:8080 ``` #### Show the saved proxy ```bash Terminal minicut network ``` ```text Output Proxy: http://192.0.2.10:8080 ``` #### Remove the proxy ```bash Terminal minicut network --direct ``` ```text Output No proxy: every command connects directly. ``` ### Output With `--json` and no other flag, it prints `{"proxy":null}` or the saved address. Exit code 0, or 5 when the address is not in the form `http://HOST:PORT`: ```text Output a proxy is http://host:port, got ftp://x ``` ## minicut uninstall Signs this computer out, stops the MiniCut app and removes MiniCut. Your projects and library stay. ### Usage ```text Usage minicut uninstall [--all] [--json] ``` ### Details `minicut uninstall` runs these steps in order: 1. Signs this computer out on minicut.ai and deletes its key. 2. Stops the MiniCut app and removes the login item, so nothing starts it again. 3. Removes the MiniCut skill folder from every agent app, and the MiniCut hooks from Claude Code and Codex. Other skills and hooks stay. 4. Removes `minicut` from your shell profile, or from your Path on Windows. 5. Removes the tools and the app from your MiniCut home folder. It keeps `projects`, `library`, `canvas` and `settings.json`. With `--all`, it removes those too. It only removes files MiniCut made, and says how many other files it left. ### Options | Flag | Type | Default | Description | |---|---|---|---| | `--all` | switch | off | Also remove your projects, library, canvas and settings | | `--json` | switch | off | Print one JSON object | ### Output It prints one line for each step it did. With `--json`: ```json JSON shape {"state": "uninstalled", "revoked": true, "kept": ["projects", "library", "canvas", "settings.json"], "home": "~/.minicut"} ``` `kept` is `[]` with `--all`. Exit codes: | Exit code | Meaning | |---|---| | 0 | MiniCut is removed | | 1 | The home folder has no MiniCut install marker (`minicut-home.json`). Nothing was removed | | 7 | MiniCut is removed, but minicut.ai did not answer. Remove this computer on the **Devices** page of your account | ## minicut install-skill Copies the MiniCut skill pack into an agent app's skill folder, so your coding agent knows how to run MiniCut. ### Usage ```text Usage minicut install-skill --app APP [--force] minicut install-skill --all-found [--force] minicut install-skill --status [--json] ``` Replace the following: - `APP`: the agent app id from the table below. ### Details The skill pack goes in a folder named `miniharness-short-drama` inside the app's skill folder. For Claude Code and Codex, it also adds the MiniCut loop hooks to the app's settings. Restart the agent app if it is open, so it loads the skill. With no flag, the command lists the apps and their folders, and exits with code 2. | `APP` | Agent app | Skill folder | |---|---|---| | `claude-code` | Claude Code | `~/.claude/skills/miniharness-short-drama` | | `codex` | Codex | `~/.agents/skills/miniharness-short-drama` | | `opencode` | OpenCode | `~/.agents/skills/miniharness-short-drama` | | `codebuddy` | CodeBuddy Code | `~/.codebuddy/skills/miniharness-short-drama` | | `trae` | TRAE | `~/.trae-cn/skills/miniharness-short-drama` | | `qoder` | Qoder and Qoder CN | `~/.qoder/skills/miniharness-short-drama` | | `qwen` | Qwen Code | `~/.qwen/skills/miniharness-short-drama` | | `kimi` | Kimi Code | `~/.agents/skills/miniharness-short-drama` | | `cursor` | Cursor | `~/.agents/skills/miniharness-short-drama` | | `cline` | Cline | `~/.cline/skills/miniharness-short-drama` | ### Options | Flag | Type | Default | Description | |---|---|---|---| | `--app` | app id | none | Install into this one app | | `--all-found` | switch | off | Install into every app whose home folder is on this computer | | `--status` | switch | off | Show which apps are found and which have the skill | | `--force` | switch | off | Replace a MiniCut skill folder that is already there | | `--json` | switch | off | With `--status`, print one JSON object | ### Examples #### Install the skill for Claude Code ```bash Terminal minicut install-skill --app claude-code ``` ```text Output Claude Code: copied the skill pack to ~/.claude/skills/miniharness-short-drama Claude Code: added the loop hooks (Stop, PreToolUse) to ~/.claude/settings.json ``` #### Show which apps have the skill ```bash Terminal minicut install-skill --status ``` ```text Output Claude Code: installed, ~/.claude/skills/miniharness-short-drama Codex: not installed. Run: minicut install-skill --app codex ``` ### Output Exit code 0 when the skill is installed or the status printed. Exit code 2 in these cases: | Message | What to do | |---|---| | ` already exists. Add --force to copy the pack over it.` | Add `--force` | | `No agent app home folder found under ~. Nothing written.` | Install your agent app first, or use `--app` | | `unknown app "".` | Use an id from the table above | ## minicut agent-rules Writes the rules that let Claude Code or Codex run `minicut` commands, and ask you first before the ones that spend or remove. ### Usage ```text Usage minicut agent-rules [--app {claude-code|codex}] [--dry-run] [--json] ``` ### Details For Claude Code, `minicut agent-rules` adds rules to `~/.claude/settings.json`. For Codex, it adds them to `~/.codex/rules/default.rules`. With no `--app`, it writes for each of the two that is on this computer. Each rule names the full path of the `minicut` launcher on this computer. Rules that are already there are not added twice, and every other rule stays. Restart Codex after the rules are written, so it reads them. ### Options | Flag | Type | Default | Description | |---|---|---|---| | `--app` | `claude-code` or `codex` | both, when found | The agent app to write rules for | | `--dry-run` | switch | off | Print the rules it would add. Write nothing | | `--json` | switch | off | Print one JSON object | ### Examples #### See the rules for Claude Code ```bash Terminal minicut agent-rules --app claude-code --dry-run ``` ```text Output Claude Code: would add to ~/.claude/settings.json: permissions.allow: Bash(~/.minicut/bin/minicut *) permissions.ask: Bash(~/.minicut/bin/minicut uninstall*) permissions.ask: Bash(~/.minicut/bin/minicut * --yes*) sandbox.excludedCommands: ~/.minicut/bin/minicut * ``` ### Output Exit code 0 when the rules are written, or already there. Exit code 2 when neither app is on this computer, or when the settings file is not valid JSON. In that case the command prints the rules to add by hand. With neither app, it prints: ```text Output No Claude Code (~/.claude) or Codex (~/.codex) on this computer. Nothing written. ``` ## See also [Account](/docs/cli/account) [Global options](/docs/cli/global-options) [Install with your agent](/docs/cli/install-with-your-agent) [Install in a terminal](/docs/cli/install-in-a-terminal) --- # 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 | |---|---| | `"" cannot be a project id.` | Use lowercase letters, digits and `-`, up to 24, and put the real title in `--title` | | `already exists: ` | 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 (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` | | ` 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: ` | 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: ` | 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 .` | Use an episode that `series.json` lists | | `no length for : 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 .` | 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) --- # Generate Commands that make pictures, video takes, voice lines and words, list models, save finished jobs, and run canvas boards. 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 gen image Makes one picture for a character, location, prop or style in your library. ### Usage ```text Usage minicut gen image OUT_FILE --prompt-file PROMPT_FILE --model MODEL --target KIND:ID [--project PROJECT] [--episode EPISODE] [--size W*H | --res RESOLUTION --aspect RATIO | --quality QUALITY] [--on {blank|PICTURE}] [--ref PICTURE ...] [--name NAME] [--json] ``` Replace the following: - `OUT_FILE`: the picture file to make, such as `lin-xia.png`. - `PROMPT_FILE`: a text file with the words that describe the picture. - `MODEL`: an image model name from [minicut models](#minicut-models). - `KIND:ID`: what the picture is for. `KIND` is `character`, `location`, `prop` or `style`, and `ID` is the item's id. - `PROJECT`: a project id or the path to a project folder. - `EPISODE`: an episode id such as `ep01`. - `W*H`: the size in pixels, such as `1024*1536`. - `RESOLUTION`, `RATIO`, `QUALITY`: values the model lists in its settings. - `PICTURE`: a picture file on your computer. - `NAME`: the short name people read on the asset card. ### Details This command uses credits. It shows what it will do and asks before it spends; `--yes` skips the question. It does not wait for the picture. It sends the job and returns, and [minicut jobs](#minicut-jobs) saves the picture into your library when it is done. With no size flag, the picture is asked at the project's screen shape when the model lists it. When it does not, the command says so and asks you to add `--aspect`. ### Options | Flag | Type | Default | Description | |---|---|---|---| | `--prompt-file` | file | none | The words that describe the picture. Needed | | `--model` | name | none | The image model. Needed. There is no default model | | `--target` | `KIND:ID` | none | The library item the picture is for. Needed | | `--project` | id or folder | none | The project the item belongs to | | `--episode` | episode id | none | The episode the picture is for | | `--size` | `W*H` | the project's shape | The size in pixels | | `--res` | value | none | The resolution, used with `--aspect` | | `--aspect` | ratio | the project's shape | The screen shape, such as `9:16` | | `--quality` | value | none | The quality setting the model offers | | `--on` | `blank` or picture | none | A picture to edit. `blank` starts from a white picture, and needs `--size` | | `--ref` | picture | none | A reference picture. Repeat it for more than one | | `--name` | text | none | The name people read on the asset card | | `--json` | switch | off | Print one JSON object | ### Examples #### Find an image model ```bash Terminal minicut models --kind image ``` #### Make a character picture ```bash Terminal minicut gen image lin-xia.png --prompt-file lin-xia.txt --model MODEL --target character:lin-xia --project rain-shop ``` Replace `MODEL` with a name from the list. This sends nothing until you say yes. ### Output Without `--yes`, the command says `Nothing was sent.` and prints the line to run after your yes. With `--json` it prints `"state": "needs_yes"` and that line as `next_step`. With the `--yes` line, it sends the job and prints its job id. ### See also [minicut jobs](#minicut-jobs), [minicut models](#minicut-models), [minicut save](/docs/cli/projects#minicut-save) ## minicut gen video Makes one video take for a shot, from the shot's own folder. ### Usage ```text Usage minicut gen video CLIP_FOLDER [--again] [--reason REASON] [--name NAME] [--json] ``` Replace the following: - `CLIP_FOLDER`: the shot's folder, such as `episodes/ep01/clips/c03`. - `REASON`: a few words on why you make this take. - `NAME`: the short name people read on the take. ### Details The command reads the shot's settings, prompt and pictures from its folder. This command uses credits. It shows what it will do and asks before it spends; `--yes` skips the question. It sends the job and returns, and [minicut jobs](#minicut-jobs) saves the take into the shot's folder. One shot has one job at a time. If the shot already has a job queued or running, the command stops and names that job. Stop it first, or add `--again` to make another take beside it. If you make a video take before the Mock loop is approved, the command prints a warning and records it. It does not refuse. See [Checks and loops](/docs/cli/checks-and-loops). ### Options | Flag | Type | Default | Description | |---|---|---|---| | `--again` | switch | off | Make another take while the shot already has a job | | `--reason` | text | none | Why you make this take | | `--name` | text | none | The name people read on the take | | `--json` | switch | off | Print one JSON object | ### Examples #### Make a take for shot 3 ```bash Terminal minicut gen video episodes/ep01/clips/c03 ``` ### Output The same as [minicut gen image](#minicut-gen-image): the `--yes` line first, then the job id after your yes. ### Errors | Message | What to do | |---|---| | `Shot already has job .` | Stop it with `minicut jobs --stop `, or add `--again` | | `no clip.json in ` | Give the path to a shot folder in an episode | ### See also [minicut jobs](#minicut-jobs), [minicut check take](/docs/cli/checks-and-loops#minicut-check-take) ## minicut gen voice Makes one spoken line for the mock, saved in the shot's folder. ### Usage ```text Usage minicut gen voice OUT_FILE --text-file TEXT_FILE --voice VOICE --target line:CLIP-N --project PROJECT [--episode EPISODE] [--model MODEL] [--json] ``` Replace the following: - `OUT_FILE`: the sound file to make, such as `l01.mp3`. - `TEXT_FILE`: a text file with the words to speak. - `VOICE`: a voice name. `minicut voices` lists the voices a voice model takes. - `CLIP-N`: the shot and the line number, such as `c03-1`. - `PROJECT`: a project id or the path to a project folder. - `EPISODE`: an episode id such as `ep01`. - `MODEL`: a voice model name from [minicut models](#minicut-models). ### Details This command uses credits. It shows what it will do and asks before it spends; `--yes` skips the question. The finished line is saved in the shot's folder, under `lines/`. ### Options | Flag | Type | Default | Description | |---|---|---|---| | `--text-file` | file | none | The words to speak. Needed | | `--voice` | name | none | The voice. Needed | | `--target` | `line:CLIP-N` | none | The shot and line. Needed | | `--project` | id or folder | none | The project. Needed | | `--episode` | episode id | none | The episode of the shot | | `--model` | name | the project's voice model | The voice model | | `--json` | switch | off | Print one JSON object | ### Examples #### Make line 1 in shot 3 ```bash Terminal minicut gen voice l01.mp3 --text-file line.txt --voice VOICE --target line:c03-1 --project rain-shop --episode ep01 ``` Replace `VOICE` with a voice name. ### See also [minicut gen batch](#minicut-gen-batch), [minicut jobs](#minicut-jobs) ## minicut gen MODEL Runs any other model by its name: music, sound split, lip sync, upscale, clip repair and 3D. ### Usage ```text Usage minicut gen MODEL OUT_FILE [--prompt PROMPT | --prompt-file PROMPT_FILE] [--set SETTING=VALUE ...] [--in INPUT=FILE ...] --target KIND:ID [--project PROJECT] [--episode EPISODE] [--name NAME] [--json] ``` Replace the following: - `MODEL`: a model name from [minicut models](#minicut-models). - `OUT_FILE`: the file to make. - `PROMPT`: the words for the model, in quotes. - `PROMPT_FILE`: a text file with the words for the model. - `SETTING=VALUE`: one setting the model lists, such as `seconds=8`. Repeat it for more. - `INPUT=FILE`: one input file the model takes. Repeat it for more. - `KIND:ID`: what the file is for. `KIND` is `character`, `location`, `prop`, `style` or `canvas`. ### Details `minicut models MODEL` lists the settings and inputs a model takes. This command uses credits. It shows what it will do and asks before it spends; `--yes` skips the question. ### Options | Flag | Type | Default | Description | |---|---|---|---| | `--prompt` | text | none | The words for the model | | `--prompt-file` | file | none | A file with the words for the model | | `--set` | `SETTING=VALUE` | the model's own | One setting. Repeat it for more | | `--in` | `INPUT=FILE` | none | One input file. Repeat it for more | | `--target` | `KIND:ID` | none | What the file is for. Needed | | `--project` | id or folder | none | The project | | `--episode` | episode id | none | The episode | | `--name` | text | none | The name people read on the asset card | | `--json` | switch | off | Print one JSON object | ### See also [minicut models](#minicut-models), [minicut jobs](#minicut-jobs) ## minicut gen batch Sends many `gen` commands and asks once for all of them. ### Usage ```text Usage minicut gen batch LIST_FILE [--no-wait] [--json] ``` Replace the following: - `LIST_FILE`: a text file with one `gen` command a line, written without `minicut gen` in front. ### Details Each line is `image ...`, `voice ...` or `video CLIP_FOLDER`, with its flags. Leave `--yes` out of every line. This command uses credits. It shows what it will do and asks before it spends; `--yes` skips the question. The `--yes` line sends the items one at a time. When your account has no free slot, it waits up to 9 minutes for one, and nothing is sent while it waits. Running the same `--yes` line again never sends an item twice. A shot can appear on one line only, unless that line has `--again`. ### Options | Flag | Type | Default | Description | |---|---|---|---| | `--no-wait` | switch | off | Stop at once when there is no free slot, instead of waiting | | `--json` | switch | off | Print JSON | ### Examples #### Make three pictures and two takes at once ```text shots.txt image lin-xia.png --prompt-file lin-xia.txt --model MODEL --target character:lin-xia --project rain-shop image shop.png --prompt-file shop.txt --model MODEL --target location:shop --project rain-shop image umbrella.png --prompt-file umbrella.txt --model MODEL --target prop:umbrella --project rain-shop video episodes/ep01/clips/c01 video episodes/ep01/clips/c02 ``` ```bash Terminal minicut gen batch shots.txt ``` ### Output Without `--yes`, one line per item, then `Nothing was sent.` and the `--yes` line. With the `--yes` line, one result per item, then how many of them were sent. ### See also [minicut jobs](#minicut-jobs) ## minicut jobs Lists your open jobs and saves the finished ones into your project. ### Usage ```text Usage minicut jobs [--wait SECONDS] [--json] minicut jobs --get JOB_ID [--json] minicut jobs --stop JOB_ID [--json] ``` Replace the following: - `SECONDS`: how long to keep checking, in seconds. - `JOB_ID`: the id of one job, as `minicut jobs` lists it. ### Details `minicut gen` and `minicut board run` send jobs and do not wait for them. `minicut jobs` reads every open job on your account. It saves each finished result into the project or board it was made for, and lists the rest by id. A job made for a project that is not on this computer is listed and left open. `--wait` keeps checking until every job it can save is saved, or the time runs out. `--get` saves one job here, even when it was already saved. `--stop` stops one job. ### Options | Flag | Type | Default | Description | |---|---|---|---| | `--wait` | seconds | none | Keep checking for up to this long | | `--get` | job id | none | Save this job here | | `--stop` | job id | none | Stop this job | | `--json` | switch | off | Print one JSON object | ### Examples #### Save finished jobs, waiting up to 5 minutes ```bash Terminal minicut jobs --wait 300 ``` ### Output One line per job: `job : saved `, or its state, such as `running`. A failed job prints `failed`, its error code, and a `Why:` line with the reason. Exit codes: 0 when nothing failed, 6 when `--wait` ran out with a job still running, 7 when minicut.ai did not answer. A failed job exits with its own code, listed on [Global options](/docs/cli/global-options). ### See also [minicut gen image](#minicut-gen-image), [minicut shots](/docs/cli/projects#minicut-shots) ## minicut models Lists the models you can use, or shows one model's settings. ### Usage ```text Usage minicut models [--kind KIND] [--search WORDS] [--json] minicut models MODEL [--json] ``` Replace the following: - `KIND`: one of `image`, `video`, `voice`, `audio`, `music`, `sfx`, `lipsync`, `upscale`, `videofx`, `audiofx` or `mesh3d`. - `WORDS`: words to search model names for. - `MODEL`: one model's name. ### Details The list comes from minicut.ai and is saved on this computer. Offline, the command prints the saved list with its age. `--kind audio` lists the voice models and every music and sound model. ### Options | Flag | Type | Default | Description | |---|---|---|---| | `--kind` | kind | all | List one kind of model | | `--search` | words | none | List the models whose names match | | `--json` | switch | off | Print JSON | ### Examples #### List the video models ```bash Terminal minicut models --kind video ``` ### Output One line per model: its name, kind and status. `minicut models MODEL` prints that model's settings and page. Exit codes: 0 when it listed the models, 7 when it printed the saved list because minicut.ai did not answer. ### See also [minicut gen MODEL](#minicut-gen-model) ## minicut write Writes words for a text box with a writing model. ### Usage ```text Usage minicut write TEXT [--model MODEL] [--json] ``` Replace the following: - `TEXT`: what to write, in quotes. - `MODEL`: a writing model name. ### Details This command uses credits. It shows what it will do and asks before it spends; `--yes` skips the question. With no `--model`, it uses the default writing model. A name the account does not have is refused, with the names it does have. ### Options | Flag | Type | Default | Description | |---|---|---|---| | `--model` | name | the default writing model | The writing model | | `--json` | switch | off | Print one JSON object with `text` and `model` | ### Examples #### Ask for a one-line title ```bash Terminal minicut write "A one-line title for a rainy night shop drama" ``` ### Output After your yes, the command prints the words. Exit code 3 means it is waiting for your yes. ### See also [minicut board](#minicut-board) ## minicut board Makes, edits, checks and runs a canvas board, which is a file you edit. ### Usage ```text Usage minicut board new [--project PROJECT --episode EPISODE] [--title TITLE] [--json] minicut board check FILE [--json] minicut board run FILE {--box BOX ... | --all} [--wait SECONDS] [--json] minicut board add FILE --kind KIND [--id BOX] [--x N --y N] [--label LABEL] [--prompt PROMPT] [--model MODEL] [--parent BOX] minicut board move FILE --box BOX --x N --y N minicut board set FILE --box BOX [--label LABEL] [--prompt PROMPT] [--text TEXT] [--model MODEL] [--seconds N] [--file PATH] [--fields JSON] minicut board {connect|disconnect} FILE --from BOX --to BOX minicut board delete FILE --box BOX [--box BOX ...] minicut board view FILE --view {workflow|storyboard} minicut board retype FILE --box BOX --kind {character|location|prop} ``` Replace the following: - `FILE`: the board file. - `PROJECT`, `EPISODE`: the project and episode the board belongs to. - `TITLE`: the board's title. - `BOX`: a box id on the board. - `KIND`: the kind of box, such as `image`, `video` or `character`. - `N`: a number: a position, or a length in seconds. - `PATH`: a file in the board's folder. - `JSON`: several fields at once, as JSON. ### Details The board file holds the boxes and the wires between them. Each edit command changes the file the same way the open **画布** tab in the MiniCut app does, and the open tab redraws by itself. - `new` makes an empty board. With `--project` and `--episode` it goes in the episode's `canvas` folder. Without them it goes in its own folder in your MiniCut home folder. - `check` reads the board for problems. It finds boxes with the same id, wires to missing boxes, wires that are not allowed, and missing upload files. - `run` makes the listed boxes. It uses credits. It shows what it will do and asks once for all the boxes; `--yes` skips the question. A box that is refused keeps its reason on the board, and the other boxes still go. `--wait` saves the results into the board's folder. ### Options | Flag | Type | Default | Description | |---|---|---|---| | `--project` | id or folder | none | `new`: the project of the board | | `--episode` | episode id | none | `new`: the episode of the board | | `--title` | text | none | `new`: the board's title | | `--box` | box id | none | The box to change or run. Repeat it for more in `run` and `delete` | | `--all` | switch | off | `run`: every box that can run | | `--wait` | seconds | none | `run`: wait this long and save the results | | `--kind` | kind | none | `add`, `retype`: the kind of box | | `--id` | box id | a new id | `add`: the new box's id | | `--x`, `--y` | number | none | `add`, `move`: the box's position | | `--label` | text | none | `add`, `set`: the box's label | | `--prompt` | text | none | `add`, `set`: the box's words for its model | | `--text` | text | none | `set`: the words in a text box | | `--model` | name | none | `add`, `set`: the box's model | | `--seconds` | number | none | `set`: the box's length | | `--file` | path | none | `set`: a file in the board's folder for the box to show | | `--fields` | JSON | none | `set`: several fields at once | | `--parent` | box id | none | `add`: the group box to put the new box in | | `--from`, `--to` | box id | none | `connect`, `disconnect`: the two ends of the wire | | `--view` | `workflow` or `storyboard` | none | `view`: how the board is laid out | | `--json` | switch | off | Print one JSON object | ### Examples #### Make a board for episode 1 ```bash Terminal minicut board new --project rain-shop --episode ep01 --title "Opening" ``` #### Make every box on a board ```bash Terminal minicut board run episodes/ep01/canvas/opening.board.json --all ``` ### Output `check` prints `Board ok:` with the number of boxes and wires, or one line per problem. Each edit prints `Board : ok` with the board's new revision number, and the new box id after `add`. | Exit code | Meaning | |---|---| | 0 | It worked | | 1 | The board has a problem, or the edit is refused | | 2 | A flag is missing | | 3 | `run` is waiting for your yes | ### See also [minicut jobs](#minicut-jobs), [minicut write](#minicut-write) --- # 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: .` | Use a step number from the table, or one of the named checks below | | `file not found: ` | 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) --- # Editor Every command that opens, changes, checks or renders the edited cut of an episode, with its usage, options and errors. These commands work on one episode's cut, the file `index.html` in the episode folder. An episode folder is `/episodes/ep01`. Your agent runs them in the Edit loop, after the Videos loop. 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`. See [Account](/docs/cli/account). Every command except `minicut edit` and `minicut catalog` runs in the episode folder. A path you name must be inside that folder. ## minicut edit Opens the MiniCut editor on one episode and prints a link to it. ### Usage ```bash Usage minicut edit PROJECT [--episode EPISODE] [--port PORT] ``` Replace the following: - `PROJECT`: the project id or the project folder. - `EPISODE`: the episode, `ep01` to `ep999`. - `PORT`: the port on your computer the editor listens on. ### Details The editor runs on your computer until you stop it. Each episode keeps its port, so the link stays the same on every restart while that port is free. If another program holds the port, the editor moves to a free one and says the link changed. If this episode's editor is already running, the command prints its address and starts nothing new. ### Options | Flag | Type | Default | Description | |---|---|---|---| | `--episode` | string | `ep01` | The episode to open. | | `--port` | number | the episode's own port | The port to start on. If it is in use, the editor takes a free port and says so. | Global options: see [Global options](/docs/cli/global-options). ### Examples ### Open the first episode of a project ```bash Command minicut edit night-market ``` You see the editor version, a link that works once within 2 minutes, and the command that stops the editor. ### Open episode 2 ```bash Command minicut edit night-market --episode ep02 ``` ### Output The link carries a one-time code. To open the editor again after 2 minutes, run `minicut edit` again. Stop the editor with Ctrl+C. | Exit code | Meaning | |---|---| | `0` | The editor ran and stopped, or it was already running. | | `2` | The project or episode has no cut, or the editor is not installed. | | `10` | This computer is not signed in. | ### See also [minicut render](#minicut-render), [Projects](/docs/cli/projects) ## minicut render Renders the episode in this folder to a video file, or runs the editor's lint, check or transcript import on it. ### Usage ```bash Usage minicut render [-o FILE] [--quality {draft|looks|delivery}] minicut render lint [--json] minicut render check [--json] minicut render transcribe TRANSCRIPT ``` Replace the following: - `FILE`: the video file to write, a `.mp4`, `.webm` or `.mov` path inside the episode folder, for example `renders/ep01.mp4`. - `TRANSCRIPT`: a `.json` transcript file inside the episode folder. ### Details `minicut render` makes the finished episode as one video file in the episode folder. `lint` is a fast check of the cut while you edit. `check` runs lint, then opens the cut and checks it again. `transcribe` puts a transcript into the episode. ### Options | Flag | Type | Default | Description | |---|---|---|---| | `-o`, `--out` | path | none | The video file to write. | | `--quality` | `draft`, `looks` or `delivery` | `looks` | `draft` while you try changes, `looks` for the first real render, `delivery` for the final file. | | `--json` | switch | off | `lint` and `check` only: print the result as JSON. | Global options: see [Global options](/docs/cli/global-options). ### Examples ### Render the final file ```bash Command minicut render -o renders/ep01.mp4 --quality delivery ``` You see the render's progress, then the file appears at `renders/ep01.mp4`. ### Check the cut before a render ```bash Command minicut render check ``` ### Output `lint` and `check` print one line for each problem. With `--json` they print the result as JSON. | Exit code | Meaning | |---|---| | `0` | The render or check finished. | | `2` | A flag is wrong, or this folder has no `index.html`. | | `10` | This computer is not signed in. | ### See also [minicut snapshot](#minicut-snapshot), [Checks and loops](/docs/cli/checks-and-loops) ## minicut timeline Prints the cut, or changes it in one step that `minicut timeline undo` reverses. ### Usage ```bash Usage minicut timeline [--json] minicut timeline {move|trim|split|delete|duplicate|ids|apply|undo} ... minicut timeline set '#CLIP_ID' --text "WORDS" [--json] minicut timeline fit [--plan] [--json] minicut timeline fit --undo ``` Replace the following: - `CLIP_ID`: the id of a caption, title or card clip, for example `cap-c05-l01`. - `WORDS`: the new words for that clip. ### Details With no subcommand, `minicut timeline` lists every track and clip: starts, ends and what plays. Each change is one step, and each step can be undone. Run `minicut timeline SUBCOMMAND --help` for the arguments a subcommand takes. | Subcommand | Does | |---|---| | `move`, `trim`, `split`, `delete`, `duplicate` | One edit to a clip. | | `set` | Changes the words of a caption, title or card. | | `ids` | Prints the clip ids. | | `apply` | Applies a list of edits from a file in one step. | | `undo` | Reverses one change, from its undo receipt. | | `fit` | Cuts every shot that is longer than its take down to the take. | `fit` moves everything after a shortened shot up, so the cut gets shorter and no take ends on a still frame. A shot whose `clip.json` says `"fit": "freeze"` keeps its still frame. ### Options | Flag | Type | Default | Description | |---|---|---|---| | `--text` | string | none | `set` only: the new words. | | `--json` | switch | off | Print the result as JSON. On `set`, this prints the undo receipt. | | `--plan` | switch | off | `fit` only: print the edits and change nothing. | | `--undo` | switch | off | `fit` only: reverse the last fit. | Global options: see [Global options](/docs/cli/global-options). ### Examples ### List the clips in the cut ```bash Command minicut timeline ``` You see every track and clip in the cut, with its start and end. ### Change the words of one caption ```bash Command minicut timeline set '#cap-c05-l01' --text "I never left." --json ``` ### Preview a fit without changing the cut ```bash Command minicut timeline fit --plan ``` ### Output | Exit code | Meaning | |---|---| | `0` | The cut was printed or changed. | | `2` | A subcommand or flag is wrong, or this folder has no `index.html`. | | `10` | This computer is not signed in. | ### See also [minicut captions](#minicut-captions), [minicut render](#minicut-render) ## minicut captions Redoes every caption in the episode to one standard. ### Usage ```bash Usage minicut captions [EPISODE_FOLDER] [--top LINE_IDS] [--bottom LINE_IDS] [--json] ``` Replace the following: - `EPISODE_FOLDER`: the episode folder. Without it, the current folder. - `LINE_IDS`: one or more spoken line ids, comma separated, for example `c05-l01`. ### Details Each caption goes bottom centre inside the title safe area, at most 2 lines, split at the natural break and timed to its line's audio. The words stay as they are. Run it again after you change the words with `minicut timeline set`. The Mock and Edit loops check captions with `minicut check captions`. ### Options | Flag | Type | Default | Description | |---|---|---|---| | `--top` | line ids | none | Put these lines at the top of the frame, for a shot whose bottom carries text. | | `--bottom` | line ids | none | Bring these lines back to the bottom. | | `--json` | switch | off | Print the result as JSON. | Global options: see [Global options](/docs/cli/global-options). ### Examples ### Redo every caption in episode 1 ```bash Command minicut captions episodes/ep01 ``` ### Move one line to the top of the frame ```bash Command minicut captions episodes/ep01 --top c05-l01 ``` You see the captions it changed, then whether every caption now meets the standard. ### Output | Exit code | Meaning | |---|---| | `0` | Every caption meets the standard. | | `1` | Captions were redone, and some still fail the standard. Each one is named. | | `2` | The folder has no `index.html`, or Python 3 is missing. | | `10` | This computer is not signed in. | ### See also [Checks and loops](/docs/cli/checks-and-loops), [minicut timeline](#minicut-timeline) ## minicut snapshot Saves still pictures of the episode in this folder, with no render. ### Usage ```bash Usage minicut snapshot [--frames COUNT | --at SECONDS] [-o FOLDER] ``` Replace the following: - `COUNT`: how many stills to take across the episode. - `SECONDS`: the times to take stills at, comma separated, for example `1.5,3`. - `FOLDER`: the folder for the stills, inside the episode folder. ### Details A snapshot is the fast way to look at the cut. It needs the browser that `minicut setup` installs. ### Options | Flag | Type | Default | Description | |---|---|---|---| | `--frames` | number | none | Take this many stills, spread across the episode. | | `--at` | seconds | none | Take a still at each of these times. | | `-o`, `--output` | path | none | The folder to save the stills in. | Global options: see [Global options](/docs/cli/global-options). ### Examples ### Take stills at three times ```bash Command minicut snapshot --at 1,3,5 -o snapshots ``` You see the path of each still it saved. ### See also [minicut keyframes](#minicut-keyframes), [minicut compare](#minicut-compare) ## minicut keyframes Saves pictures of how each animation in the episode moves. ### Usage ```bash Usage minicut keyframes [TARGET] [--selector SELECTOR] ``` Replace the following: - `TARGET`: a file inside the episode folder to look at. Without it, the episode. - `SELECTOR`: a CSS selector. Only the elements that match it are shown. ### Details Use it to check that a title, name tag or effect moves the way you want. It needs the browser that `minicut setup` installs. ### Options | Flag | Type | Default | Description | |---|---|---|---| | `--selector` | string | none | Show only the elements that match this CSS selector. | Global options: see [Global options](/docs/cli/global-options). ### Examples ### Check every animation in the episode ```bash Command minicut keyframes ``` ### See also [minicut snapshot](#minicut-snapshot) ## minicut compare Puts versions side by side in one picture. ### Usage ```bash Usage minicut compare FOLDER [--out FILE] ``` Replace the following: - `FOLDER`: a folder inside the episode folder that holds the versions to compare. - `FILE`: the picture to write, inside the episode folder. ### Details Use it to choose between versions of a shot or a still. It needs the browser that `minicut setup` installs. ### Options | Flag | Type | Default | Description | |---|---|---|---| | `--out` | path | none | The picture to write. | Global options: see [Global options](/docs/cli/global-options). ### Examples ### Compare the stills in one folder ```bash Command minicut compare snapshots --out compare.png ``` ### See also [minicut grade-compare](#minicut-grade-compare), [minicut snapshot](#minicut-snapshot) ## minicut grade-compare Puts colour looks for one clip side by side in one picture. ### Usage ```bash Usage minicut grade-compare --for CLIP [--grades LOOKS] ``` Replace the following: - `CLIP`: the clip to show the looks on. - `LOOKS`: the colour looks to compare, comma separated. ### Details Use it to pick the colour look of the episode before the final render. It needs the browser that `minicut setup` installs. ### Options | Flag | Type | Default | Description | |---|---|---|---| | `--for` | path | none | The clip to show the looks on. | | `--grades` | list | none | The colour looks to compare. | Global options: see [Global options](/docs/cli/global-options). ### See also [minicut compare](#minicut-compare) ## minicut catalog Lists the ready-made titles, name tags, transitions and effects that come with the editor. ### Usage ```bash Usage minicut catalog [WORDS] [--type {block|component}] [--json] ``` Replace the following: - `WORDS`: what you want, in English, for example `reveal a headline one line at a time`. ### Details The search runs on your computer. Search before you build a title or effect by hand, then add the one you pick with `minicut add`. `minicut catalog` works in any folder. ### Options | Flag | Type | Default | Description | |---|---|---|---| | `--type` | `block` or `component` | both | Only list one kind of piece. | | `--json` | switch | off | Print the results as JSON. | Global options: see [Global options](/docs/cli/global-options). ### Examples ### Search for a title ```bash Command minicut catalog "reveal a headline one line at a time" --json ``` You see the matching pieces, best match first, each with its name. ### See also [minicut add](#minicut-add) ## minicut add Puts a ready-made piece into the episode in this folder. ### Usage ```bash Usage minicut add NAME [--force] ``` Replace the following: - `NAME`: the piece's name, as `minicut catalog` lists it. ### Details The piece's files go into the episode folder. You then place it in the cut. ### Options | Flag | Type | Default | Description | |---|---|---|---| | `--force` | switch | off | See `minicut add --help`. | Global options: see [Global options](/docs/cli/global-options). ### Examples ### Add a film grain effect ```bash Command minicut add grain-overlay ``` ### See also [minicut catalog](#minicut-catalog) ## Errors | Message | What to do | |---|---| | `You are not signed in. Ask your agent to run minicut login.` | Run `minicut login`, then run the command again. | | `This folder has no index.html.` | Run the command in the episode folder, for example `episodes/ep01`. | | `no episode timeline at ...` | The episode has no cut yet. Run `minicut new PROJECT --timeline ep01`. | | `The MiniCut editor is not installed: ...` | Follow the step in the message: run `minicut setup`, or run the install line again. | | `The browser for pictures is not installed. Run: minicut setup` | Run `minicut setup`. | | `... is not inside this episode folder.` | Name a path inside the episode folder. | | `-o takes a .mp4, .webm or .mov path inside this episode folder.` | Give `-o` a video file name inside the episode folder. | | `--quality is draft, looks or delivery.` | Use one of those three values. | | `--top takes caption line ids, comma separated, like c05-l01` | Give line ids such as `c05-l01,c06-l02`. | | `no Python 3 found. Run: minicut setup` | Run `minicut setup`. | ## Next [Scene and music](/docs/cli/scene-and-music) [Checks and loops](/docs/cli/checks-and-loops) [Global options](/docs/cli/global-options) --- # Scene and music Every command that builds, checks and draws a 3D scene, and every command that checks, plays and measures an episode's music. A 3D scene and a song are both files your agent writes. The CLI checks them, then draws the scene or plays the song on your computer. These commands send nothing to a model. 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`. See [Account](/docs/cli/account). ## minicut scene api Prints the import line for a scene script that you run yourself with Node.js. ### Usage ```bash Usage minicut scene api ``` ### Details Put the printed line at the top of your script. The script then has the scene composer's own operations and a save that checks the scene before it writes. MiniCut never runs your script. You run it, so your agent app's permission check sees every run. Global options: see [Global options](/docs/cli/global-options). ### Examples ### Get the import line ```bash Command minicut scene api ``` You see one import line to copy into your script. ### See also [minicut scene build](#minicut-scene-build), [minicut scene check](#minicut-scene-check) ## minicut scene build Applies a list of scene operations to a fresh scene, checks it, and writes the scene file. ### Usage ```bash Usage minicut scene build NAME.scene.ops.json [--out FILE] ``` Replace the following: - `NAME.scene.ops.json`: a data file that lists the scene operations and their arguments. - `FILE`: the scene file to write. ### Details An operations file is data only. A file that holds code is refused. Without `--out`, the command writes `NAME.scene.json` beside the operations file and raises its revision number by one. If the scene has problems, nothing is written. ### Options | Flag | Type | Default | Description | |---|---|---|---| | `--out` | path | `NAME.scene.json` | The scene file to write. | Global options: see [Global options](/docs/cli/global-options). ### Examples ### Build a scene from an operations file ```bash Command minicut scene build episodes/ep01/scenes/c03.scene.ops.json ``` You see `Wrote` with the scene file, its revision and a short summary of the scene. ### Output | Exit code | Meaning | |---|---| | `0` | The scene file was written. | | `1` | The scene has problems. Nothing was written. | | `2` | The file is missing or the command is wrong. | ### See also [minicut scene check](#minicut-scene-check) ## minicut scene check Checks a scene file against the composer's own rules and limits. ### Usage ```bash Usage minicut scene check FILE [--loose] ``` Replace the following: - `FILE`: the scene file to check. ### Details The check reads the scene's structure and limits first. Then it checks every body against every prop and the floor, at every frame. It prints one line for each problem. ### Options | Flag | Type | Default | Description | |---|---|---|---| | `--loose` | switch | off | Run the check without the strict rules. | Global options: see [Global options](/docs/cli/global-options). ### Examples ### Check a shot's scene ```bash Command minicut scene check episodes/ep01/scenes/c03.scene.json ``` You see `OK` with a summary of the scene, or the number of problems and one line for each. ### Output | Exit code | Meaning | |---|---| | `0` | No problems. No body goes through a prop or the floor. | | `1` | One or more problems. Each one is printed. | | `2` | The file is missing or the command is wrong. | ### See also [minicut scene render](#minicut-scene-render), [Checks and loops](/docs/cli/checks-and-loops) ## minicut scene render Draws a scene as a still or a clip on your computer. ### Usage ```bash Usage minicut scene render FILE [--camera CAMERA] {--still SECOND|--still middle|--clip} [--project PROJECT --episode EPISODE --clip CLIP] [--id LIBRARY_ID] [--draft | --size WIDTH] [--force] minicut scene render FILE FILE ... {--still SECOND|--clip} [--draft] [--force] minicut scene render --project PROJECT --episode EPISODE {--still SECOND|--clip} [--draft] [--force] ``` Replace the following: - `FILE`: the scene file to draw. - `CAMERA`: the id of a camera in the scene. - `SECOND`: the second of the scene to draw as a still. - `PROJECT`, `EPISODE`, `CLIP`: where to save a clip, for example `night-market`, `ep01`, `c03`. - `LIBRARY_ID`: the library entry to save a still into. - `WIDTH`: the frame width in pixels. ### Details A clip is saved as the next take of the named shot. A still goes into your library with `--project` or `--id`. Without them, it goes into the `cache/stills` folder of your MiniCut home folder, and the path is printed. Every render keeps two copies: the clean picture, and a copy in `labeled/` with a name tag on every asset, for people to read. The render is refused while a body goes through a prop or the floor in the frames it would draw. A clip whose scene, camera and size are unchanged since its newest take is not drawn again. With several files, or with `--project` and `--episode` alone, the command draws many scenes in one run. With `--project` and `--episode` alone, it draws every shot scene of the episode, in shot order. ### Options | Flag | Type | Default | Description | |---|---|---|---| | `--camera` | string | the scene's own camera | The camera to draw from. | | `--still` | second or `middle` | none | Draw one still at this second, or at the middle second. | | `--clip` | switch, or a clip id | none | Draw a clip. | | `--project` | string | none | The project to save into. | | `--episode` | string | none | The episode to save into. | | `--id` | string | none | The library entry to save a still into. | | `--draft` | switch | off | Draw half of each side (640 x 360 for 16:9), for mock looks. | | `--size` | number | the full size | Any even width from 128 up to the full width. | | `--force` | switch | off | Draw a clip again even if nothing changed. | Global options: see [Global options](/docs/cli/global-options). ### Examples ### Draw a still from the middle of a scene ```bash Command minicut scene render episodes/ep01/scenes/c03.scene.json --still middle --draft ``` ### Draw every shot scene of an episode as clips ```bash Command minicut scene render --project night-market --episode ep01 --clip ``` You see each scene as it is drawn, then one line with how many were drawn, unchanged and not drawn. ### Output | Exit code | Meaning | |---|---| | `0` | Every scene was drawn or was already up to date. | | `1` | A scene has a body going through a prop or the floor. | | `2` | The command is wrong or a file is missing. | | `5` | An option value is wrong. The message names it. | ### See also [minicut scene check](#minicut-scene-check), [Generate](/docs/cli/generate) ## minicut scene undo Puts back the version of a scene before its last write. ### Usage ```bash Usage minicut scene undo FILE ``` Replace the following: - `FILE`: the scene file. ### Details It undoes the last write from the MiniCut app or from an agent. The last 20 versions are kept. Global options: see [Global options](/docs/cli/global-options). ### See also [minicut scene build](#minicut-scene-build) ## minicut scene panorama Sets or clears the panorama picture of a scene. ### Usage ```bash Usage minicut scene panorama FILE {--image PICTURE|--box BOX_ID|--clear} ``` Replace the following: - `FILE`: the scene file. - `PICTURE`: a picture on your computer. It is also put on the episode's board. - `BOX_ID`: the id of a picture box on the episode's board. ### Options | Flag | Type | Default | Description | |---|---|---|---| | `--image` | path | none | Use this picture from your computer. | | `--box` | string | none | Use this picture box from the board. | | `--clear` | switch | off | Remove the panorama picture. | Global options: see [Global options](/docs/cli/global-options). ### See also [minicut scene to-board](#minicut-scene-to-board) ## minicut scene to-board Copies a picture or clip next to the scene and adds it as a box on the episode's board. ### Usage ```bash Usage minicut scene to-board FILE MEDIA [--label WORDS] ``` Replace the following: - `FILE`: a scene file inside an episode, `/episodes/epNN/scenes/NAME.scene.json`. - `MEDIA`: the picture or clip to send to the board. - `WORDS`: the label for the new box. ### Details The episode needs a board first. Make one with `minicut board new --project PROJECT --episode EPISODE`. ### Options | Flag | Type | Default | Description | |---|---|---|---| | `--label` | string | none | The label for the new box. | Global options: see [Global options](/docs/cli/global-options). ### See also [minicut scene panorama](#minicut-scene-panorama), [Generate](/docs/cli/generate) ## minicut music Gives your own music script what it needs, then checks, plays and measures the song file it writes. ### Usage ```bash Usage minicut music api [--json] minicut music instruments [--json] minicut music cuts EPISODE_FOLDER [--json] minicut music check SONG minicut music render SONG [--from SECONDS --to SECONDS] [--stems] [--no-mp3] minicut music measure WAV [--episode EPISODE_FOLDER] minicut music from-midi MIDI --map MAP [--out SONG] ``` Replace the following: - `EPISODE_FOLDER`: the episode folder, for example `episodes/ep01`. - `SONG`: a song file, `NAME.song.json`. - `SECONDS`: a time in the song, in seconds. - `WAV`: a `.wav` file that `minicut music render` made. - `MIDI`: a `.mid` file from any music tool. - `MAP`: a `.json` file that maps the MIDI tracks to instruments. ### Details Your agent writes its own music script in Python 3.9 or newer and runs it itself. The script writes a song file. A song file is data only: instruments by catalog id, synths by preset id, no paths and no code. MiniCut never runs your script, and the music commands open no network connection. Your agent runs these commands in the Mock loop. | Subcommand | Does | |---|---| | `api` | Prints the import lines for your music script. The module uses the Python standard library only. | | `instruments` | Lists instrument ids, note ranges, drum kit pieces and settings. | | `cuts` | Lists the episode's shots, cuts, scene changes and spoken lines, in seconds. | | `check` | Checks that a song file can be played: ids, ranges and limits. | | `render` | Plays the song into audio files beside it. | | `measure` | Reports loudness, peaks, hits on cuts and the music level under spoken lines. | | `from-midi` | Turns a MIDI file into a song file. | `render` writes `NAME.wav`, `NAME.mp3`, `NAME.beats.json`, `NAME-waveform.png` and `NAME.report.json` beside the song. It needs the instrument samples that `minicut setup` installs once, about 396 MB. ### Options | Flag | Type | Default | Description | |---|---|---|---| | `--json` | switch | off | `api`, `instruments` and `cuts`: print the result as JSON. | | `--from` | seconds | the start | `render`: start playing at this time. | | `--to` | seconds | the end | `render`: stop playing at this time. | | `--stems` | switch | off | `render`: also write each instrument as its own file. | | `--no-mp3` | switch | off | `render`: skip the `.mp3` file. | | `--episode` | path | none | `measure`: compare the music with this episode's cuts and spoken lines. | | `--map` | path | none | `from-midi`: the file that maps MIDI tracks to instruments. Required. | | `--out` | path | `NAME.song.json` beside the MIDI file | `from-midi`: the song file to write. | Global options: see [Global options](/docs/cli/global-options). ### Examples ### Read the timing of an episode ```bash Command minicut music cuts episodes/ep01 --json ``` ### Check and play a song ```bash Command minicut music check episodes/ep01/music/score.song.json minicut music render episodes/ep01/music/score.song.json ``` You see the problems in the song file, if any, then the files that `render` wrote. ### Measure the result against the episode ```bash Command minicut music measure episodes/ep01/music/score.wav --episode episodes/ep01 ``` ### Output | Exit code | Meaning | |---|---| | `0` | The command finished. | | `2` | The command could not run: a file is missing, or a tool needs `minicut setup`. | | `5` | The song file or MIDI map has problems. Each one is printed. | ### Limits | Limit | Value | |---|---| | Song file size | 32 MB | | Time for one `render` | 30 minutes | | Time for one `measure` | 10 minutes | ### See also [Setup](/docs/cli/setup), [Checks and loops](/docs/cli/checks-and-loops) ## Errors | Message | What to do | |---|---| | `You are not signed in. Ask your agent to run minicut login.` | Run `minicut login`, then run the command again. | | `no such file: ...` | Check the path to the scene file. | | `Not written: N problem(s). ... is unchanged.` | Fix the problems printed above it, then build again. | | `Use --draft or --size , not both.` | Pick one of the two. | | `--size is the frame width in pixels: an even number from 128 to ...` | Give an even width in that range. | | `Each clip is saved as the next take of its shot: add --project --episode epNN.` | Add `--project` and `--episode` to draw clips from many scenes. | | `this episode has no board yet: make one with minicut board new ...` | Run the `minicut board new` command in the message. | | `no Python found. Run: minicut setup` | Run `minicut setup`. | | `the music tools are not set up (...). Run: minicut setup` | Run `minicut setup`. | | `no instrument samples in .... Run: minicut setup (about 396 MB, once). Nothing was rendered.` | Run `minicut setup`. | | `the song file is over 32 MB` | Make the song file smaller. | | `Stopped: it ran past the time limit.` | Render a shorter part with `--from` and `--to`. | ## Next [Editor](/docs/cli/editor) [Checks and loops](/docs/cli/checks-and-loops) [Global options](/docs/cli/global-options) --- # Global options The flags, output format, exit codes and environment variables that work the same way on every minicut command. Every `minicut` command follows the rules on this page. A script or a coding agent can read the exit code and the JSON output of any command in the same way. ## Options | Flag | Type | Description | |---|---|---| | `--json` | switch | Print one JSON object on stdout instead of text. Works on every command that lists it in its usage line | | `--help`, `-h` | switch | Print every command with a one-line description, then exit with code 0. `minicut help` does the same | A command name MiniCut does not know prints the command list and exits with code 2. On a computer that is not signed in, the sign-in check comes first, so it exits with code 10. ## Output Results go to stdout. Notes for a person go to stderr, so stdout stays one clean result. Two notes can appear on stderr: - The offline note, when the computer has not reached minicut.ai for a while. See [Account](/docs/cli/account). - One line after an automatic update, on the next command. With `--json`, an error has the same shape on every command: ```bash Terminal minicut me --json ``` ```json Output {"error":{"code":"signed_out","message":"You are not signed in. Ask your agent to run minicut login.","url":null,"request_id":null}} ``` | Field | Description | |---|---| | `code` | A fixed error code. Read this to decide what to do | | `message` | The same sentence the text output prints | | `url` | A page on minicut.ai that fixes it, or `null` | | `request_id` | The id of the request, to quote when you contact us, or `null` | Without `--json`, the command prints the message, then the URL and `Request id:` when they exist. If a command stops on an error it did not expect, it prints `minicut:` and the error, and exits with code 1. ## Exit codes | Code | Meaning | What to do | |---|---|---| | 0 | Done | Nothing | | 1 | A check found a problem, or the command stopped on an error it printed | Read the printed lines. Each check failure names its fix | | 2 | The command could not run: a wrong flag, a missing file or a wrong id | Fix the command and run it again | | 3 | The command needs your yes before it runs. It printed the line to run after you agree. Nothing was sent | Run the printed line if you agree. `minicut setup` also uses 3 when there is less than 5 GB free | | 4 | `minicut setup` finished, but Python 3.12 or ffmpeg is missing | Install it from the site setup printed, then run setup again | | 5 | An input is outside what the command or model takes | Change the input the message names | | 6 | Not ready yet: a job is still running | Run the same command again later | | 7 | MiniCut could not reach minicut.ai | Connect to the internet, then run the same command again | | 8 | Something went wrong on our side, or there are too many requests right now | Run the same command again. If it fails again, wait a few minutes | | 9 | Your account does not cover this. The message links to minicut.ai | Open the link in the message | | 10 | This computer is not signed in, or the sign-in was cancelled or expired | Run `minicut login` | | 12 | This version of MiniCut is too old | Run `minicut update`, then the same command again | | 75 | Another `minicut update` is running | Wait for it to finish, then run `minicut update` again | ## Environment variables | Variable | Default | Description | |---|---|---| | `MINICUT_HOME` | `~/.minicut`, or `%LOCALAPPDATA%\minicut` on Windows | The MiniCut home folder: settings, key file, tools, projects and library | | `MINICUT_PORT` | `7311` | The port the MiniCut app uses on your computer. Set it when another program uses that port | | `MINICUT_NO_AUTOUPDATE` | not set | Set to `1` to turn off the automatic update. `"auto_update": false` in `settings.json` does the same | | `MINICUT_NO_ERROR_REPORTS` | not set | Set to `1` to turn off crash reports. `"error_reports": false` in `settings.json` does the same | | `CI` | not set | When set, MiniCut makes no automatic update and sends no crash reports | | `HTTPS_PROXY` | not set | Read when you install MiniCut. The install saves it as the proxy for every command. Change it later with [minicut network](/docs/cli/setup#minicut-network) | When a command crashes, MiniCut sends one crash report to minicut.ai. It carries no key, no file path and no error message. ## See also [Account](/docs/cli/account) [Setup](/docs/cli/setup) [Quickstart](/docs/cli/quickstart) --- # Project files Every file in a project that you can open, what it holds, and which command writes it. The folders are on [Project directory](/docs/cli/project-directory). In the Files table, **Written by** names who makes or changes the file. ## Files | File | Holds | Written by | |---|---|---| | `series.json` | The project's title, settings and lists. See below | `minicut new`, `minicut save`, your agent and the app | | `source/sources.json` | The sources the story comes from, empty at first | `minicut new` | | `research.md` | The researched idea | Your agent, in the Script loop | | `script.md` | The story and world document | Your agent, in the Script loop | | `episodes/epNN/script.md` | The episode script | Your agent, in the Script loop | | `episodes/epNN/shots.md` | The [shot sheet](/docs/cli/shot-sheet) | Your agent, in the Shot sheet loop | | `episodes/epNN/assets.md` | The asset list and the picture prompts | Your agent, in the Shot sheet loop | | `episodes/epNN/prompts.md` | The video prompts, one section for each shot | Your agent, in the Shot sheet loop | | `episodes/epNN/shots.checks.json`, `episodes/epNN/prompts.checks.json` | The result of the last check of the file beside it | `minicut check` | | `episodes/epNN/loops.json` | The rounds, approvals and stops of each loop | `minicut loop` | | `episodes/epNN/now.json` | The shot your agent is writing, for 120 seconds | `minicut now` | | `episodes/epNN/mock.sheet.jpg` | One frame of every shot, made for the Mock loop | `minicut loop run mock` | | `episodes/epNN/index.html` | The episode timeline | `minicut new`, `minicut timeline` and the editor | | `episodes/epNN/minicut.json` | The editor settings for the episode | `minicut new` | | `episodes/epNN/clips/cNN/prompt.md` | The video prompt of the shot | Your agent | | `episodes/epNN/clips/cNN/clip.json` | The shot's model, settings and picked take. See below | Your agent, `minicut save take` and `minicut asset pick` | | `episodes/epNN/clips/cNN/tNN.mp4` | A take of the shot. It can be `.mp4`, `.mov`, `.webm`, `.wav`, `.mp3` or `.m4a`. A take is never renamed or overwritten | `minicut save take` and a finished video job | | `episodes/epNN/clips/cNN/tNN.json` | The record of the take. See below | `minicut save take` and a finished video job | | `episodes/epNN/clips/cNN/tNN.checks.json` | The result of the checks of the take | `minicut check take` and the Videos loop | | `episodes/epNN/clips/cNN/jobs/` | One file for each job of the shot that is open, failed or stopped | `minicut gen` | ## series.json | Field | Holds | |---|---| | `id` | The project id, the same as the folder name | | `uid` | A unique id that ties the project's jobs to this folder | | `title` | The title people read | | `language` | The language of the project, such as `zh` or `en` | | `format` | One-off, series episode or series | | `entry` | What you brought in: `idea`, `ip`, `story`, `script` or `shots` | | `aspect_ratio` | The screen shape of the video | | `resolution` | The video size | | `fps` | The frame rate, 30 at first | | `episodes_planned` | How many episodes you plan | | `episodes` | The ids of the project's episodes | | `library` | The ids of the characters, locations, props and styles the project uses | | `models` | The model you picked for each kind, such as `"models": {"video": "NAME"}` | | `loops` | The limit of each loop, such as `"loops": {"mock": 4, "takes": 5}`. See [Steps and loops](/docs/cli/steps-and-loops) | ## clip.json | Field | Holds | |---|---| | `id` | The shot id, such as `c01` | | `model` | The model for this shot. Always written, as the series default | | `params` | The settings sent with the shot, such as the screen shape and the seconds | | `bindings` | The reference pictures of the shot | | `prompt` | The name of the prompt file, `prompt.md` | | `pick` | The take the shot uses | | `shots` | The part of the take to keep, as `from` and `to` seconds | | `fit` | `"take"` cuts the shot down to its take. `"freeze"` keeps the still frame | ## tNN.json | Field | Holds | |---|---| | `id` | The take id, such as `t01` | | `state` | The state of the take, such as `done` | | `file` | The file name of the take | | `kind` | `model`, `code` or `placeholder` | | `model` | The model that made the take | | `settings_sent` | The settings the model received | | `prompt_text` | The prompt the model received | | `sha256` | The checksum of the file | | `link` | `hardlink` or `copy`: how the shot's folder got the file | | `library` | The path of the same file in your library | | `created` | When the record was made | ## See also [Project directory](/docs/cli/project-directory) [Shot sheet](/docs/cli/shot-sheet) [minicut save](/docs/cli/projects#minicut-save) --- # Troubleshooting The messages the minicut command prints, what each one means, and what to do. Exit codes are on Global options. Find the message you see in the first column. Text in capitals, such as `PATH`, stands for a value that changes. Every exit code is explained on [Global options](/docs/cli/global-options). | What you see | Exit code | Cause | What to do | |---|---|---|---| | `You are not signed in. Ask your agent to run minicut login.` | 10 | This computer has no sign-in | Run `minicut login`. With no browser on the computer, see [Sign in without a browser](/docs/cli/sign-in-without-a-browser) | | `This computer was signed out on minicut.ai.` | 10 | The sign-in was removed on minicut.ai | Run `minicut login` | | `Sign-in was cancelled on minicut.ai.` | 10 | The sign-in was cancelled on minicut.ai | Run `minicut login` again and confirm on minicut.ai | | `This sign-in code expired. Run minicut login again.` | 10 | The code lasts 15 minutes, or no code is waiting on this computer | Run `minicut login --device` for a new code, then `minicut login --complete` on the same computer | | `Waiting for you to confirm on minicut.ai.` | 0 | You have not confirmed the code yet | Confirm the code, then run `minicut login --complete` again | | `Could not reach minicut.ai.` or `minicut.ai did not answer in time.` | 7 | No internet connection, a proxy that blocks it, or a slow connection | Connect to the internet, then run the same command again. For a proxy, see [Use MiniCut in China mainland](/docs/cli/use-minicut-in-china-mainland) | | `Could not reach minicut.ai, and this computer's sign-in was last confirmed N days ago. Connect to the internet, then run the same command again.` | 7 | The computer has been offline for more than 7 days | Connect to the internet, then run the same command again | | `Offline: minicut.ai was last reached N days ago. Minicut keeps working offline for M more days.` | Not changed | The computer is offline. The note goes to stderr | Connect to the internet within M days | | `This Minicut is too old. Run minicut update, then the same command again.` | 12 | The installed version is too old for this command | Run `minicut update`, then the same command. See [Update and uninstall](/docs/cli/update-and-uninstall) | | `Another Minicut update is running on this computer. Run minicut update again when it has finished.` | 75 | An update is already running | Wait for it to finish, then run `minicut update` again | | `Too many requests. Try again in N seconds.` | 8 | Too many requests in a short time | Wait N seconds, then run the same command again | | `Something went wrong on our side. Try again.` | 8 | A fault on our side | Run the same command again. If it fails again, wait a few minutes. Quote the `Request id:` line if you contact us | | `This account reached today's limit. It resets at TIME.` | 8 | The account reached its limit for today | Run the command again after TIME | | `This model is not available right now. Try again later.` | 8 | The model is not taking requests | Run the same command later, or pick another model with `minicut models` | | `Nothing was sent.` with a line to run after you agree | 3 | The command uses credits. It shows what it will do and asks before it spends | Run the printed line if you agree | | `Pick a model. Run minicut models to see them, then pass --model.` | 5 | The command needs a model name | Run `minicut models`, then add `--model NAME` | | `No model named NAME. Nothing was sent. The list: minicut models.` | 5 | The model name is not in the list | Use a name from `minicut models` | | `FIELD on this model is RANGE. You asked for VALUE.` | 5 | The value is outside what the model takes | Change the value to one inside RANGE | | `Minicut is not fully installed: PATH is missing. Run the install line again.` | 2 | A file of the install is missing | Run the install line again. See [Install in a terminal](/docs/cli/install-in-a-terminal) | | `the folder FOLDER already holds files that are not Minicut's (FILES), so Minicut will not install into it. Set MINICUT_HOME to a new folder, or empty this one.` | 1 | The install folder has files MiniCut did not make | Set `MINICUT_HOME` to a new folder, or empty this one | | `Port 7311 is used by another program. Set MINICUT_PORT to a free port, then run minicut again.` | 2 | Another program uses the port of the MiniCut app | Set `MINICUT_PORT` to a free port, then run `minicut` again | | `The Minicut app did not start.` | 2 | The MiniCut app did not answer after it was started | Run `minicut doctor`, then run `minicut` again | | `REFUSED: under 5 GB free. Free some space and run again.` | 3 | Setup needs 5 GB of free disk | Free disk space, then run `minicut setup` again | | `MISSING: Python 3.12. Download it from SITE and install it ..., then run minicut setup again.` or the same line for `ffmpeg` | 4 | Setup does not bring Python 3.12 or ffmpeg | Install it from SITE, then run `minicut setup` again | | `FAILED TOOL: REASON` | 1 | A download for one tool failed | Run `minicut setup` again. In China mainland, add `--china` | | A line starting `这一行需要你自己运行：` followed by a command | 2 | This program cannot write to that folder, for example an agent's sandbox | Run that command in your own terminal | | `No project NAME in PATH.` | 2 | The folder has no project with that id | Use the id from `minicut new` | | `Not a project id: NAME. Use the id from minicut new (letters, digits and -).` | 2 | The project id has other characters | Use letters, digits and `-` | | `unknown app "NAME". Apps:` followed by a list | 2 | `--app` got a name that is not in the list | Use an id from the list | | `PATH already exists. Add --force to copy the pack over it.` | 2 | The skill folder is already there | Add `--force` | | `a proxy is http://host:port, got VALUE` or `Invalid URL` | 5 | The proxy address is wrong, or missing after `--proxy` | Use the form `http://HOST:PORT` | | `代理 HOST 连不上，已直接连接；运行 minicut network --direct 可以不再用它` | Not changed | The saved proxy refused the connection, so the command connected directly | Fix the proxy, or run `minicut network --direct` to stop using it | | `FOLDER has no Minicut install marker (minicut-home.json), so it may hold files that are not Minicut's. Nothing was removed.` | 1 | The uninstall found no MiniCut install in that folder | Check that `MINICUT_HOME` points at your MiniCut home folder | | `minicut: ERROR` | 1 | The command stopped on an error it did not expect | Run the command again. If it fails again, contact us with the line | --- # Changelog Every version of the MiniCut CLI, newest first, with what changed for you. Run `minicut status` to see your version on the line that starts `Minicut CLI`. To get the newest version, see [Update and uninstall](/docs/cli/update-and-uninstall). Versions and their changes are listed here from the next release.