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

# Options globales

> Options disponibles sur chaque commande Youka CLI

Chaque commande `youka` accepte le même ensemble d’options globales. Elles contrôlent le mode de sortie, la gestion des entrées, le comportement d’attente et l’API cible.

## Options

| Option                    | Description                                                                                                                                                      |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--json`                  | Mode machine : imprime exactement une enveloppe JSON sur stdout. Les logs et la progression sont supprimés.                                                      |
| `--body <file\|->`        | Fusionne un objet JSON depuis un fichier ou stdin. Les options CLI remplacent les champs correspondants de `--body`.                                             |
| `--wait`                  | Interroge la ressource créée jusqu’à ce qu’elle atteigne un état terminal. Courant avec `project create`, `project sync`, `project separate` et `export create`. |
| `--idempotency-key <key>` | Transmet une clé d’idempotence à l’API lors des opérations d’écriture.                                                                                           |
| `--quiet`                 | Supprime la sortie de progression non-JSON lorsqu’elle est combinée avec `--wait`.                                                                               |
| `--no-color`              | Désactive la sortie couleur ANSI.                                                                                                                                |
| `--api <url>`             | Remplace l’URL de base de l’API. Le suffixe `/fr/api/v1` est ajouté automatiquement si nécessaire.                                                               |

## Enveloppe JSON

Avec `--json`, la CLI écrit exactement une enveloppe sur stdout et rien d’autre.

Succès :

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

Échec :

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

Codes de sortie :

| Code | Signification                                           |
| ---- | ------------------------------------------------------- |
| `0`  | Succès.                                                 |
| `1`  | Erreur d’exécution (réseau, API, rendu).                |
| `2`  | Entrée invalide (mauvaises options, payload illisible). |

<Tip>
  Faites passer l’enveloppe via `jq` pour le scripting : `youka project show $ID --json |
      jq '.data.state'`.
</Tip>

## Passer des bodies JSON

Toute commande de création ou de mise à jour accepte `--body` pour le body complet de la requête. Utilisez-le plutôt que d’échapper de gros JSON sur la ligne de commande.

<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}
  # L’option CLI est prioritaire sur les champs correspondants de --body
  youka preset create --body ./preset.json --name "Override name" --json
  ```
</CodeGroup>

## Attendre les tâches asynchrones

`--wait` interroge la ressource créée pour vous et renvoie l’état final. Sans `--wait`, les commandes se terminent dès que la tâche est mise en file d’attente.

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

Associez `--wait` à `--quiet` dans des scripts pour supprimer la barre de progression tout en imprimant le résultat JSON.

## Idempotence

Passez `--idempotency-key` pour rendre les commandes d’écriture sûres à retenter. Réutiliser la même clé avec le même payload renvoie le résultat d’origine au lieu de créer un doublon.

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

Utilisez des clés d’idempotence dès qu’un agent pourrait réessayer après un timeout.

## Variables d’environnement

| Variable             | Objectif                                                          |
| -------------------- | ----------------------------------------------------------------- |
| `YOUKA_API_KEY`      | Clé API utilisée lorsqu’elle n’est pas définie via `youka login`. |
| `YOUKA_API_BASE_URL` | URL de base alternative de l’API. Remplacée par `--api`.          |

## Et ensuite

* [Compte](/fr/cli/account) - enregistrer votre clé API
* [Projets](/fr/cli/projects) - votre premier workflow scripté
* [Agents IA](/fr/agents) - règles de fonctionnement pour les auteurs d’agents