# CLI di IA e skill ufficiale

> Usa la CLI SQL di DuckDB di DuckLocal con agenti di IA: ispeziona gli schemi dei file locali, esegui un'istruzione e restituisci JSON limitato senza GUI né server.

Source: https://ducklocal.app/docs/it/cli

Per la panoramica orientata alle attività, vedi [SQL per agenti di IA sui dati locali](https://ducklocal.app/it/use-cases/ai-agent-sql/). Questa pagina è il riferimento completo di comandi e output.

## Esegui senza finestra

`ducklocal --help` elenca dieci sottocomandi:

| Comando | Cosa fa |
| --- | --- |
| `ducklocal query` | Esegue un'istruzione SQL e stampa il risultato come JSON |
| `ducklocal schema` | Elenca ciò che si può interrogare, con le colonne; `--stats` per le statistiche delle colonne di una relazione |
| `ducklocal open` | Mostra SQL, una dashboard o dati nella finestra in esecuzione; `--state` rilegge cosa mostra |
| `ducklocal check` | Valida una dashboard `.dash` |
| `ducklocal metrics` | Elenca le metriche di un modello semantico; `compile` o `query` per compilarle o interrogarle |
| `ducklocal comments` | Legge e risponde ai commenti di revisione che le persone hanno lasciato su una dashboard |
| `ducklocal propose` | Propone una modifica a una dashboard perché la persona la riveda e la applichi |
| `ducklocal project` | Controlla una cartella di analisi portabile e ciò di cui ha bisogno; `relink` sistema i percorsi spostati |
| `ducklocal session` | Rilegge come un'analisi è arrivata dove è arrivata |
| `ducklocal presence` | Mostra chi sta lavorando a una dashboard aperta e dove arriverà una modifica |

`ducklocal lsp`, il language server che gli editor avviano per i file `.dash`, e `ducklocal profile`, l'alias storico di `schema --stats`, funzionano ancora ma sono omessi da `--help`.

`propose`, `project` e `session`, e le opzioni `--restricted`, `--wait` e `--if-revision`, sono arrivati nella 0.4.0 e sono trattati in [Flussi di lavoro per agenti](agent-workflows.md). `metrics` e `--format html` sono successivi alla 0.4.1: sono sul branch `main` e arriveranno con la prossima versione. `metrics` è trattato in [Metriche semantiche](metrics.md).

`ducklocal query` esegue SQL senza inizializzare la GUI, la cronologia, i file registrati, le impostazioni della lingua o la connessione globale della GUI. Ogni invocazione crea una connessione dedicata. Invocare DuckLocal senza comandi — o solo con percorsi di file, cartelle e pattern glob — apre la GUI normale. Per aprire nella GUI un percorso il cui nome coincide con un comando (`query`, `schema`, `open`, `check`, `metrics`, `comments`, `propose`, `project`, `session`, `presence`, `profile` o `lsp`), anteponi `./`, per esempio `./query`.

## Ottieni il comando {#get-the-command}

DuckLocal supporta macOS 12+ su Apple silicon, Windows (x86_64) e Linux (x86_64). La CLI gira direttamente dall'eseguibile dell'applicazione, quindi non devi installare un binario della CLI di DuckDB separato.

Il modo più rapido per averla nel PATH è dall'app (0.1.1 e successive): apri **Riga di comando e IA…** — il pulsante del robot nella barra del titolo, o il menu DuckLocal — e fai clic su **Installa comando**. Lo stesso dialogo installa la skill per gli agenti di IA; vedi [Installa la skill ufficiale](#install-the-official-skill). Se salti l'installazione, chiama l'eseguibile dove si trova:

```bash
# macOS
/Applications/DuckLocal.app/Contents/MacOS/ducklocal --help
# Linux: wherever you extracted the tarball
./ducklocal-linux-x86_64/ducklocal --help
# Windows (PowerShell): wherever you extracted the zip
.\ducklocal-windows-x86_64\ducklocal.exe --help
```

Da un checkout dei sorgenti, `cargo build --locked` compila `./target/debug/ducklocal`. Gli esempi qui sotto danno per scontato che `ducklocal` sia nel tuo PATH. Le versioni più vecchie potrebbero non avere `query`; controlla prima `--help`. Il supporto JSON e Parquet è incluso, non viene scaricato al momento della query.

## Opzioni di query {#query-options}

```bash
ducklocal --help
ducklocal --version
ducklocal query --help
ducklocal query --sql "SELECT 1 AS n"
ducklocal query --sql "SELECT 1 AS n" --format md
ducklocal query --sql-file analysis.sql --limit 100
ducklocal query --sql-file - < analysis.sql
ducklocal query --database warehouse.duckdb --sql "SHOW TABLES"
```

- Si richiede esattamente uno tra `--sql SQL` e `--sql-file FILE`. I file devono essere UTF-8; `-` legge da stdin. L'SQL deve contenere esattamente un'istruzione. Il parser di DuckDB lo valida prima di aprire il database di destinazione o eseguire qualcosa; i commenti, i punti e virgola tra virgolette e il punto e virgola finale funzionano. Gli script vengono rifiutati, non eseguiti parzialmente.
- `--database PATH` apre un **file esistente, in sola lettura per impostazione predefinita**. Omettilo per un nuovo database in memoria. `--read-write` richiede `--database` e consente esplicitamente scritture e la creazione di un database (non delle cartelle superiori). Gli errori del database non ripiegano mai sulla memoria. Quando DuckDB rifiuta un file, il messaggio di errore inizia con il motivo che DuckLocal legge dall'header del file — scritto da una DuckDB più recente, un file dell'epoca v0.9, un file SQLite o qualcosa che non è affatto un database — e con cosa eseguire invece (per un file più recente, la copia `ATTACH … (STORAGE_VERSION)` / `COPY FROM DATABASE` da fare in quella release; per SQLite, l'`ATTACH` che lo legge), prima del messaggio di DuckDB stesso.
- `--limit N` è un intero positivo, vale 1000 per impostazione predefinita e limita le righe restituite. Si applica anche un budget di 2.000.000 di celle. Dopo il limite, la CLI continua a contare fino a 100.000 righe in più senza codificarne i valori, riportando `total_rows` e `total_rows_exact`. Questo limita l'output, non il calcolo o la memoria: ordinamenti e aggregati possono comunque elaborare l'intero input. Un errore di esecuzione incontrato dopo il limite di output fa comunque fallire il comando.
- `--format json` (il valore predefinito) è il contratto qui sotto. `--format md` rende lo stesso risultato come tabella Markdown, per un documento o per un agente che lo legge. `--format html` lo rende come un'unica pagina web autonoma; vedi [Output HTML](#html-output). Nient'altro cambia: lo stesso SQL, gli stessi limiti, gli stessi errori.
- Flag ripetuti o sconosciuti, valori mancanti, SQL vuoto e limiti non validi sono errori. Le opzioni usano valori separati, non `--flag=value`. I percorsi relativi vengono risolti rispetto alla directory di lavoro del processo, non alla cartella del file SQL. Metti tra virgolette i percorsi della shell; dentro l'SQL, raddoppia gli apostrofi (`'O''Brien.csv'`). Gli identificatori SQL usano le virgolette doppie.

**La sola lettura non è una sandbox del filesystem né della rete.** SQL come `COPY` può scrivere file anche quando il database è in sola lettura. Autorizza i percorsi di output, le sovrascritture, le mutazioni del database, l'installazione di estensioni e l'accesso esterno prima dell'esecuzione. DuckLocal non installa estensioni automaticamente né ritenta operazioni. L'SQL esplicito `INSTALL`/`LOAD` resta possibile con autorizzazione; le estensioni installate possono caricarsi da sole. Un comando fallito può aver già prodotto effetti collaterali (per esempio prima di un errore di output); ispeziona la destinazione prima di riprovare.

### Output Markdown

`--format md` è una rappresentazione, non un secondo contratto: i valori sono quelli che contiene il JSON, scritti come li mostra la griglia dei risultati.

| Valore | Reso come |
| --- | --- |
| `NULL` | `NULL` |
| intero, decimale, float | le cifre che il valore porta, esattamente — un `DECIMAL(38,10)` conserva la sua scala, `NaN`/`inf`/`-inf` sono scritti per esteso |
| `DATE` | `YYYY-MM-DD` |
| `TIMESTAMP` | `YYYY-MM-DD HH:MM:SS[.fffffffff]`, con la frazione solo quando il valore ne ha una, e con tante cifre quante ne ha. Non viene aggiunto alcun fuso orario; `--format json` conserva il conteggio grezzo |
| `TIME` | `HH:MM:SS[.ffffff]` |
| `INTERVAL` | come lo scrive DuckDB: `1 month 2 days 00:00:00.000003` |
| `BLOB`, `GEOMETRY` | `0x00ff`, eliso con `…` quando è lungo |
| `LIST`, `STRUCT`, `MAP` | `[1, 2]`, `{x: 1}`, eliso con `…` oltre 120 caratteri |

Un `|` in una cella viene escapato e un newline diventa `<br>`, così un valore non può rompere la tabella in cui si trova. A un risultato senza righe segue `_0 rows._`, e a un risultato tagliato da `--limit` o dal budget di celle segue `_Truncated at 2 of 5000 rows, so this is not the whole answer._` (`of at least …` oltre il conteggio di 100.000 righe) — un'anteprima non dovrebbe leggersi come una risposta completa. Gli errori non cambiano: JSON su stderr, stdout vuoto.

### Output HTML {#html-output}

```bash
ducklocal query --sql "SELECT * FROM 'sales.csv'" --format html > sales.html
```

`--format html` scrive gli stessi valori di `--format md` come un'unica pagina web:

- Il numero di righe e colonne, il tempo trascorso e l'SQL dietro il risultato, compresso.
- I nomi delle colonne con i loro tipi. I numeri sono allineati a destra e i `NULL` sono segnalati.
- Fai clic su un'intestazione per ordinare; i `NULL` restano in fondo. Scrivi nella casella di filtro per tenere solo le righe che corrispondono.
- Un risultato troncato da `--limit` o dal budget di celle lo dice, come in Markdown.

Lo stile e lo script sono incorporati e la pagina non scarica nulla, quindi si apre dal disco e si può pubblicare così com'è, per esempio su GitHub Pages. Ogni cella viene sottoposta a escape HTML.

## Mappa ciò che si può interrogare {#map-what-can-be-queried}

`ducklocal schema` risponde a "cosa c'è, e quali sono le sue colonne?" in una sola chiamata, mentre `DESCRIBE` risponde una relazione alla volta. È la prima cosa che un agente dovrebbe eseguire.

```bash
ducklocal schema ./data/                          # files, folders, globs
ducklocal schema --database warehouse.duckdb      # tables and views
ducklocal schema warehouse.duckdb --table orders  # one relation, whole
ducklocal schema ./logs/ --full                   # everything, however large
```

I percorsi PATH si espandono come quando trascini qualcosa sulla finestra: i file di dati di una cartella in modo ricorsivo (quelli nascosti saltati, al massimo 256), le corrispondenze di un glob e un file di database come se fosse dato con `--database`. Torna un unico oggetto JSON:

```json
{"detail":"full","relations":[{"name":"data/orders.csv","kind":"file","from":"'data/orders.csv'","rows":null,"column_count":2,"path":"data/orders.csv","columns":[{"name":"channel","type":"VARCHAR"},{"name":"amount","type":"BIGINT"}]}],"without_columns":0}
```

| Campo | Significato |
| --- | --- |
| `name` | Il percorso di un file come è stato dato (relativo alla directory di lavoro quando è sotto di essa), o il nome di una tabella come l'SQL su questa connessione la raggiunge: senza qualifica nello schema predefinito, `schema.table` altrove |
| `kind` | `file`, `glob`, `table`, `view` o `workbook` |
| `from` | L'SQL che lo legge, pronto per seguire `FROM`: un percorso tra virgolette, o un identificatore tra virgolette quando serve |
| `rows` | La stima del catalogo per una tabella, esatta per Parquet (dal suo footer), `null` dove saperlo richiederebbe una scansione — CSV, JSON, viste |
| `column_count`, `columns` | Le colonne come le descrive DuckDB |
| `files` | Per un `glob`: quanti file corrispondono |

Un glob le cui corrispondenze sono tutte di un solo formato è una sola relazione, letta come la legge un `source` di `.dash` (`ducklocal schema 'logs/*.csv'`); `--stats` la profila come una. Un glob su formati misti, e una cartella, elencano i loro file uno per uno.

Un catalogo piccolo torna intero (`"detail": "full"`). Oltre 12 relazioni o 400 colonne diventa un **riepilogo** (`"detail": "summary"`). Le 5 relazioni con più righe conservano le loro colonne; le altre elencano nome, tipo, righe e numero di colonne, e `without_columns` le conta. Per ottenere di più, `hint` nomina i due modi: `--table NAME` per una relazione (cercata per il suo nome, il suo nome di tabella senza qualifica o il nome di un file) e `--full` per tutte. Una cartella di lavoro è elencata con i suoi `sheets` e senza colonne, dato che non ha una funzione tabella; `--stats` legge il suo primo foglio. Un percorso PATH che non esiste, o un `--table` che non nomina nulla, esce con codice 2.

Testo compresso con gzip come `.json.gz` e `.csv.gz` è un file di dati qui, come lo è per i blocchi `source` e per la finestra. Un file i cui record stanno in un'unica lista — il `{"Records": [...]}` di CloudTrail, per esempio — torna con un `hint`: l'SQL che legge quei record come righe, dato che altrimenti l'unica riga e l'unica colonna descrivono solo l'involucro.

## Esplora e converti i file

Dopo aver confermato che il file reale esiste:

```bash
ducklocal query --sql "DESCRIBE SELECT * FROM 'sales.csv'"
ducklocal query --sql "SELECT * FROM 'sales.csv'" --limit 20
ducklocal query --sql "SELECT sum(amount) AS total FROM 'sales.csv'"
# Only after authorizing this output path:
ducklocal query --sql "COPY (SELECT * FROM 'sales.csv') TO 'sales.parquet' (FORMAT PARQUET)"
ducklocal query --sql "SELECT count(*), sum(amount) FROM 'sales.parquet'"
ducklocal query --sql "DESCRIBE SELECT * FROM 'events.json'"
```

Non dare per scontato che `amount` esista: esegui prima `ducklocal schema` o `DESCRIBE`. Calcola gli aggregati completi in SQL invece di sommare un'anteprima troncata. Le chiamate CLI non condividono le viste registrate della GUI né le tabelle in memoria di altre chiamate. Persisti esplicitamente quando serve:

```bash
# These are separate statements and separate invocations, with explicit write permission.
ducklocal query --database warehouse.duckdb --read-write --sql "CREATE TABLE sales AS SELECT * FROM 'sales.csv'"
ducklocal query --database warehouse.duckdb --sql "SELECT count(*) FROM sales"
```

Un conflitto di lock sul database è un errore. Chiudi l'altro scrittore (compresa la GUI) o usa una copia autorizzata; non cancellare mai i file di lock né creare in silenzio un database diverso.

## JSONL e JSON annidato {#jsonl-and-nested-json}

`read_ndjson_objects` è il lettore per JSON delimitato da newline (un oggetto per riga, `.jsonl`/`.ndjson`); `read_json`/`read_json_auto` leggono documenti JSON (un array o un singolo oggetto). Nomina esplicitamente il lettore per un file JSONL invece di affidarti al rilevamento automatico. `json_extract_string(col, '$.a.b[0].c')` percorre un percorso annidato — chiavi di oggetto e indici di array — e restituisce VARCHAR:

```bash
ducklocal query --sql "SELECT json_extract_string(event, '$.payload.items[0].sku') AS sku, count(*) AS n FROM read_ndjson_objects('events.jsonl') GROUP BY 1 ORDER BY n DESC"
```

Usa invece `json_extract` quando la foglia non è una stringa e la vuoi come JSON.

## Statistiche delle colonne

`ducklocal schema --stats` risponde alle domande che decidono un grafico, una scala e un formato numerico, prima che su di esse si costruisca qualcosa. `DESCRIBE` dice che una colonna è `DOUBLE`; le sue statistiche dicono che usa due decimali, che il suo valore più grande è mille volte la sua mediana e che le sue date saltano undici giorni nel mezzo.

```bash
ducklocal schema sales.csv --stats
ducklocal schema ./exports/ --table orders.parquet --stats
ducklocal schema --database warehouse.duckdb --table "my orders" --stats
```

`--stats` profila una sola relazione: l'unica che gli argomenti nominano, o quella scelta da `--table` — due o più senza `--table` è codice 2, con un hint che lo dice. Non si può combinare con `--full`. `ducklocal profile TARGET [--database PATH]`, delle release precedenti, è lo stesso rapporto e funziona ancora.

La relazione è un file di dati — `csv`, `tsv`, `txt`, `parquet`, `json`, `ndjson`, `jsonl` — o una cartella di lavoro (`xlsx`, `xls`, `xlsb`, `ods`; il suo primo foglio viene importato come tabella TEMP e profilato), oppure, con `--database`, il nome di una tabella o vista. Un nome con punti viene letto come `schema.table` e ogni parte viene messa tra virgolette, così un nome con uno spazio o una maiuscola funziona così com'è scritto. Una relazione che non nomina nulla è un errore di argomenti (codice 2), non uno di SQL.

Torna un unico oggetto JSON: `target`, `relation` (l'SQL su cui sono state eseguite le statistiche), `row_count`, `elapsed_ms` e `columns` nell'ordine proprio della relazione. Per colonna:

| Campo | Significato |
| --- | --- |
| `name`, `type` | come li riporta `DESCRIBE` |
| `nulls` | righe in cui la colonna è `NULL` |
| `distinct` | esatto, non stimato |
| `unique` | presente e `true` quando `distinct` è uguale a `row_count` |
| `min`, `max` | come testo, così un `DECIMAL` conserva le sue cifre |
| `decimals` | cifre dopo il punto che la colonna **usa realmente**, che non è la sua scala dichiarata |
| `median` | un valore che la colonna contiene, non un'interpolazione tra due di essi |
| `max_over_median` | quante volte il valore più grande è più grande della mediana — il numero che decide un asse lineare rispetto a uno logaritmico |
| `covered_days`, `span_days`, `missing_days` | giorni che la colonna nomina, giorni tra i suoi estremi e la differenza: `0` è una serie continua, qualsiasi altra cosa sono buchi che una linea disegnerebbe sopra |

`decimals`, `median` e `max_over_median` compaiono sulle colonne numeriche; i campi dei giorni su date e timestamp. Le colonne `LIST`, `STRUCT`, `MAP` e `UNION` riportano solo `nulls` — `min` e `max` non sono definiti su di esse.

Una colonna di testo che contiene numeri e una parola breve, come `NA` di R, riporta anche `null_marker` e `null_marker_rows`. Il rapporto aggiunge allora un `hint` che nomina la chiamata `read_csv` che legge la colonna come numeri.

Le statistiche sono esatte e leggono tutta la relazione, quindi costano una scansione completa. `--limit` non si applica: il profilo di un campione non è un profilo.

## Mostra il lavoro nella finestra in esecuzione {#show-work-in-the-running-window}

`ducklocal open` consegna qualcosa alla finestra di DuckLocal già in esecuzione — avviandone una se non ce n'è — e la porta in primo piano. È il modo in cui un agente mette il suo lavoro davanti a una persona, dove può proseguire da lì:

```bash
ducklocal open --title "Revenue by channel" --run --sql "SELECT channel, sum(amount) AS total FROM 'orders.csv' GROUP BY 1"
ducklocal open sales.dash                    # a dashboard tab
ducklocal open ./data/ --sql-file analysis.sql
echo "SELECT 42" | ducklocal open --sql-file - --no-launch
```

- I percorsi PATH si aprono come quando trascini qualcosa sulla finestra: un file `.dash` come scheda, un file di database DuckDB come database della finestra, file di dati, cartelle e glob collegati come viste. I percorsi PATH relativi vengono risolti rispetto alla cartella del comando. Una richiesta che arriva mentre la finestra sta ancora avviandosi attende che la sua apertura di avvio sia finita.
- `--sql` o `--sql-file` (`-` legge da stdin) apre una nuova scheda di query, intitolata `--title`. `--run` la esegue una volta che i percorsi PATH sono stati collegati.
- `--no-launch` fallisce con kind `not_running` invece di avviare una finestra — per una macchina dove una finestra che compare senza essere chiesta sarebbe sgradita.

Il successo stampa `{"delivered": true, "launched": BOOL}`: la consegna, non un risultato. Ciò che si apre viene eseguito nella sessione propria della finestra — la sua connessione, le sue viste collegate, la sua cronologia — e qualsiasi errore appare lì, non su stdout. Codice 2 per gli argomenti; 1 con kind `not_running` (nessuna finestra raggiungibile), `refused` (la finestra ha rifiutato la richiesta) o `launch`.

La finestra ascolta su una porta di loopback. Scrive la porta e un token casuale in un file che solo il tuo account può leggere (vedi [Impostazioni e dati dell'app](settings-and-data.md#where-things-are-stored)); un altro utente sulla macchina, o una pagina web che punta a localhost, non può raggiungerla.

### Leggi cosa mostra la finestra

`ducklocal open --state` va nella direzione opposta: non apre nulla, non avvia mai una finestra e stampa cosa mostra la finestra in esecuzione — così un agente può riprendere da dove una persona ha lasciato, invece di chiederle di incollare la sua query.

```bash
ducklocal open --state
ducklocal open --state sales.dash
ducklocal open --state --active
```

```json
{"database":":memory:","attached":[{"path":"/Users/me/data/orders.csv","name":"orders","rows":224}],"active_tab":1,"tabs":[{"kind":"query","title":"Query 1","active":false,"sql":"SELECT …","result":{"status":"rows","columns":[…],"row_count":5,"truncated":false,"preview":[["Web","132771.24"],…],"sql":"SELECT …","elapsed_ms":4}},{"kind":"dashboard","title":"sales","active":true,"path":"/Users/me/data/sales.dash","unsaved":false,"dashboard":{"running":false,"error":null,"stale":null,"plots":[…],"filters":[{"name":"channel","plot":"revenue_by_channel","column":"channel","picked":true,"value":"Web"}]}}]}
```

- `database` è il file di database aperto, o `":memory:"`; `attached` elenca i file che la finestra ha registrato come viste, con il `name` della vista. Una query della CLI non può leggere quelle viste — usa il `path`.
- Una scheda di **query** ha `sql`, il testo dell'editor eseguito o meno, e `result`: `status` è `empty`, `running`, `rows`, `affected`, `failed`, `explain` o `profile`. Per le righe: `columns`, `row_count`, `truncated`, `preview` (le prime 20 righe come le mostra la griglia, come stringhe), `elapsed_ms` e l'`sql` che le ha prodotte; per `affected`, `count` e `elapsed_ms`; per un fallimento, `error`.
- Una volta che la persona ha scelto le colonne nella scheda **Grafico**, un risultato ha anche `chart`: `type`, `x`, `y`, `split` e `dash`, un blocco `query` e un blocco `plot` che disegnano lo stesso grafico in una dashboard.
- `explain` è ciò che mostra **Explain**: `plan`, l'output di `EXPLAIN` di DuckDB come array di righe di testo, e `elapsed_ms`.
- `profile` è ciò che mostra **Profilo** (vedi [Editor SQL](sql-editor.md)): `plan`, l'albero degli operatori misurato da `EXPLAIN ANALYZE`, come array di radici, ciascuna `{operator, seconds, rows, estimated, children}` — `seconds` è il tempo proprio dell'operatore esclusi i suoi figli, `rows` ciò che ha prodotto, `estimated` la stima dell'ottimizzatore per `rows` (`null` dove il piano non ne indica nessuna), `children` di nuovo la stessa forma. `operator_seconds` è la somma del tempo proprio di ogni operatore, cioè il totale a cui sommano le quote, non il tempo di orologio; `elapsed_ms` è l'intera esecuzione.
- Una scheda di **dashboard** ha `path`, `unsaved` e `dashboard`: il percorso del suo `comments_file`, i suoi `plots` (nome, tipo, titolo, query, righe, `open_comments` e `failure` quando uno non può disegnare) e i suoi `filters` con ciò che ognuno ha scelto: `picked`, `value` (il primo valore), `values` (tutti i valori scelti, in ordine) e `multiple`. `value: null` con `picked: true` significa che è stato scelto il valore NULL.

Usa `--state sales.dash` per tenere solo le schede che mostrano quella dashboard, o `--state --active` per solo la scheda attiva. Un percorso che non è aperto restituisce codice 1, kind `not_open`, con le dashboard aperte nell'hint. `active_tab` è l'indice della scheda attiva dentro le `tabs` restituite, o `null` se non è tra esse; `database` e `attached` restano inclusi.

`--state` accetta un percorso `.dash` oppure `--active`, non entrambi. `--no-launch` è accettato e non cambia nulla. Altre opzioni, comprese `--sql` e `--run`, non sono valide (codice 2). Codice 1 con kind `not_running` quando non c'è nessuna finestra in esecuzione, e `timeout` quando non risponde entro 5 secondi.

## Valida la specifica di una dashboard {#check-a-dashboard-spec}

Il formato in sé — blocchi, attributi, tipi di grafico, regole SQL e messaggi comuni — è descritto in [Dashboard (.dash)](dashboards.md); questa sezione copre il comando.

Un file `.dash` dichiara una dashboard come Terraform dichiara l'infrastruttura — query e grafici come blocchi, riferimenti tra loro — invece di programmarla. È facile da scrivere e da confrontare con un diff, sia per una persona sia per un agente.

```hcl
query "latency" {
  sql = <<SQL
    SELECT timestamp, service, avg(latency) AS latency
    FROM logs
    GROUP BY timestamp, service
  SQL
}

plot "latency" {
  type   = "line"
  query  = query.latency
  x      = timestamp
  y      = latency
  series = service
}
```

```bash
ducklocal check dashboard.dash
ducklocal check dashboard.dash --database warehouse.duckdb
ducklocal check dashboard.dash --summary
```

Un blocco `source` nomina file di dati, relativi al file `.dash`, perché le query li leggano, e un blocco `view` contiene SQL condiviso da più query. Un blocco `query` contiene un attributo `sql` — una sola istruzione in sola lettura, come heredoc o come stringa. `SELECT`, `WITH`, quelli che iniziano con `FROM`, `VALUES`, `SHOW`, `DESCRIBE`, `SUMMARIZE` e `PIVOT` sono accettati; qualsiasi cosa che possa scrivere — DDL, DML, `COPY`, `ATTACH`, `INSTALL` — è una diagnostica, e la GUI si rifiuta di eseguirla, perché le query di una dashboard vengono eseguite ogni volta che il file si apre. Un blocco `plot` contiene `type` (uno di `line`, `bar`, `stacked_bar`, `area`, `scatter`, `pie`, `heatmap`, `histogram`, `map`, `timeline`, `table`, `card`, `text`), `query` (un riferimento come `query.latency` a un blocco query dello stesso file), le sue colonne e, facoltativamente, `title` e `width`. Un blocco `filter` rende cliccabile un grafico a barre o una tabella — un valore, o più con `multiple = true` su una barra — e una query legge la scelta come `$name`. `#` e `//` commentano fino a fine riga. [Dashboard (.dash)](dashboards.md) ha ogni attributo.

Un grafico `text` è l'eccezione: contiene `title`, `text`, o entrambi, e non accetta `query`. Le card possono usare anche `note` e `tone`; vedi [Card e pannelli di testo](dashboards.md#cards-and-text-panels).

Prima i controlli statici: l'SQL di ogni query passa dal vero parser di DuckDB su una connessione usa e getta, come `query` valida prima di eseguire, e ogni `$name` viene confrontato con i blocchi `filter` — l'SQL viene analizzato ed eseguito con ogni `$name` come `TRUE`, che è ciò che esegue la dashboard prima che si scelga qualcosa.

Poi ogni query viene eseguita, esattamente come la eseguirebbe aprire la dashboard — in sola lettura, con le sue origini, attraverso lo stesso percorso di codice e lo stesso budget di righe — e le colonne di ogni grafico vengono confrontate con le colonne che la query restituisce realmente: una `y` non numerica è un errore per ogni tipo di grafico, e così le coordinate non numeriche di una mappa o la sua `size`, e una `column` di filtro che la query del suo grafico non restituisce.

- **Senza `--database`** le query vengono eseguite in memoria, che è tutto ciò di cui ha bisogno una dashboard sulle proprie origini `source`. Una query che legge una tabella che nessuna origine definisce può essere destinata a un database che non è stato passato al controllo: viene elencata in `unresolved` (query, riga, motivo) invece di fallire, e le colonne dei suoi grafici non vengono controllate.
- **Con `--database PATH`** (file esistente, in sola lettura) vengono eseguite su quel database. Passalo ogni volta che le query leggono tabelle di un database: tutto ciò che finisce in `unresolved` non è stato controllato.

Ogni query che legge un filtro viene anche associata a un valore scelto, senza eseguire quella variante. Questo intercetta una colonna di filtro mancante in una query che la consuma, anche quando la versione iniziale con `$name = TRUE` funziona. Un filtro deve anche referenziare una colonna restituita dal grafico che lo sceglie.

Eseguire e non solo pianificare conta: alcuni fallimenti, come un cast che la build non può eseguire o un valore che non si convertirà, appaiono solo quando si leggono le righe, e un controllo che li lasciasse passare consegnerebbe una dashboard che non può disegnare. Le query vengono eseguite per intero, quindi un controllo su un database grande richiede lo stesso tempo che aprire la dashboard.

Il successo è un unico oggetto JSON che elenca le origini del file (con il loro percorso `resolved`), le viste, le query (con le loro colonne di risultato e `rows`, quante ne ha restituite ciascuna senza nulla scelto, più `truncated: true` quando il budget di righe della dashboard l'ha tagliata), i filtri (con le `queries` che leggono ciascuno), i grafici, `unresolved` e `empty` — le query che sono state eseguite e non hanno restituito righe. Una query vuota supera tutti gli altri controlli, ma di solito è una regex, un filtro o un join che non ha trovato nulla, quindi guardale una per una. Con `--summary`, il successo è una riga JSON compatta:

```json
{"file":"sales.dash","ok":true,"sources":1,"views":0,"queries":3,"filters":1,"plots":6,"unresolved":[],"empty":[]}
```

I cinque campi dei blocchi sono conteggi; `unresolved` elenca le query che non si sono potute controllare, e `empty` quelle che non hanno restituito righe.

Un blocco difettoso viene escluso mentre i blocchi validi proseguono nella validazione. Gli errori di specifica e i fallimenti delle query vengono raccolti nella stessa esecuzione, uno `file:line: message` ciascuno. Se esiste qualche diagnostica di specifica, l'uscita è 2 con kind `spec`; se falliscono solo l'esecuzione o il binding SQL, è 1 con kind `sql`. Anche i fallimenti di database e I/O escono con 1. `--summary` non nasconde le diagnostiche.

Lo stesso file si apre come scheda di dashboard nella GUI — `ducklocal dashboard.dash`, `ducklocal open dashboard.dash`, o trascinalo sulla finestra — con i grafici su una griglia di 12 colonne e un grafico che non può disegnare che mostra il motivo in linea. Vedi [Dashboard (.dash)](dashboards.md).

## Metriche da un modello semantico {#metrics}

```bash
ducklocal metrics                       # ./model.ossie.yaml
ducklocal metrics compile --metric error_count,event_count --by events.ip
ducklocal metrics query --metric event_count --by events.event_time:day \
  --views reports/investigation.dash --restricted --allow-read data
```

`ducklocal metrics` legge un modello Apache Ossie, `model.ossie.yaml`, ed elenca le sue metriche e i suoi campi. `compile` stampa l'unica `SELECT` DuckDB che risponde a una richiesta, senza leggere dati; `query` la esegue come fa `ducklocal query`, con un oggetto `semantic` che indica l'SQL e lo `sha256` del modello. Una richiesta a cui il modello non può rispondere con esattezza viene rifiutata, con codice di uscita 2 e un `kind` come `metric_fanout`. [Metriche semantiche](metrics.md) descrive il formato del modello, ogni opzione e ogni rifiuto.

## Rivedi i commenti di una dashboard {#review-comments-on-a-dashboard}

Le persone rivedono una dashboard commentando i suoi grafici nella finestra — passa il cursore su un grafico, fai clic sulla nuvoletta (vedi [Revisione con commenti](dashboards.md#review-with-comments)). `ducklocal comments` è il lato dell'agente: legge i thread e risponde, senza finestra.

```bash
ducklocal comments sales.dash [--all]
ducklocal comments sales.dash --reply c1 --text "Sorted by revenue, descending" [--resolve]
ducklocal comments sales.dash --resolve c1
ducklocal comments sales.dash --reopen c1
ducklocal comments sales.dash --add revenue_by_channel --text "Is this net of refunds?"
```

- Senza alcuna azione, stampa i thread aperti: `{file, comments_file, open, threads}`. `--all` include quelli risolti.
- Ogni thread ha `id`, `plot` e ciò che l'agente deve trovare nella specifica: `plot_title`, `plot_query` e `plot_lines`, la prima e l'ultima riga del blocco `plot` (`null` quando la specifica non viene analizzata). `plot_missing` è `true` quando non resta nessun grafico con quel nome. Poi `resolved` e `comments`, ciascuno con `author` (`user` o `agent`), su un commento di un agente il suo `name` (il nome che mostra [`presence`](#agent-presence)), `text` e `at` (RFC 3339, ora locale).
- `--reply ID --text TEXT` aggiunge la risposta dell'agente. Una risposta a un thread risolto lo riapre, a meno che non venga dato anche `--resolve`.
- `--resolve ID` e `--reopen ID` cambiano lo stato di un thread; `--add PLOT --text TEXT` avvia un thread, firmato come l'agente.
- Il numero di un thread funziona come il suo ID: `--reply 1` significa `c1`. `--add` rifiuta un grafico che la specifica non ha (codice 2), e l'hint elenca i suoi grafici.
- Un'azione stampa `{thread}`, com'è cambiato.

I thread sono conservati accanto alla specifica, in `FILE.comments.json`. Una finestra in esecuzione nota una modifica entro un secondo e la mostra sul grafico. Un id di thread sconosciuto è codice 2, con un hint per elencare i thread; un file di specifica che non esiste è codice 1.

Una revisione, dall'inizio alla fine: leggi i thread aperti, modifica la specifica, esegui `ducklocal check`, poi rispondi a ogni thread con cosa è cambiato e `--resolve`. Usa `--reply` senza `--resolve` per chiedere qualcosa alla persona.

## Mostra l'attività dell'agente {#agent-presence}

`check` e `comments` dicono automaticamente a una finestra in esecuzione a quale dashboard sta lavorando l'agente. `presence` può annunciare una modifica prima che avvenga:

```bash
ducklocal presence sales.dash --doing editing --plot revenue_by_channel,daily_revenue
ducklocal presence sales.dash --doing reading --agent "Analyst"
ducklocal presence sales.dash --doing idle
```

- `--doing` accetta `reading`, `editing` o `idle` (`done` è un alias di `idle`).
- `--plot` prende nomi di grafici separati da virgole. Con `editing`, i nomi nuovi sono ammessi e compaiono come segnaposto. Con `reading` o `idle`, un nome sconosciuto è codice 2.
- Il nome mostrato viene da `--agent`, poi da `DUCKLOCAL_AGENT`, poi dall'ambiente agente rilevato (Claude, Codex, Cursor o Gemini), e infine da `Agent`.
- L'output è `{delivered}`. Senza una finestra in esecuzione produce `{"delivered":false}` senza errore e senza avviare una finestra.

Il nome resta nell'angolo della dashboard finché i comandi mantengono attiva la sessione. Fai clic su di esso per il registro delle attività. Trenta secondi di silenzio o `--doing idle` terminano la sessione; i grafici modificati e aggiunti restano contrassegnati finché non vengono visti, e gli avvisi dei grafici rimossi finché non vengono chiusi. Vedi [Vedere un agente al lavoro](dashboards.md#agent-presence).

## Modifica la specifica di una dashboard con LSP {#edit-a-dashboard-spec-with-lsp}

`ducklocal lsp` è un server Language Server Protocol per i file `.dash`, su stdio, perché gli editor lo avviino. Dà a qualsiasi editor compatibile con LSP ciò che ha l'editor di specifiche della GUI:

- **Diagnostica**: quelle che riporta `check`, pubblicate a ogni apertura e modifica (sincronizzazione dell'intero documento, tutte con severità Error — sono errori, non stile).
- **Completamento**: tipi di blocco, nomi di attributo, tipi di grafico e i nomi dopo `query.` e `plot.`, ciascuno con una modifica di testo che sostituisce la parola in digitazione.
- **Hover**: documentazione per blocchi, attributi e riferimenti.
- **Vai alla definizione**: da un riferimento `query.name` o `plot.name` al nome del suo blocco.

Con `--database PATH` l'SQL di ogni query viene inoltre validato dal vero parser di DuckDB, come fa `check --database`.

Punta il supporto LSP generico del tuo editor su `ducklocal lsp` per i file `*.dash` — il comando non prende argomenti di documento; l'editor parla con esso su stdio. In Neovim (0.10+):

```lua
vim.api.nvim_create_autocmd("FileType", {
  pattern = "dash",
  callback = function(event)
    vim.lsp.start({
      name = "ducklocal",
      cmd = { "ducklocal", "lsp" },
      root_dir = vim.fs.dirname(vim.api.nvim_buf_get_name(event.buf)),
    })
  end,
})
```

In VS Code, qualsiasi estensione LSP generica fa lo stesso con il comando `ducklocal`, argomenti `["lsp"]`, selettore di documento `dash`. Codici di uscita: **0** dopo uno `shutdown`/`exit` pulito, **1** quando il client sparisce senza farlo, **2** per una riga di comando errata o un handshake di protocollo fallito.

## Contratto JSON

Le query riuscite scrivono esattamente un oggetto JSON su stdout, seguito da un newline:

```json
{"columns":[{"name":"n","type":"Int32"}],"rows":[[1]],"row_count":1,"truncated":false,"total_rows":1,"total_rows_exact":true,"elapsed_ms":1}
```

`columns` e ogni riga preservano l'ordine delle colonne e i nomi duplicati. `type` è la **rappresentazione di debug di Arrow**, non il nome del tipo SQL originale di DuckDB (per esempio HUGEINT e DECIMAL possono condividere un carrier Arrow). `row_count` conta le righe restituite. `total_rows` conta le righe prodotte, comprese quelle contate dopo il limite di output; `total_rows_exact: false` significa che il conteggio si è fermato dopo fino a 100.000 righe aggiuntive, quindi quel totale è un limite inferiore. Nessuno dei due conteggi è un conteggio di righe interessate. `elapsed_ms` misura preparazione, esecuzione e codifica delle righe, non il caricamento dei file o la creazione della connessione. I risultati con zero righe conservano i metadati. DDL/DML espongono il risultato reale di DuckDB, comprese le colonne `Count`: INSERT/COPY di solito restituiscono `[[N]]`; CREATE TABLE di solito non restituisce righe. Non vengono classificati dalla prima parola chiave SQL.

Codifica delle celle:

| Valore SQL | Codifica JSON |
| --- | --- |
| NULL | `null` (mai la stringa `"NULL"`) |
| Booleano, float finito | booleano/numero JSON |
| Intero entro ±9.007.199.254.740.991 | numero JSON |
| Intero più grande, compresi HUGEINT/UHUGEINT | `{"encoding":"integer","value":"9007199254740992"}` |
| Decimale | `{"encoding":"decimal","value":"123.450"}` con il testo decimale esatto |
| Testo, enum | stringa JSON |
| Blob, geometry | `{"encoding":"hex","value":"00ff"}`; byte in minuscolo, geometry usa WKB |
| Date | `{"encoding":"date","unit":"Day","value":"1","iso":"1970-01-02"}`; giorni dal 1970-01-01 |
| Timestamp | `{"encoding":"timestamp","unit":"Nanosecond","value":"123456789","iso":"1970-01-01T00:00:00.123456789"}`; conteggio con segno dall'epoca Unix; l'unità può anche essere Second/Millisecond/Microsecond |
| Time | `{"encoding":"time","unit":"Microsecond","value":"123456","iso":"00:00:00.123456"}`; conteggio dalla mezzanotte |
| Interval | `{"encoding":"interval","months":1,"days":2,"nanos":"3000"}` |
| NaN, infinito positivo/negativo | `{"encoding":"float","value":"NaN"}` / `"inf"` / `"-inf"` |
| List, array | array JSON, codificato ricorsivamente (compresi i null annidati) |
| Struct | `{"encoding":"struct","fields":[["name",VALUE],...]}` |
| Map | `{"encoding":"map","entries":[[KEY,VALUE],...]}`; non è un oggetto JSON, quindi le chiavi conservano i loro tipi |
| Union | `{"encoding":"union-value","value":VALUE}`; solo il valore attivo, il tag del membro non viene conservato |

I `value` temporali sono conteggi esatti, quindi non si perde precisione frazionaria; i sentinella di infinito di date e timestamp restano conteggi grezzi. Accanto a ciascuno, `iso` è lo stesso valore come testo ISO 8601 per la lettura, con tante cifre di frazione quante ne contiene l'unità. Un timestamp di una colonna con fuso orario (metadati Arrow) è un istante UTC, e il suo `iso` termina con `Z`. Anche `--format md` rende date e timestamp in modo leggibile. Poiché il wrapper Arrow di DuckDB fissato non riesce a distinguere HUGEINT, UHUGEINT e DECIMAL(38,0) annidati, le occorrenze non nulle producono un errore chiaro invece di cambiare silenziosamente segno o precisione. Converti esplicitamente quei campi in VARCHAR nell'SQL. Anche i tipi non supportati sconosciuti producono un errore; non scambiare un errore per un risultato vuoto. La codifica Union è una rappresentazione del valore attivo, non un round trip senza perdite di una union.

Gli errori scrivono un oggetto JSON su **stderr**, lasciando stdout vuoto:

```json
{"error":{"kind":"argument","message":"Unknown query option: --limt","hint":"Did you mean --limit?"}}
```

`hint` c'è quando il passo successivo è noto, nei termini propri di questa CLI: il flag che uno sbagliato doveva essere, `--read-write` per una scrittura rifiutata su un database in sola lettura, `ducklocal schema` per una tabella che non esiste, `TRY_CAST` per un valore che non si convertirà, la divisione di uno script che ha più di un'istruzione, o `AS` per una parola chiave usata come alias di colonna nudo (`SELECT count(*) AS minutes`, o mettila tra virgolette). Un agente dovrebbe agire su di esso prima di riscrivere l'SQL. È assente quando non c'è nulla da aggiungere al messaggio di DuckDB stesso, come in un errore di sintassi.

Codici di uscita: **0** successo, **2** argomenti/numero di istruzioni non validi, **1** fallimento di SQL, database, I/O o output. I kind di errore sono `argument`, `sql`, `database`, `io`, `output`, `spec` per `check`, e `not_running`, `not_open`, `refused`, `timeout` o `launch` per `open`. Controlla lo stato di uscita prima di analizzare stdout e ispeziona `truncated` prima di dichiarare la completezza. Aiuto e versione sono eccezioni in testo semplice. I fallimenti di trasporto come un pipe di stdout chiuso non possono garantire un flusso di output vuoto o completo.

## Installa la skill ufficiale {#install-the-official-skill}

La skill insegna all'agente le abitudini che mantengono oneste le sue risposte: ispezionare lo schema, visualizzare in anteprima un campione limitato, calcolare gli aggregati in SQL, controllare `truncated` e rispondere dai valori restituiti. Copre l'ispezione degli schemi, le statistiche delle colonne, le conversioni, le query ai database, le dashboard `.dash` e i loro commenti di revisione, e il consegnare lavoro alla finestra e rileggerlo; non fornisce navigazione S3, comandi specifici per dati spaziali, memoria di sessione né un server MCP.

**Dall'app.** Apri **Riga di comando e IA…** (il pulsante del robot nella barra del titolo, o il menu DuckLocal):

- **Installa comando** mette `ducklocal` nel tuo `PATH`, così la shell di un agente può eseguirlo.
- **Aggiungi a Claude Code** scrive la skill in `~/.claude/skills/ducklocal`, dove Claude Code la trova in ogni progetto. Vengono scritti solo i due file propri della skill; qualsiasi altra cosa in quella cartella viene conservata. Quando un aggiornamento di DuckLocal porta una skill più recente, il dialogo offre **Aggiorna skill**.
- **Copia il brief** copia una breve spiegazione per qualsiasi altro agente — Codex, Cursor, una finestra di chat — nominando il comando e come usarlo.

**A mano.** La skill è [`skills/ducklocal`](https://github.com/JetSquirrel/ducklocal/tree/main/skills/ducklocal). Per aggiungerla a un solo progetto invece (esempio per Claude Code):

```bash
# Run from the DuckLocal checkout; replace the destination with your project.
mkdir -p /path/to/your-project/.claude/skills
cp -R skills/ducklocal /path/to/your-project/.claude/skills/
```

Ispeziona prima una destinazione esistente invece di sovrascrivere modifiche locali. Altri agenti possono usare lo stesso `SKILL.md` più `references/cli.md` nella cartella delle skill che supportano.
