> ## Documentation Index
> Fetch the complete documentation index at: https://docs.youka.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Opções globais

> Flags disponíveis em todos os comandos do Youka CLI

Todos os comandos `youka` aceitam o mesmo conjunto de flags globais. Elas controlam o modo de saída, o tratamento de entrada, o comportamento de espera e a API de destino.

## Flags

| Flag                      | Descrição                                                                                                                                              |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--json`                  | Modo máquina: imprime exatamente um envelope JSON no stdout. Logs e progresso são suprimidos.                                                          |
| `--body <file\|->`        | Mescla um objeto JSON de um arquivo ou do stdin. As flags do CLI sobrescrevem campos correspondentes vindos de `--body`.                               |
| `--wait`                  | Consulta (poll) o recurso criado até ele alcançar um estado terminal. Comum em `project create`, `project sync`, `project separate` e `export create`. |
| `--idempotency-key <key>` | Encaminha uma chave de idempotência para a API em operações de escrita.                                                                                |
| `--quiet`                 | Suprime a saída de progresso não-JSON quando combinado com `--wait`.                                                                                   |
| `--no-color`              | Desativa a saída de cores ANSI.                                                                                                                        |
| `--api <url>`             | Substitui a URL base da API. O sufixo `/pt/api/v1` é anexado automaticamente quando necessário.                                                        |

## Envelope JSON

Com `--json`, o CLI grava exatamente um envelope no stdout e nada mais.

Sucesso:

```json theme={null}
{
  "ok": true,
  "data": {
    /* command result */
  }
}
```

Falha:

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing or invalid API key.",
    "details": null
  }
}
```

Códigos de saída:

| Code | Significado                                            |
| ---- | ------------------------------------------------------ |
| `0`  | Sucesso.                                               |
| `1`  | Erro de execução (rede, API, renderização).            |
| `2`  | Entrada inválida (flags incorretas, payload ilegível). |

<Tip>
  Envie o envelope por pipe para o `jq` em scripts: `youka project show $ID --json |
      jq '.data.state'`.
</Tip>

## Passando bodies JSON

Qualquer comando de criação ou atualização aceita `--body` para o corpo completo da requisição. Use isso em vez de escapar JSON grande na linha de comando.

<CodeGroup>
  ```bash from-file theme={null}
  youka preset create --body ./preset.json --json
  ```

  ```bash from-stdin theme={null}
  cat preset.json | youka preset create --body - --json
  ```

  ```bash override-with-flag theme={null}
  # A flag do CLI tem prioridade sobre campos correspondentes vindos de --body
  youka preset create --body ./preset.json --name "Override name" --json
  ```
</CodeGroup>

## Aguardando jobs assíncronos

`--wait` faz polling do recurso criado por você e retorna o estado final. Sem `--wait`, os comandos retornam assim que o job é enfileirado.

```bash theme={null}
youka project create ./song.mp3 --wait --json
youka export create $ID --wait --download --output ./out.mp4
```

Em scripts, combine `--wait` com `--quiet` para suprimir a barra de progresso enquanto ainda imprime o resultado JSON.

## Idempotência

Passe `--idempotency-key` para tornar comandos de escrita seguros para repetir. Reutilizar a mesma chave com o mesmo payload retorna o resultado original em vez de criar um duplicado.

```bash theme={null}
youka project create ./song.mp3 \
  --idempotency-key "import-2026-04-08-song-001" \
  --json
```

Use chaves de idempotência sempre que um agente puder tentar novamente após um timeout.

## Variáveis de ambiente

| Variável             | Finalidade                                                  |
| -------------------- | ----------------------------------------------------------- |
| `YOUKA_API_KEY`      | Chave de API usada quando não é definida via `youka login`. |
| `YOUKA_API_BASE_URL` | URL base alternativa da API. Substituída por `--api`.       |

## Próximos passos

* [Conta](/pt/cli/account) - salve sua chave de API
* [Projetos](/pt/cli/projects) - seu primeiro workflow com scripts
* [Agentes de IA](/pt/agents) - regras de operação para autores de agentes