# Integrations

Call MiniCut from another tool, a script or an agent. Run one command, read the exit code, then read one JSON object. No MiniCut project and no sign-in needed.

## Run a command

This runs the free take check on a video file. It runs on this computer, needs no sign-in and makes no project.

```bash Shell
out=$(minicut check take take.mp4 --json)
code=$?
echo "exit code: $code"
echo "$out"
```

```js Node
import { spawnSync } from 'node:child_process';

const run = spawnSync('minicut', ['check', 'take', 'take.mp4', '--json'], { encoding: 'utf8' });
console.log('exit code:', run.status);
const verdict = JSON.parse(run.stdout);
console.log(verdict.result, verdict.failures.length);
```

```python Python
import json
import subprocess

run = subprocess.run(["minicut", "check", "take", "take.mp4", "--json"], capture_output=True, text=True)
print("exit code:", run.returncode)
verdict = json.loads(run.stdout)
print(verdict["result"], len(verdict["failures"]))
```

Replace `take.mp4` with the path to your clip. On Windows, Node needs `shell: true` to find `minicut`.

## Output

The JSON object it prints, as the tests recorded it:

```json Output, exit 0
{
  "ok": true,
  "type": "mh.verdict",
  "check": "take",
  "at": "<volatile>",
  "clip": null,
  "take": "<dir>/take.mp4",
  "kind": "file",
  "seconds": 2,
  "window": [
    0,
    2
  ],
  "result": "pass",
  "failures": [],
  "notes": [
    "no --lines file: the spoken words were not checked (add --lines <text file> to check them, free, local speech engine)",
    "the look is not checked here: minicut check zoom <dir>/take.mp4 --json writes full-size pictures to look at"
  ],
  "sheet": null,
  "readback": null,
  "takes_made": null,
  "cap": null
}
```

A command that cannot finish prints one `error` object with a `code` and a `message` instead, and exits with the code for that error.

## Exit codes

Every command exits with one of these codes.

| Exit code | Name | Meaning |
|---|---|---|
| 0 | `OK` | ok |
| 1 | `CHECK_FAILED` | check failed |
| 2 | `COULD_NOT_RUN` | could not run |
| 3 | `NEEDS_YES` | needs yes |
| 4 | `LIMIT_REFUSED_RESERVED` | limit refused reserved |
| 5 | `FIX_INPUT` | fix input |
| 6 | `NOT_READY` | not ready |
| 7 | `OFFLINE` | offline |
| 8 | `TRY_AGAIN` | try again |
| 9 | `UPGRADE_OR_CREDITS` | upgrade or credits |
| 10 | `SIGN_IN` | sign in |
| 11 | `FLAG` | flag |
| 12 | `TOO_OLD` | too old |

## Next

[Commands](/cli#commands) [Hosts](/docs/cli/hosts)

Updated 2026-11-12.