Skip to content

Agents

The CLI for agents

How an agent with a shell uses vukem-video: JSON output, exit codes and waiting.

Last updated:

The idea#

Every command is an adapter over the same service as the MCP tools. For an agent three flags matter: --json prints one JSON document and nothing else on standard output; --actor <label> names the caller in the history; --project (or VUKEM_VIDEO_PROJECT) says which project.

Exit codes#

CodeMeaning
0success
2a retryable error, or a --wait that ran out of time
1anything else, including a failed file in media:import

With --json an error is one JSON document with code, message, hint and retryable, and standard error stays empty.

Waiting#

media:import and export wait by default, up to --timeout (ten minutes). --no-wait returns the job at once; job:show <id> --wait picks it up later. A wait that ran out prints the job as it is and exits 2.

Quick start#

Terminal
vukem-video project:create --name "Launch teaser" --json --actor claude-code
vukem-video edit --project prj_7k2m9x4q1b --ops - --json < batch.json
vukem-video export --project prj_7k2m9x4q1b --json

Every command and flag is in the CLI reference.

Next steps#