# A CLI para agentes

> Como um agente com um shell usa o vukem-video: saída JSON, códigos de saída e espera.

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

## A ideia

Cada comando é um adaptador sobre o mesmo serviço das ferramentas MCP. Para um agente, três flags importam: `--json` imprime um único documento JSON e nada mais na saída padrão; `--actor <rótulo>` identifica quem chama no histórico; `--project` (ou `VUKEM_VIDEO_PROJECT`) diz qual é o projeto.

## Códigos de saída

| Código | Significado |
| --- | --- |
| `0` | sucesso |
| `2` | um erro que pode ser repetido, ou um `--wait` que estourou o tempo |
| `1` | qualquer outra coisa, inclusive um arquivo que falhou no `media:import` |

Com `--json`, um erro é um único documento JSON com `code`, `message`, `hint` e `retryable`, e a saída de erro fica vazia.

## Espera

O `media:import` e o `export` esperam por padrão, até o `--timeout` (dez minutos). O `--no-wait` devolve a tarefa na hora; o `job:show <id> --wait` a retoma depois. Uma espera que estourou o tempo imprime a tarefa como está e sai com `2`.

## Início rápido

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

Todos os comandos e flags estão na [referência da CLI](/docs/reference/cli).

## Próximos passos

- [Conectar um agente](/docs/agents/connect)
