# 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 |
|---|---|
| `<folder> 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 "<name>".` | 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)