Skip to content

Reference

CLI reference

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

Last updated:

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#

FlagTypeDefaultMeaning
--jsonbooleanfalseprint one JSON document
--projectstringproject id (default $VUKEM_VIDEO_PROJECT)
--workspacestringworkspace directory (default $VUKEM_VIDEO_HOME, else ~/.vukem-video)
--actorstringclilabel of the actor local:<label>
--key-filestringfile holding an API key for a remote server
--dry-runbooleanfalsevalidate and report, change nothing
--waitbooleantrueblock until the job is final (--no-wait to return at once)
--timeoutduration10mlongest --wait

Exit codes#

CodeMeaning
0success
1a failure that retrying will not fix, a failed file of media:import, a failed job, or lint --strict with an error finding
2a 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]
FlagTypeDefaultMeaning
--statestringactiveactive, trashed or all
--cursorstringcontinue a list from this cursor
--limitinteger20items per page

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

Example:

Terminal
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_...]
FlagTypeDefaultMeaning
--namestringproject name (required)
--presetstring9:169:16, 1:1, 16:9 or 4:5
--fpsstring30frames per second, for example 30 or 30000/1001
--idstringidentifier to give the project

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

Example:

Terminal
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]
FlagTypeDefaultMeaning
--detailstringconciseconcise, full or document
--cursorstringcontinue a list from this cursor
--limitintegeritems per page

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

Example:

Terminal
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:

Terminal
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:

Terminal
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]...
FlagTypeDefaultMeaning
--opsstringa file with the batch, or - for standard input
--baseintegerthe revision the batch was planned against (default: the current one)
--keystringidempotency key

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

Example:

Terminal
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]
FlagTypeDefaultMeaning
--bystringonly the steps of this actor
--cursorstringcontinue a list from this cursor
--limitinteger20items per page

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

Example:

Terminal
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:

Terminal
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:

Terminal
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]
FlagTypeDefaultMeaning
--severitystringwarningerror lists only errors; warning lists everything
--strictbooleanfalseexit 1 when there is at least one error finding
--cursorstringcontinue a list from this cursor
--limitinteger25items per page

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

Example:

Terminal
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:

Terminal
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:

Terminal
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]
FlagTypeDefaultMeaning
--asset-idstring, repeatableid to give the asset, once per path, in order

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

Example:

Terminal
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]
FlagTypeDefaultMeaning
--sectionsstringprobeprobe, transcript, silences, loudness
--min-silencestring0.4sshortest silence to report
--cursorstringcontinue a list from this cursor
--limitintegeritems per page

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

Example:

Terminal
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]
FlagTypeDefaultMeaning
--cursorstringcontinue a list from this cursor
--limitinteger50items per page

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

Example:

Terminal
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:

Terminal
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:

Terminal
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]
FlagTypeDefaultMeaning
--modestringframeframe (one image at --at) or sheet (a grid)
--atstringframe: the time to show
--timesstringsheet: 2 to 16 times, comma separated
--fromstringsheet: first time (default 0s)
--untilstringsheet: last time, included (default the last frame)
--countinteger9sheet: frames evenly spaced from --from to --until
--colsintegersheet: columns (default ceil(sqrt(count)))
--assetstringview the media of a source asset instead of the timeline
--max-tokensintegerimage token budget (default 800, a sheet 1,500; at most 1,568)
--widthintegerimage width in pixels, even; exclusive with --max-tokens

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

Example:

Terminal
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]
FlagTypeDefaultMeaning
--startstringfirst time to export (default: the start)
--endstringend of the export (default: the end of the timeline)
--formatstringmp4 (default), gif, wav or aac

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

Example:

Terminal
vukem-video export --project prj_7k2m9x4q1b --json

job:show#

Show a job

Text
vukem-video job:show <job id> [--wait] [--timeout d]
FlagTypeDefaultMeaning
--waitbooleanfalseblock until the job is final (--no-wait to return at once)

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

Example:

Terminal
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:

Terminal
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]
FlagTypeDefaultMeaning
--statestringqueued, running, succeeded, failed, cancelled, active or all
--cursorstringcontinue a list from this cursor
--limitinteger20items per page

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

Example:

Terminal
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]
FlagTypeDefaultMeaning
--from-idstringresume after this event id (the Last-Event-ID)
--sinceintegerreplay the revisions after this one
--countinteger0stop after n events (0: until interrupted)

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

Example:

Terminal
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:

Terminal
vukem-video command:help item.move

template:list#

List the templates of the library

Text
vukem-video template:list [--cursor c] [--limit n]
FlagTypeDefaultMeaning
--cursorstringcontinue a list from this cursor
--limitinteger20items per page

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

Example:

Terminal
vukem-video template:list --json

template:save#

Make a template from a project

Text
vukem-video template:save --project <id> --name <name> [--description d]
FlagTypeDefaultMeaning
--namestringtemplate name (required)
--descriptionstringwhat the template is for

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

Example:

Terminal
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_...]
FlagTypeDefaultMeaning
--namestringproject name (required)
--fillstringa JSON object of slot name to value: a file, or - for standard input
--idstringidentifier to give the project
--brand-colorstring, repeatablea colour of the template that takes its value from the brand kit
--brand-fontstring, repeatablea family of the brand kit to add to the project's fonts

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

Example:

Terminal
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:

Terminal
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:

Terminal
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]
FlagTypeDefaultMeaning
--logbooleantrueinclude the operation log (--no-log to share without history)

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

Example:

Terminal
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]
FlagTypeDefaultMeaning
--as-newbooleanfalsegive 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:

Terminal
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>
FlagTypeDefaultMeaning
--printstringprint one of skill, agents or instructions
--writestringwrite the three files into this directory

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

Example:

Terminal
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]
FlagTypeDefaultMeaning
--assetstringasset to transcribe (required)
--languagestringautoBCP 47 code, or auto

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

Example:

Terminal
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]
FlagTypeDefaultMeaning
--fullbooleanfalserun every check, not only the identity
--verifybooleanfalserecompute the digests of FFmpeg and the helpers
--bundlebooleanfalsewrite a diagnostic bundle inside the workspace
--gcbooleanfalseremove what no project refers to any more

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

Example:

Terminal
vukem-video doctor --full

fonts#

List the bundled font families

Text
vukem-video fonts

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

Example:

Terminal
vukem-video fonts --json

audit#

List the audit table

Text
vukem-video audit [--project <id>] [--cursor c] [--limit n]
FlagTypeDefaultMeaning
--projectstringonly the entries of this project
--cursorstringcontinue a list from this cursor
--limitinteger50items per page

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

Example:

Terminal
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]
FlagTypeDefaultMeaning
--modelstringthe model to download (default: small)
--yesbooleanfalsedo not ask for confirmation

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

Example:

Terminal
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:

Terminal
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:

Terminal
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:

Terminal
vukem-video brand:show --json

brand:set#

Replace the brand kit

Text
vukem-video brand:set --kit <file|->
FlagTypeDefaultMeaning
--kitstringa JSON object with logo, colors and fonts, all optional: a file, or - for standard input (required)

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

Example:

Terminal
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]
FlagTypeDefaultMeaning
--outstringthe file to write (default: the name of the project, in the current directory)
--forcebooleanfalsereplace the file when it exists

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

Example:

Terminal
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]
FlagTypeDefaultMeaning
--base-revisionintegerthe revision the file is applied to (default: the current one)

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

Example:

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