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.

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

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

minicut open

Opens the MiniCut app at one episode of a project, on the tab you name, and prints that address.

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

Examples

Open the editor on the first episode

minicut open snow-bus

On a computer with no project of that id:

No project snow-bus in ~/.minicut/projects.

Open with a project id that is not valid

minicut open "Snow Bus"

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

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

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

Examples

See what setup would download

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

minicut setup --china

Output

minicut update

Installs the newest MiniCut version beside the one you have.

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.

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:

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

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

Examples

Save a proxy

minicut network --proxy http://192.0.2.10:8080

Proxy saved: http://192.0.2.10:8080

Show the saved proxy

minicut network

Proxy: http://192.0.2.10:8080

Remove the proxy

minicut network --direct

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:

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

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

Output

It prints one line for each step it did. With --json:

{"state": "uninstalled", "revoked": true, "kept": ["projects", "library", "canvas", "settings.json"], "home": "~/.minicut"}

kept is [] with --all. Exit codes:

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

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.

Options

Examples

Install the skill for Claude Code

minicut install-skill --app claude-code

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

minicut install-skill --status

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:

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

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

Examples

See the rules for Claude Code

minicut agent-rules --app claude-code --dry-run

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:

No Claude Code (~/.claude) or Codex (~/.codex) on this computer. Nothing written.

See also