# CLI reference

> Every vukem-video command, its flags and the exit codes.

Source: https://alexgalhardo.github.io/vukem-video/docs/reference/cli/

The CLI is a thin adapter over the same service as the editor, the MCP server and the HTTP API. Add `--json` to any command for one JSON document on standard output.

## Global flags

| Flag | Type | Default | Meaning |
| --- | --- | --- | --- |
| `--json` | boolean | `false` | print one JSON document |
| `--project` | string |  | project id (default $VUKEM_VIDEO_PROJECT) |
| `--workspace` | string |  | workspace directory (default $VUKEM_VIDEO_HOME, else ~/.vukem-video) |
| `--actor` | string | `cli` | label of the actor local:&lt;label&gt; |
| `--key-file` | string |  | file holding an API key for a remote server |
| `--dry-run` | boolean | `false` | validate and report, change nothing |
| `--wait` | boolean | `true` | block until the job is final (--no-wait to return at once) |
| `--timeout` | duration | `10m` | longest --wait |

## Exit codes

| Code | Meaning |
| --- | --- |
| 0 | success |
| 1 | a failure that retrying will not fix, a failed file of media:import, a failed job, or lint --strict with an error finding |
| 2 | a retryable error (E_REVISION_CONFLICT, E_WORKSPACE_LOCKED, E_QUEUE_FULL, E_RATE_LIMITED, E_ASSET_NOT_READY) or a --wait that timed out |

## `project:list`

List the projects of the workspace

```text
vukem-video project:list [--state active|trashed|all] [--cursor c] [--limit n]
```

| Flag | Type | Default | Meaning |
| --- | --- | --- | --- |
| `--state` | string | `active` | active, trashed or all |
| `--cursor` | string |  | continue a list from this cursor |
| `--limit` | integer | `20` | items per page |

Global flags: `--json`, `--workspace`, `--actor`, `--key-file`.

Example:

```bash
vukem-video project:list --json
```

## `project:create`

Create a project

```text
vukem-video project:create --name <name> [--preset 9:16|1:1|16:9|4:5] [--fps 30] [--id prj_...]
```

| Flag | Type | Default | Meaning |
| --- | --- | --- | --- |
| `--name` | string |  | project name (required) |
| `--preset` | string | `9:16` | 9:16, 1:1, 16:9 or 4:5 |
| `--fps` | string | `30` | frames per second, for example 30 or 30000/1001 |
| `--id` | string |  | identifier to give the project |

Global flags: `--json`, `--workspace`, `--actor`, `--key-file`, `--dry-run`.

Example:

```bash
vukem-video project:create --name "Launch teaser" --json
```

## `project:show`

Show a project

```text
vukem-video project:show [<project id>] [--detail concise|full|document] [--cursor c] [--limit n]
```

| Flag | Type | Default | Meaning |
| --- | --- | --- | --- |
| `--detail` | string | `concise` | concise, full or document |
| `--cursor` | string |  | continue a list from this cursor |
| `--limit` | integer |  | items per page |

Global flags: `--json`, `--workspace`, `--actor`, `--key-file`, `--project`.

Example:

```bash
vukem-video project:show --project prj_7k2m9x4q1b
```

## `project:trash`

Move a project to the trash

```text
vukem-video project:trash <project id>
```

Global flags: `--json`, `--workspace`, `--actor`, `--key-file`, `--project`, `--dry-run`.

Example:

```bash
vukem-video project:trash prj_7k2m9x4q1b
```

## `project:restore`

Restore a trashed project

```text
vukem-video project:restore <project id>
```

Global flags: `--json`, `--workspace`, `--actor`, `--key-file`, `--project`, `--dry-run`.

Example:

```bash
vukem-video project:restore prj_7k2m9x4q1b
```

## `edit`

Apply a batch of operations to a project

```text
vukem-video edit --project <id> --ops <file|-> [--base n] [--key k]
vukem-video edit --project <id> <op> [k=v | k:=json]...
```

| Flag | Type | Default | Meaning |
| --- | --- | --- | --- |
| `--ops` | string |  | a file with the batch, or - for standard input |
| `--base` | integer |  | the revision the batch was planned against (default: the current one) |
| `--key` | string |  | idempotency key |

Global flags: `--json`, `--workspace`, `--actor`, `--key-file`, `--project`, `--dry-run`.

Example:

```bash
vukem-video edit --project prj_7k2m9x4q1b item.move item_id=itm_m1n2p3q4r5 start=2s
```

## `history`

List the steps of a project history

```text
vukem-video history --project <id> [--by a] [--cursor c] [--limit n]
```

| Flag | Type | Default | Meaning |
| --- | --- | --- | --- |
| `--by` | string |  | only the steps of this actor |
| `--cursor` | string |  | continue a list from this cursor |
| `--limit` | integer | `20` | items per page |

Global flags: `--json`, `--workspace`, `--actor`, `--key-file`, `--project`.

Example:

```bash
vukem-video history --project prj_7k2m9x4q1b --json
```

## `undo`

Undo the last step of the caller

```text
vukem-video undo --project <id>
```

Global flags: `--json`, `--workspace`, `--actor`, `--key-file`, `--project`, `--dry-run`.

Example:

```bash
vukem-video undo --project prj_7k2m9x4q1b
```

## `redo`

Redo the last undone step of the caller

```text
vukem-video redo --project <id>
```

Global flags: `--json`, `--workspace`, `--actor`, `--key-file`, `--project`, `--dry-run`.

Example:

```bash
vukem-video redo --project prj_7k2m9x4q1b
```

## `lint`

Check a project against the lint rules

```text
vukem-video lint --project <id> [--severity error|warning] [--cursor c] [--limit n] [--strict]
```

| Flag | Type | Default | Meaning |
| --- | --- | --- | --- |
| `--severity` | string | `warning` | error lists only errors; warning lists everything |
| `--strict` | boolean | `false` | exit 1 when there is at least one error finding |
| `--cursor` | string |  | continue a list from this cursor |
| `--limit` | integer | `25` | items per page |

Global flags: `--json`, `--workspace`, `--actor`, `--key-file`, `--project`.

Example:

```bash
vukem-video lint --project prj_7k2m9x4q1b --json
```

## `version`

Print the version of this binary

```text
vukem-video version [--json]
```

Global flags: `--json`, `--workspace`, `--actor`, `--key-file`.

Example:

```bash
vukem-video version
```

## `mcp`

Serve the MCP tools on standard input and output

```text
vukem-video mcp [--actor <label>]
```

Global flags: `--json`, `--workspace`, `--actor`, `--key-file`.

Example:

```bash
claude mcp add vukem-video -- vukem-video mcp
```

## `media:import`

Import media files into a project

```text
vukem-video media:import <path>... --project <id> [--asset-id ast_...] [--wait] [--timeout d]
```

| Flag | Type | Default | Meaning |
| --- | --- | --- | --- |
| `--asset-id` | string, repeatable |  | id to give the asset, once per path, in order |

Global flags: `--json`, `--workspace`, `--actor`, `--key-file`, `--project`, `--wait`, `--timeout`.

Example:

```bash
vukem-video media:import clip.mov --project prj_7k2m9x4q1b --json
```

## `media:inspect`

Show what is known about an asset

```text
vukem-video media:inspect <asset id> --project <id> [--sections probe,transcript,silences,loudness]
```

| Flag | Type | Default | Meaning |
| --- | --- | --- | --- |
| `--sections` | string | `probe` | probe, transcript, silences, loudness |
| `--min-silence` | string | `0.4s` | shortest silence to report |
| `--cursor` | string |  | continue a list from this cursor |
| `--limit` | integer |  | items per page |

Global flags: `--json`, `--workspace`, `--actor`, `--key-file`, `--project`.

Example:

```bash
vukem-video media:inspect ast_3c5v8n2w6d --project prj_7k2m9x4q1b --sections probe,silences
```

## `media:list`

List the assets of a project

```text
vukem-video media:list --project <id> [--cursor c] [--limit n]
```

| Flag | Type | Default | Meaning |
| --- | --- | --- | --- |
| `--cursor` | string |  | continue a list from this cursor |
| `--limit` | integer | `50` | items per page |

Global flags: `--json`, `--workspace`, `--actor`, `--key-file`, `--project`.

Example:

```bash
vukem-video media:list --project prj_7k2m9x4q1b --json
```

## `media:trash`

Move an asset to the trash

```text
vukem-video media:trash <asset id> --project <id>
```

Global flags: `--json`, `--workspace`, `--actor`, `--key-file`, `--project`, `--dry-run`.

Example:

```bash
vukem-video media:trash ast_3c5v8n2w6d --project prj_7k2m9x4q1b
```

## `media:restore`

Restore a trashed asset

```text
vukem-video media:restore <asset id> --project <id>
```

Global flags: `--json`, `--workspace`, `--actor`, `--key-file`, `--project`, `--dry-run`.

Example:

```bash
vukem-video media:restore ast_3c5v8n2w6d --project prj_7k2m9x4q1b
```

## `view`

Render a frame or a contact sheet of a project

```text
vukem-video view --project <id> [--mode frame|sheet] [--at t] [--times t1,t2,...]
    [--from t --until t --count n] [--cols n] [--asset <id>] [--max-tokens n] [--width px]
```

| Flag | Type | Default | Meaning |
| --- | --- | --- | --- |
| `--mode` | string | `frame` | frame (one image at --at) or sheet (a grid) |
| `--at` | string |  | frame: the time to show |
| `--times` | string |  | sheet: 2 to 16 times, comma separated |
| `--from` | string |  | sheet: first time (default 0s) |
| `--until` | string |  | sheet: last time, included (default the last frame) |
| `--count` | integer | `9` | sheet: frames evenly spaced from --from to --until |
| `--cols` | integer |  | sheet: columns (default ceil(sqrt(count))) |
| `--asset` | string |  | view the media of a source asset instead of the timeline |
| `--max-tokens` | integer |  | image token budget (default 800, a sheet 1,500; at most 1,568) |
| `--width` | integer |  | image width in pixels, even; exclusive with --max-tokens |

Global flags: `--json`, `--workspace`, `--actor`, `--key-file`, `--project`.

Example:

```bash
vukem-video view --project prj_7k2m9x4q1b --at 1s --json
```

## `export`

Export a project to a file

```text
vukem-video export --project <id> [--start t] [--end t] [--format f] [--wait] [--timeout d]
```

| Flag | Type | Default | Meaning |
| --- | --- | --- | --- |
| `--start` | string |  | first time to export (default: the start) |
| `--end` | string |  | end of the export (default: the end of the timeline) |
| `--format` | string |  | mp4 (default), gif, wav or aac |

Global flags: `--json`, `--workspace`, `--actor`, `--key-file`, `--project`, `--wait`, `--timeout`.

Example:

```bash
vukem-video export --project prj_7k2m9x4q1b --json
```

## `job:show`

Show a job

```text
vukem-video job:show <job id> [--wait] [--timeout d]
```

| Flag | Type | Default | Meaning |
| --- | --- | --- | --- |
| `--wait` | boolean | `false` | block until the job is final (--no-wait to return at once) |

Global flags: `--json`, `--workspace`, `--actor`, `--key-file`, `--timeout`.

Example:

```bash
vukem-video job:show job_4h8k2m6p9t --wait
```

## `job:cancel`

Cancel a queued or running job

```text
vukem-video job:cancel <job id>
```

Global flags: `--json`, `--workspace`, `--actor`, `--key-file`.

Example:

```bash
vukem-video job:cancel job_4h8k2m6p9t
```

## `job:list`

List the jobs of a project

```text
vukem-video job:list --project <id> [--state s] [--cursor c] [--limit n]
```

| Flag | Type | Default | Meaning |
| --- | --- | --- | --- |
| `--state` | string |  | queued, running, succeeded, failed, cancelled, active or all |
| `--cursor` | string |  | continue a list from this cursor |
| `--limit` | integer | `20` | items per page |

Global flags: `--json`, `--workspace`, `--actor`, `--key-file`, `--project`.

Example:

```bash
vukem-video job:list --project prj_7k2m9x4q1b --state active
```

## `events`

Print the events of a project as they arrive

```text
vukem-video events --project <id> [--from-id n] [--since n] [--count n]
```

| Flag | Type | Default | Meaning |
| --- | --- | --- | --- |
| `--from-id` | string |  | resume after this event id (the Last-Event-ID) |
| `--since` | integer |  | replay the revisions after this one |
| `--count` | integer | `0` | stop after n events (0: until interrupted) |

Global flags: `--json`, `--workspace`, `--actor`, `--key-file`, `--project`.

Example:

```bash
vukem-video events --project prj_7k2m9x4q1b --since 4 --count 3
```

## `command:help`

List the editing commands, or describe one

```text
vukem-video command:help [<name>]
```

Global flags: `--json`, `--workspace`, `--actor`, `--key-file`.

Example:

```bash
vukem-video command:help item.move
```

## `template:list`

List the templates of the library

```text
vukem-video template:list [--cursor c] [--limit n]
```

| Flag | Type | Default | Meaning |
| --- | --- | --- | --- |
| `--cursor` | string |  | continue a list from this cursor |
| `--limit` | integer | `20` | items per page |

Global flags: `--json`, `--workspace`, `--actor`, `--key-file`.

Example:

```bash
vukem-video template:list --json
```

## `template:save`

Make a template from a project

```text
vukem-video template:save --project <id> --name <name> [--description d]
```

| Flag | Type | Default | Meaning |
| --- | --- | --- | --- |
| `--name` | string |  | template name (required) |
| `--description` | string |  | what the template is for |

Global flags: `--json`, `--workspace`, `--actor`, `--key-file`, `--project`, `--dry-run`.

Example:

```bash
vukem-video template:save --project prj_7k2m9x4q1b --name "Spring sale"
```

## `template:new`

Create a project from a template

```text
vukem-video template:new <template id> --name <name> [--fill <file|->] [--id prj_...]
```

| Flag | Type | Default | Meaning |
| --- | --- | --- | --- |
| `--name` | string |  | project name (required) |
| `--fill` | string |  | a JSON object of slot name to value: a file, or - for standard input |
| `--id` | string |  | identifier to give the project |
| `--brand-color` | string, repeatable |  | a colour of the template that takes its value from the brand kit |
| `--brand-font` | string, repeatable |  | a family of the brand kit to add to the project's fonts |

Global flags: `--json`, `--workspace`, `--actor`, `--key-file`, `--dry-run`.

Example:

```bash
vukem-video template:new tpl_5n8b2v6c1x --name "Spring sale" --fill fill.json
```

## `template:export`

Write a template to a file the workspace keeps

```text
vukem-video template:export <template id>
```

Global flags: `--json`, `--workspace`, `--actor`, `--key-file`.

Example:

```bash
vukem-video template:export tpl_5n8b2v6c1x
```

## `template:import`

Add a template file to the library

```text
vukem-video template:import <path>
```

Global flags: `--json`, `--workspace`, `--actor`, `--key-file`, `--dry-run`.

Example:

```bash
vukem-video template:import spring-sale.vukem-template.zip
```

## `bundle:export`

Export a project as a .vvbundle to share or to back up

```text
vukem-video bundle:export --project <id> [--no-log] [--wait]
```

| Flag | Type | Default | Meaning |
| --- | --- | --- | --- |
| `--log` | boolean | `true` | include the operation log (--no-log to share without history) |

Global flags: `--json`, `--workspace`, `--actor`, `--key-file`, `--project`, `--wait`, `--timeout`.

Example:

```bash
vukem-video bundle:export --project prj_7k2m9x4q1b --wait
```

## `bundle:import`

Create a project from a .vvbundle file

```text
vukem-video bundle:import <path> [--as-new]
```

| Flag | Type | Default | Meaning |
| --- | --- | --- | --- |
| `--as-new` | boolean | `false` | give the project a new id and leave the log out (required on a server with accounts) |

Global flags: `--json`, `--workspace`, `--actor`, `--key-file`, `--dry-run`.

Example:

```bash
vukem-video bundle:import launch-teaser.vvbundle --as-new
```

## `agent:docs`

Print or write the material for agents: the skill, the AGENTS.md snippet, the MCP instructions

```text
vukem-video agent:docs --print skill|agents|instructions
vukem-video agent:docs --write <dir>
```

| Flag | Type | Default | Meaning |
| --- | --- | --- | --- |
| `--print` | string |  | print one of skill, agents or instructions |
| `--write` | string |  | write the three files into this directory |

Global flags: `--json`, `--workspace`, `--actor`, `--key-file`.

Example:

```bash
vukem-video agent:docs --write ~/.claude/skills/vukem-video
```

## `transcribe`

Transcribe the audio of an asset

```text
vukem-video transcribe --project <id> --asset <id> [--language auto] [--wait] [--timeout d]
```

| Flag | Type | Default | Meaning |
| --- | --- | --- | --- |
| `--asset` | string |  | asset to transcribe (required) |
| `--language` | string | `auto` | BCP 47 code, or auto |

Global flags: `--json`, `--workspace`, `--actor`, `--key-file`, `--project`, `--wait`, `--timeout`.

Example:

```bash
vukem-video transcribe --project prj_7k2m9x4q1b --asset ast_3c5v8n2w6d --language en
```

## `doctor`

Check the installation and the workspace

```text
vukem-video doctor [--full] [--verify] [--bundle] [--gc]
```

| Flag | Type | Default | Meaning |
| --- | --- | --- | --- |
| `--full` | boolean | `false` | run every check, not only the identity |
| `--verify` | boolean | `false` | recompute the digests of FFmpeg and the helpers |
| `--bundle` | boolean | `false` | write a diagnostic bundle inside the workspace |
| `--gc` | boolean | `false` | remove what no project refers to any more |

Global flags: `--json`, `--workspace`, `--actor`, `--key-file`.

Example:

```bash
vukem-video doctor --full
```

## `fonts`

List the bundled font families

```text
vukem-video fonts
```

Global flags: `--json`, `--workspace`, `--actor`, `--key-file`.

Example:

```bash
vukem-video fonts --json
```

## `audit`

List the audit table

```text
vukem-video audit [--project <id>] [--cursor c] [--limit n]
```

| Flag | Type | Default | Meaning |
| --- | --- | --- | --- |
| `--project` | string |  | only the entries of this project |
| `--cursor` | string |  | continue a list from this cursor |
| `--limit` | integer | `50` | items per page |

Global flags: `--json`, `--workspace`, `--actor`, `--key-file`.

Example:

```bash
vukem-video audit --limit 20 --json
```

## `tools:install`

Download a helper such as the transcription program

```text
vukem-video tools:install <name> [--model <model>] [--yes] [--timeout d]
```

| Flag | Type | Default | Meaning |
| --- | --- | --- | --- |
| `--model` | string |  | the model to download (default: small) |
| `--yes` | boolean | `false` | do not ask for confirmation |

Global flags: `--json`, `--workspace`, `--actor`, `--key-file`, `--timeout`.

Example:

```bash
vukem-video tools:install whisper --model small
```

## `token:rotate`

Replace the local token; clients that hold the old one must be set up again

```text
vukem-video token:rotate
```

Global flags: `--json`, `--workspace`, `--actor`, `--key-file`.

Example:

```bash
vukem-video token:rotate
```

## `font:import`

Add a TrueType or OpenType font file to the font store

```text
vukem-video font:import <path>
```

Global flags: `--json`, `--workspace`, `--actor`, `--key-file`.

Example:

```bash
vukem-video font:import Brand-Regular.ttf
```

## `brand:show`

Show the brand kit: logo, colours and fonts

```text
vukem-video brand:show
```

Global flags: `--json`, `--workspace`, `--actor`, `--key-file`.

Example:

```bash
vukem-video brand:show --json
```

## `brand:set`

Replace the brand kit

```text
vukem-video brand:set --kit <file|->
```

| Flag | Type | Default | Meaning |
| --- | --- | --- | --- |
| `--kit` | string |  | a JSON object with logo, colors and fonts, all optional: a file, or - for standard input (required) |

Global flags: `--json`, `--workspace`, `--actor`, `--key-file`.

Example:

```bash
vukem-video brand:set --kit brand.json
```

## `otio:export`

Write the timeline of a project as an OpenTimelineIO file

```text
vukem-video otio:export --project <id> [--out f] [--force]
```

| Flag | Type | Default | Meaning |
| --- | --- | --- | --- |
| `--out` | string |  | the file to write (default: the name of the project, in the current directory) |
| `--force` | boolean | `false` | replace the file when it exists |

Global flags: `--json`, `--workspace`, `--actor`, `--key-file`, `--project`.

Example:

```bash
vukem-video otio:export --project prj_7k2m9x4q1b --out cut.otio
```

## `otio:import`

Apply an OpenTimelineIO file to a project as one undo step

```text
vukem-video otio:import <path> --project <id> [--base-revision n]
```

| Flag | Type | Default | Meaning |
| --- | --- | --- | --- |
| `--base-revision` | integer |  | the revision the file is applied to (default: the current one) |

Global flags: `--json`, `--workspace`, `--actor`, `--key-file`, `--project`, `--dry-run`.

Example:

```bash
vukem-video otio:import cut.otio --project prj_7k2m9x4q1b --dry-run
```
