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

# Globale Optionen

> Flags, die bei jedem Youka-CLI-Befehl verfügbar sind

Jeder `youka`-Befehl akzeptiert denselben Satz globaler Flags. Sie steuern den Ausgabemodus, die Eingabeverarbeitung, das Warteverhalten und die Ziel-API.

## Flags

| Flag                      | Beschreibung                                                                                                                                              |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--json`                  | Maschinenmodus: gibt genau einen JSON-Umschlag nach stdout aus. Logs und Fortschritt werden unterdrückt.                                                  |
| `--body <file\|->`        | Führt ein JSON-Objekt aus einer Datei oder stdin zusammen. CLI-Flags überschreiben passende Felder aus `--body`.                                          |
| `--wait`                  | Fragt die erstellte Ressource ab, bis sie einen Endzustand erreicht. Häufig bei `project create`, `project sync`, `project separate` und `export create`. |
| `--idempotency-key <key>` | Leitet bei Schreiboperationen einen Idempotency-Key an die API weiter.                                                                                    |
| `--quiet`                 | Unterdrückt nicht-JSON-Fortschrittsausgabe in Kombination mit `--wait`.                                                                                   |
| `--no-color`              | Deaktiviert ANSI-Farbausgabe.                                                                                                                             |
| `--api <url>`             | Überschreibt die API-Basis-URL. Das Suffix `/de/api/v1` wird bei Bedarf automatisch angehängt.                                                            |

## JSON-Umschlag

Mit `--json` schreibt die CLI genau einen Umschlag nach stdout und sonst nichts.

Erfolg:

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

Fehler:

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

Exit-Codes:

| Code | Bedeutung                                                  |
| ---- | ---------------------------------------------------------- |
| `0`  | Erfolg.                                                    |
| `1`  | Laufzeitfehler (Netzwerk, API, Rendering).                 |
| `2`  | Ungültige Eingabe (falsche Flags, nicht lesbarer Payload). |

<Tip>
  Leite den Umschlag für Skripting durch `jq`: `youka project show $ID --json |
      jq '.data.state'`.
</Tip>

## JSON-Bodies übergeben

Jeder Create- oder Update-Befehl akzeptiert `--body` für den vollständigen Request-Body. Verwende das, statt großes JSON in der Kommandozeile zu escapen.

<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}
  # CLI flag takes priority over matching fields from --body
  youka preset create --body ./preset.json --name "Override name" --json
  ```
</CodeGroup>

## Auf asynchrone Jobs warten

`--wait` pollt die erstellte Ressource in deinem Auftrag und gibt den finalen Zustand zurück. Ohne `--wait` kehren Befehle zurück, sobald der Job in die Warteschlange gestellt wurde.

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

Kombiniere `--wait` in Skripten mit `--quiet`, um die Fortschrittsanzeige zu unterdrücken und trotzdem das JSON-Ergebnis auszugeben.

## Idempotenz

Gib `--idempotency-key` an, um Schreibbefehle sicher wiederholbar zu machen. Die Wiederverwendung desselben Keys mit demselben Payload liefert das ursprüngliche Ergebnis zurück, statt ein Duplikat zu erzeugen.

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

Verwende Idempotency-Keys immer dann, wenn ein Agent nach einem Timeout möglicherweise erneut versucht.

## Umgebungsvariablen

| Variable             | Zweck                                                        |
| -------------------- | ------------------------------------------------------------ |
| `YOUKA_API_KEY`      | API-Key, wenn nicht via `youka login` gesetzt.               |
| `YOUKA_API_BASE_URL` | Alternative API-Basis-URL. Wird durch `--api` überschrieben. |

## Was als Nächstes

* [Account](/de/cli/account) - speichere deinen API-Key
* [Projects](/de/cli/projects) - dein erster geskripteter Workflow
* [AI agents](/de/agents) - Betriebsregeln für Agent-Autoreninnen und -Autoren