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

# Opciones globales

> Flags disponibles en cada comando de Youka CLI

Cada comando de `youka` acepta el mismo conjunto de flags globales. Controlan el modo de salida, el manejo de entrada, el comportamiento de espera y la API de destino.

## Flags

| Flag                      | Description                                                                                                                                     |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `--json`                  | Modo máquina: imprime exactamente un sobre JSON en stdout. Se suprimen los logs y el progreso.                                                  |
| `--body <file\|->`        | Fusiona un objeto JSON desde un archivo o stdin. Los flags de la CLI anulan los campos coincidentes de `--body`.                                |
| `--wait`                  | Sondea el recurso creado hasta que alcance un estado terminal. Común en `project create`, `project sync`, `project separate` y `export create`. |
| `--idempotency-key <key>` | Reenvía una clave de idempotencia a la API en operaciones de escritura.                                                                         |
| `--quiet`                 | Suprime la salida de progreso no JSON cuando se combina con `--wait`.                                                                           |
| `--no-color`              | Desactiva la salida de color ANSI.                                                                                                              |
| `--api <url>`             | Anula la URL base de la API. El sufijo `/es/api/v1` se añade automáticamente cuando es necesario.                                               |

## Sobre JSON

Con `--json`, la CLI escribe exactamente un sobre en stdout y nada más.

Éxito:

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

Fallo:

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

Códigos de salida:

| Code | Meaning                                                  |
| ---- | -------------------------------------------------------- |
| `0`  | Éxito.                                                   |
| `1`  | Error en tiempo de ejecución (red, API, renderizado).    |
| `2`  | Entrada no válida (flags incorrectos, payload ilegible). |

<Tip>
  Canaliza el sobre a través de `jq` para scripting: `youka project show $ID --json |
      jq '.data.state'`.
</Tip>

## Pasar cuerpos JSON

Cualquier comando de creación o actualización acepta `--body` para el cuerpo completo de la solicitud. Úsalo en lugar de escapar JSON grande en la línea de comandos.

<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}
  # El flag de la CLI tiene prioridad sobre los campos coincidentes de --body
  youka preset create --body ./preset.json --name "Override name" --json
  ```
</CodeGroup>

## Esperar trabajos asíncronos

`--wait` sondea el recurso creado en tu nombre y devuelve el estado final. Sin `--wait`, los comandos vuelven en cuanto el trabajo queda encolado.

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

Combina `--wait` con `--quiet` en scripts para suprimir la barra de progreso mientras sigues imprimiendo el resultado JSON.

## Idempotencia

Pasa `--idempotency-key` para que los comandos de escritura sean seguros de reintentar. Reutilizar la misma clave con el mismo payload devuelve el resultado original en lugar de crear un duplicado.

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

Usa claves de idempotencia siempre que un agente pueda reintentar tras un timeout.

## Variables de entorno

| Variable             | Purpose                                                           |
| -------------------- | ----------------------------------------------------------------- |
| `YOUKA_API_KEY`      | Clave de API usada cuando no se establece mediante `youka login`. |
| `YOUKA_API_BASE_URL` | URL base alternativa de la API. Anulada por `--api`.              |

## Qué sigue

* [Account](/es/cli/account) - guarda tu clave de API
* [Projects](/es/cli/projects) - tu primer flujo de trabajo con scripting
* [AI agents](/es/agents) - reglas operativas para autores de agentes