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

# Youka CLI

> Crea karaoke, personalizza lo stile ed esporta video MP4 dalla riga di comando

La Youka CLI incapsula l’API pubblica, così puoi creare karaoke da una canzone, personalizzare i testi e lo stile del video, ed esportare un MP4 finale dal tuo terminale o da un agente.

## Installazione

<CodeGroup>
  ```bash npm theme={null}
  npm install -g @youka/cli
  ```

  ```bash pnpm theme={null}
  pnpm add -g @youka/cli
  ```

  ```bash yarn theme={null}
  yarn global add @youka/cli
  ```
</CodeGroup>

Verifica l’installazione:

```bash theme={null}
youka --version
youka --help
```

## Configura l’autenticazione

<Steps>
  <Step title="Ottieni una chiave API">
    Vai su [online.youka.io/account](https://online.youka.io/account), apri
    **API keys** e copia una nuova chiave.
  </Step>

  <Step title="Salva la chiave">
    Salva in modo persistente la chiave in `~/.youka/config.json`:

    ```bash theme={null}
    youka login YOUR_API_KEY
    ```

    Oppure esportala come variabile d’ambiente:

    ```bash theme={null}
    export YOUKA_API_KEY=YOUR_API_KEY
    ```
  </Step>
</Steps>

## Crea un karaoke da un file

Usa un file audio o video locale come sorgente:

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

Questo carica la sorgente, crea il progetto karaoke, esegue il render di un export e scarica il video MP4 finale.

## Crea un karaoke da un URL

Passa un URL sorgente HTTP o HTTPS invece di un percorso file:

```bash theme={null}
youka project create "https://example.com/song.mp4" --download --output ./karaoke.mp4 --wait --json
```

Per URL di video ospitati, Youka usa `yt-dlp` per scaricare dall’URL. Puoi installare le dipendenze per il download da URL prima della prima importazione da URL:

```bash theme={null}
youka deps ensure --for url
```

## Riferimento

<Columns cols={2}>
  <Card title="Account" icon="key" href="/it/cli/account">
    Accedi, esci e ispeziona lo stato di autenticazione.
  </Card>

  <Card title="Credits" icon="coins" href="/it/cli/credits">
    Ispeziona il saldo attuale e i pacchetti di crediti in scadenza.
  </Card>

  <Card title="Billing" icon="credit-card" href="/it/cli/billing">
    Mostra i prezzi e crea URL per checkout o portale.
  </Card>

  <Card title="Projects" icon="folder" href="/it/cli/projects">
    Crea, ispeziona, attendi e aggiorna i progetti.
  </Card>

  <Card title="Exports" icon="file-video" href="/it/cli/exports">
    Esegui il render di artefatti di export nel cloud o in locale e scaricali.
  </Card>

  <Card title="Presets" icon="palette" href="/it/cli/presets">
    Gestisci configurazioni di render riutilizzabili.
  </Card>

  <Card title="Media" icon="image" href="/it/cli/media">
    Carica e gestisci media riutilizzabili.
  </Card>

  <Card title="Tasks" icon="list-check" href="/it/cli/tasks">
    Ispeziona, quando necessario, lo stato delle attività di basso livello.
  </Card>

  <Card title="Dependencies" icon="box" href="/it/cli/deps">
    Ispeziona e installa le dipendenze per l’importazione da URL e il render locale.
  </Card>

  <Card title="Global options" icon="gear" href="/it/cli/global-options">
    Flag disponibili su ogni comando.
  </Card>
</Columns>

## Pronta per gli agenti per impostazione predefinita

Ogni comando supporta una modalità leggibile dalle macchine che restituisce un singolo involucro JSON con una struttura stabile. Usa questi flag per pilotare la CLI da agenti o script:

| Flag                      | Scopo                                                                                                |
| ------------------------- | ---------------------------------------------------------------------------------------------------- |
| `--json`                  | Stampa esattamente un involucro JSON su stdout. Avanzamento e log sono soppressi.                    |
| `--body <file\|->`        | Unisce un payload JSON da un file o da stdin. I flag della CLI sovrascrivono i campi corrispondenti. |
| `--wait`                  | Interroga i job asincroni (creazione progetto, export) finché non raggiungono uno stato finale.      |
| `--idempotency-key <key>` | Passa una chiave di idempotenza a qualsiasi operazione di scrittura.                                 |
| `--quiet`                 | Sopprime l’output di avanzamento non-JSON quando usato con `--wait`.                                 |
| `--api <url>`             | Sovrascrive l’URL base dell’API pubblica.                                                            |

Struttura dell’involucro JSON:

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

In caso di errore:

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "INVALID_INPUT",
    "message": "Human-readable description",
    "details": {
      /* optional */
    }
  }
}
```

Vedi [Global options](/it/cli/global-options) per l’elenco completo.

## Export nel cloud vs in locale

`export create` viene eseguito nel cloud per impostazione predefinita. Passa `--local` per eseguire il render sulla tua macchina usando la toolchain Remotion inclusa. I render locali richiedono le dipendenze di render:

```bash theme={null}
youka deps ensure --for render
```

Vedi [Exports](/it/cli/exports) per il flusso di lavoro completo.

## Cosa fare dopo

* [Account](/it/cli/account) - salva la tua chiave API
* [Projects](/it/cli/projects) - crea ed elabora progetti
* [Exports](/it/cli/exports) - esegui il render di un video karaoke finale
* [AI agents](/it/agents) - pilota la CLI da un flusso di lavoro automatizzato