# The CLI for agents

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

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

## 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

| Code | Meaning |
| --- | --- |
| `0` | success |
| `2` | a retryable error, or a `--wait` that ran out of time |
| `1` | anything 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

```bash
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](/docs/reference/cli).

## Next steps

- [Connect an agent](/docs/agents/connect)
