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

# Opzioni globali

> Flag disponibili su ogni comando della Youka CLI

Ogni comando `youka` accetta lo stesso set di flag globali. Controllano la modalità di output, la gestione dell’input, il comportamento di attesa e l’API di destinazione.

## Flag

| Flag                      | Descrizione                                                                                                                                                          |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--json`                  | Modalità machine: stampa esattamente un envelope JSON su stdout. Log e avanzamento vengono soppressi.                                                                |
| `--body <file\|->`        | Unisce un oggetto JSON da un file o da stdin. I flag della CLI sovrascrivono i campi corrispondenti provenienti da `--body`.                                         |
| `--wait`                  | Effettua il polling della risorsa creata finché non raggiunge uno stato terminale. Comune in `project create`, `project sync`, `project separate` e `export create`. |
| `--idempotency-key <key>` | Inoltra una chiave di idempotenza all’API nelle operazioni di scrittura.                                                                                             |
| `--quiet`                 | Sopprime l’output di avanzamento non-JSON quando combinato con `--wait`.                                                                                             |
| `--no-color`              | Disabilita l’output ANSI a colori.                                                                                                                                   |
| `--api <url>`             | Sovrascrive l’URL base dell’API. Il suffisso `/it/api/v1` viene aggiunto automaticamente quando necessario.                                                          |

## Envelope JSON

Con `--json`, la CLI scrive esattamente un envelope su stdout e niente altro.

Successo:

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

Errore:

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

Codici di uscita:

| Code | Significato                                          |
| ---- | ---------------------------------------------------- |
| `0`  | Successo.                                            |
| `1`  | Errore di runtime (rete, API, rendering).            |
| `2`  | Input non valido (flag errati, payload illeggibile). |

<Tip>
  Inoltra l’envelope in pipe a `jq` per lo scripting: `youka project show $ID --json |
      jq '.data.state'`.
</Tip>

## Passare body JSON

Qualsiasi comando di creazione o aggiornamento accetta `--body` per il body completo della richiesta. Usalo invece di fare escaping di JSON grandi sulla riga di 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}
  # Il flag della CLI ha priorità sui campi corrispondenti provenienti da --body
  youka preset create --body ./preset.json --name "Override name" --json
  ```
</CodeGroup>

## Attendere job asincroni

`--wait` esegue il polling della risorsa creata per tuo conto e restituisce lo stato finale. Senza `--wait`, i comandi ritornano non appena il job viene messo in coda.

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

Abbina `--wait` a `--quiet` negli script per sopprimere la barra di avanzamento continuando a stampare il risultato JSON.

## Idempotenza

Passa `--idempotency-key` per rendere i comandi di scrittura sicuri da ritentare. Riutilizzare la stessa chiave con lo stesso payload restituisce il risultato originale invece di creare un duplicato.

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

Usa chiavi di idempotenza ogni volta che un agente potrebbe ritentare dopo un timeout.

## Variabili d’ambiente

| Variabile            | Scopo                                                    |
| -------------------- | -------------------------------------------------------- |
| `YOUKA_API_KEY`      | Chiave API usata quando non impostata via `youka login`. |
| `YOUKA_API_BASE_URL` | URL base dell’API alternativo. Sovrascritto da `--api`.  |

## Cosa c’è dopo

* [Account](/it/cli/account) - salva la tua chiave API
* [Projects](/it/cli/projects) - il tuo primo workflow scriptato
* [AI agents](/it/agents) - regole operative per gli autori di agenti