> ## Documentation Index
> Fetch the complete documentation index at: https://docs.plaud.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI di Plaud

> Accedi alle tue registrazioni di Plaud dal terminale: consulta, cerca, legge le trascrizioni, scarica audio e visualizza i riassunti AI senza aprire l'app.

## Prerequisiti

* Node.js ≥ 20 — [download](https://nodejs.org/)
* Un account Plaud

***

## Installa

```bash theme={"system"}
npm install -g @plaud-ai/cli
```

***

## Avvio rapido

```bash theme={"system"}
plaud login          # accedi tramite browser
plaud files          # consulta le tue registrazioni
plaud search "Q2"    # trova una registrazione tramite parola chiave
plaud summary <id>   # leggi il riepilogo AI
plaud transcript <id> # leggi la trascrizione completa
```

***

## Riferimento ai comandi

### Autenticazione

```bash theme={"system"}
plaud login    # accedi tramite browser — token salvati automaticamente
plaud logout   # disconnettiti e revoca l'autorizzazione
plaud me       # mostra i dettagli del tuo account attuale
```

### Esplora

```bash theme={"system"}
plaud files                   # l'ultima pagina delle registrazioni
plaud files --page 2 --page-size 50
plaud recent                  # registrazioni degli ultimi 7 giorni
plaud recent --days 30        # registrazioni degli ultimi 30 giorni
plaud today                   # registrazioni solo di oggi
```

**`plaud files`Opzioni**

| Opzione           | Descrizione                  | Predefinito |
| ----------------- | ---------------------------- | ----------- |
| `-p, --page`      | Numero di pagina (1–1000)    | `1`         |
| `-s, --page-size` | Elementi per pagina (10–100) | `20`        |

### Cerca

```bash theme={"system"}
plaud search <keyword>
plaud search "weekly" --from 2026-04-01 --to 2026-04-30
plaud search "onboarding" --max 10
```

Ricerca delle parole chiave lato client (senza distinzione tra maiuscole e minuscole) nei nomi delle registrazioni. Scansiona fino a 500 registrazioni più recenti.

| Opzione               | Descrizione                                           |
| --------------------- | ----------------------------------------------------- |
| `--from <YYYY-MM-DD>` | Inizio dell'intervallo di date (inclusivo)            |
| `--to <YYYY-MM-DD>`   | Fine dell'intervallo di date (inclusivo)              |
| `--max <n>`           | Risultati massimi da visualizzare (predefinito: `50`) |

### Leggi una registrazione

```bash theme={"system"}
plaud file <id>               # metadati completi e disponibilità
plaud audio <id>              # URL di download dell'audio per 24 ore
plaud transcript <id>         # trascrizione con timestamp
plaud transcript <id> -o transcript.txt   # salva su file
plaud summary <id>            # riepilogo AI (Markdown)
plaud summary <id> -o summary.md          # salva su file
```

### Utility

```bash theme={"system"}
plaud version    # mostra versione installata e informazioni sulla build
plaud update     # controlla se esiste una versione più recente e stampa il comando di aggiornamento
```

***

## Dati di riferimento

### Campi in `plaud files` / `plaud file`

| Campo        | Descrizione                                               |
| ------------ | --------------------------------------------------------- |
| `id`         | ID registrazione unico — utilizza questo in altri comandi |
| `name`       | Nome di registrazione                                     |
| `created_at` | Tempo di creazione (ISO 8601)                             |
| `duration`   | Durata della registrazione                                |

Campi aggiuntivi solo in `plaud file <id>`:

| Campo           | Descrizione                                  |
| --------------- | -------------------------------------------- |
| `start_at`      | Ora di inizio della registrazione (ISO 8601) |
| `serial_number` | Numero di serie del dispositivo              |
| `audio`         | Se l'audio è disponibile per il download     |
| `transcript`    | Se è disponibile una trascrizione            |
| `summary`       | Se è disponibile un riassunto AI             |

### Codici di uscita

| Codice | Significato                                        |
| ------ | -------------------------------------------------- |
| `0`    | Successo                                           |
| `1`    | Argomenti non validi o errore sconosciuto          |
| `2`    | Autenticazione non riuscita — esegui `plaud login` |
| `3`    | Errore di rete — controlla la tua connessione      |
| `4`    | Richiesta scaduta                                  |

Tutti gli errori sono scritti in **stderr**, mantenendo stdout libero per piping e scripting:

```
✖ [AUTH_FAILED] Token non valido o scaduto. Esegui `plaud login`.
```

***

## Configurazione

I token sono memorizzati in `~/.plaud/tokens.json` e gestiti automaticamente — non sono necessarie modifiche manuali.

Per un uso avanzato, crea un file di configurazione opzionale in `~/.plaud/cli.yaml`:

```yaml theme={"system"}
api_base: "https://platform.plaud.ai/developer/api"
timeout: 30000   # millisecondi
```

Le variabili d'ambiente sovrascrivono sia il file di configurazione che i valori predefiniti incorporati:

| Variabile                                 | Scopo                              |
| ----------------------------------------- | ---------------------------------- |
| `PLAUD_API_BASE`                          | Sovrascrivi l'URL di base dell'API |
| `PLAUD_CLIENT_ID` / `PLAUD_CLI_CLIENT_ID` | ID client OAuth                    |
| `PLAUD_CLIENT_SECRET`                     | Client OAuth segreto               |
| `PLAUD_AUTH_URL`                          | Endpoint di autorizzazione         |
| `PLAUD_TOKEN_URL`                         | Endpoint di scambio token          |
| `PLAUD_REFRESH_URL`                       | Endpoint di aggiornamento token    |

***

## Aggiorna

```bash theme={"system"}
npm install -g @plaud-ai/cli@latest
```

Oppure controlla prima:

```bash theme={"system"}
plaud update
```

***

## Disinstalla

```bash theme={"system"}
npm uninstall -g @plaud-ai/cli
rm -rf ~/.plaud
```

***

## Risoluzione dei problemi

| Segnale                                      | Risoluzione                                                                                         |
| -------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| `401` / "Non autenticato"                    | Esegui `plaud login`                                                                                |
| `plaud: command not found`                   | Riapri il suo terminale; verifica che `npm install -g @plaud-ai/cli` si sia completato senza errori |
| Errori di aggiornamento del token            | Elimina `~/.plaud/tokens.json` ed esegui di nuovo `plaud login`                                     |
| Il browser non si apre durante l'accesso     | Copia l'URL stampato nel terminale e aprilo manualmente                                             |
| `npx` restituisce `E404` per `@plaud-ai/cli` | Esegui `npm cache clean --force` e riprova                                                          |