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:<label> |
--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
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:
vukem-video project:list --jsonproject:create#
Create a project
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:
vukem-video project:create --name "Launch teaser" --jsonproject:show#
Show a project
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:
vukem-video project:show --project prj_7k2m9x4q1bproject:trash#
Move a project to the trash
vukem-video project:trash <project id>Global flags: --json, --workspace, --actor, --key-file, --project, --dry-run.
Example:
vukem-video project:trash prj_7k2m9x4q1bproject:restore#
Restore a trashed project
vukem-video project:restore <project id>Global flags: --json, --workspace, --actor, --key-file, --project, --dry-run.
Example:
vukem-video project:restore prj_7k2m9x4q1bedit#
Apply a batch of operations to a project
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:
vukem-video edit --project prj_7k2m9x4q1b item.move item_id=itm_m1n2p3q4r5 start=2shistory#
List the steps of a project history
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:
vukem-video history --project prj_7k2m9x4q1b --jsonundo#
Undo the last step of the caller
vukem-video undo --project <id>Global flags: --json, --workspace, --actor, --key-file, --project, --dry-run.
Example:
vukem-video undo --project prj_7k2m9x4q1bredo#
Redo the last undone step of the caller
vukem-video redo --project <id>Global flags: --json, --workspace, --actor, --key-file, --project, --dry-run.
Example:
vukem-video redo --project prj_7k2m9x4q1blint#
Check a project against the lint rules
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:
vukem-video lint --project prj_7k2m9x4q1b --jsonversion#
Print the version of this binary
vukem-video version [--json]Global flags: --json, --workspace, --actor, --key-file.
Example:
vukem-video versionmcp#
Serve the MCP tools on standard input and output
vukem-video mcp [--actor <label>]Global flags: --json, --workspace, --actor, --key-file.
Example:
claude mcp add vukem-video -- vukem-video mcpmedia:import#
Import media files into a project
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:
vukem-video media:import clip.mov --project prj_7k2m9x4q1b --jsonmedia:inspect#
Show what is known about an asset
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:
vukem-video media:inspect ast_3c5v8n2w6d --project prj_7k2m9x4q1b --sections probe,silencesmedia:list#
List the assets of a project
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:
vukem-video media:list --project prj_7k2m9x4q1b --jsonmedia:trash#
Move an asset to the trash
vukem-video media:trash <asset id> --project <id>Global flags: --json, --workspace, --actor, --key-file, --project, --dry-run.
Example:
vukem-video media:trash ast_3c5v8n2w6d --project prj_7k2m9x4q1bmedia:restore#
Restore a trashed asset
vukem-video media:restore <asset id> --project <id>Global flags: --json, --workspace, --actor, --key-file, --project, --dry-run.
Example:
vukem-video media:restore ast_3c5v8n2w6d --project prj_7k2m9x4q1bview#
Render a frame or a contact sheet of a project
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:
vukem-video view --project prj_7k2m9x4q1b --at 1s --jsonexport#
Export a project to a file
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:
vukem-video export --project prj_7k2m9x4q1b --jsonjob:show#
Show a job
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:
vukem-video job:show job_4h8k2m6p9t --waitjob:cancel#
Cancel a queued or running job
vukem-video job:cancel <job id>Global flags: --json, --workspace, --actor, --key-file.
Example:
vukem-video job:cancel job_4h8k2m6p9tjob:list#
List the jobs of a project
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:
vukem-video job:list --project prj_7k2m9x4q1b --state activeevents#
Print the events of a project as they arrive
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:
vukem-video events --project prj_7k2m9x4q1b --since 4 --count 3command:help#
List the editing commands, or describe one
vukem-video command:help [<name>]Global flags: --json, --workspace, --actor, --key-file.
Example:
vukem-video command:help item.movetemplate:list#
List the templates of the library
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:
vukem-video template:list --jsontemplate:save#
Make a template from a project
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:
vukem-video template:save --project prj_7k2m9x4q1b --name "Spring sale"template:new#
Create a project from a template
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:
vukem-video template:new tpl_5n8b2v6c1x --name "Spring sale" --fill fill.jsontemplate:export#
Write a template to a file the workspace keeps
vukem-video template:export <template id>Global flags: --json, --workspace, --actor, --key-file.
Example:
vukem-video template:export tpl_5n8b2v6c1xtemplate:import#
Add a template file to the library
vukem-video template:import <path>Global flags: --json, --workspace, --actor, --key-file, --dry-run.
Example:
vukem-video template:import spring-sale.vukem-template.zipbundle:export#
Export a project as a .vvbundle to share or to back up
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:
vukem-video bundle:export --project prj_7k2m9x4q1b --waitbundle:import#
Create a project from a .vvbundle file
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:
vukem-video bundle:import launch-teaser.vvbundle --as-newagent:docs#
Print or write the material for agents: the skill, the AGENTS.md snippet, the MCP instructions
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:
vukem-video agent:docs --write ~/.claude/skills/vukem-videotranscribe#
Transcribe the audio of an asset
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:
vukem-video transcribe --project prj_7k2m9x4q1b --asset ast_3c5v8n2w6d --language endoctor#
Check the installation and the workspace
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:
vukem-video doctor --fullfonts#
List the bundled font families
vukem-video fontsGlobal flags: --json, --workspace, --actor, --key-file.
Example:
vukem-video fonts --jsonaudit#
List the audit table
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:
vukem-video audit --limit 20 --jsontools:install#
Download a helper such as the transcription program
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:
vukem-video tools:install whisper --model smalltoken:rotate#
Replace the local token; clients that hold the old one must be set up again
vukem-video token:rotateGlobal flags: --json, --workspace, --actor, --key-file.
Example:
vukem-video token:rotatefont:import#
Add a TrueType or OpenType font file to the font store
vukem-video font:import <path>Global flags: --json, --workspace, --actor, --key-file.
Example:
vukem-video font:import Brand-Regular.ttfbrand:show#
Show the brand kit: logo, colours and fonts
vukem-video brand:showGlobal flags: --json, --workspace, --actor, --key-file.
Example:
vukem-video brand:show --jsonbrand:set#
Replace the brand kit
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:
vukem-video brand:set --kit brand.jsonotio:export#
Write the timeline of a project as an OpenTimelineIO file
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:
vukem-video otio:export --project prj_7k2m9x4q1b --out cut.otiootio:import#
Apply an OpenTimelineIO file to a project as one undo step
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:
vukem-video otio:import cut.otio --project prj_7k2m9x4q1b --dry-run