Opzioni globali

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:

{
  "ok": true,
  "data": {
    /* command result */
  }
}

Errore:

{
  "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).

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

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.

youka preset create --body ./preset.json --json

cat preset.json | youka preset create --body - --json

# Il flag della CLI ha priorità sui campi corrispondenti provenienti da --body
youka preset create --body ./preset.json --name "Override name" --json

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.

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.

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 - salva la tua chiave API
Projects - il tuo primo workflow scriptato
AI agents - regole operative per gli autori di agenti

Overview

How To

Customization

Audio

Settings

Exporting

Account

Flag

Envelope JSON

Passare body JSON

Attendere job asincroni

Idempotenza

Variabili d’ambiente

Cosa c’è dopo

​Flag

​Envelope JSON

​Passare body JSON

​Attendere job asincroni

​Idempotenza

​Variabili d’ambiente

​Cosa c’è dopo

Flag

Envelope JSON

Passare body JSON

Attendere job asincroni

Idempotenza

Variabili d’ambiente

Cosa c’è dopo