# CLI IA et compétence officielle

> La CLI SQL DuckDB de DuckLocal avec des agents IA : inspecter le schéma local, exécuter une instruction et renvoyer un JSON borné, sans interface ni serveur.

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

Pour la vue d'ensemble orientée tâches, voir [Du SQL pour les agents IA sur des données locales](https://ducklocal.app/use-cases/ai-agent-sql/). Cette page est la référence complète des commandes et de la sortie.

## Fonctionner sans fenêtre

`ducklocal --help` liste dix sous-commandes :

| Commande | Effet |
| --- | --- |
| `ducklocal query` | Exécute une instruction SQL et affiche le résultat en JSON |
| `ducklocal schema` | Liste ce qu'il y a à interroger, avec les colonnes ; `--stats` pour les statistiques de colonnes d'une relation |
| `ducklocal open` | Affiche du SQL, un tableau de bord ou des données dans la fenêtre en cours ; `--state` relit ce qu'elle affiche |
| `ducklocal check` | Valide un tableau de bord `.dash` |
| `ducklocal metrics` | Liste les métriques d'un modèle sémantique ; `compile` ou `query` pour les compiler ou les interroger |
| `ducklocal comments` | Lit et répond aux commentaires de relecture laissés sur un tableau de bord |
| `ducklocal propose` | Suggère une modification du tableau de bord, que la personne relit et applique |
| `ducklocal project` | Vérifie un dossier d'analyse portable et ce dont il a besoin ; `relink` corrige les chemins déplacés |
| `ducklocal session` | Relit comment une analyse est arrivée là où elle est |
| `ducklocal presence` | Montre qui travaille sur un tableau de bord ouvert et où une modification va atterrir |

`ducklocal lsp`, le serveur de langage que les éditeurs lancent pour les fichiers `.dash`, et `ducklocal profile`, l'ancien alias de `schema --stats`, fonctionnent toujours mais sont omis de `--help`.

`propose`, `project` et `session`, ainsi que les options `--restricted`, `--wait` et `--if-revision`, sont arrivés en 0.4.0 et sont décrits dans [Flux de travail d'agent](agent-workflows.md). `metrics` et `--format html` sont plus récents que 0.4.1 : ils sont sur la branche `main` et sortiront avec la prochaine version. `metrics` est décrit dans [Métriques sémantiques](metrics.md).

`ducklocal query` exécute du SQL sans initialiser l'interface, l'historique, les fichiers enregistrés, les paramètres de langue ni la connexion globale de l'interface. Chaque appel crée une connexion dédiée. Lancer DuckLocal sans commande — ou seulement avec des chemins de fichiers, des dossiers et des motifs glob — ouvre l'interface habituelle. Pour ouvrir dans l'interface un chemin dont le nom correspond à une commande (`query`, `schema`, `open`, `check`, `metrics`, `comments`, `propose`, `project`, `session`, `presence`, `profile` ou `lsp`), préfixez-le par `./`, par exemple `./query`.

## Obtenir la commande {#get-the-command}

DuckLocal fonctionne sur macOS 12 et versions ultérieures (Apple silicon), Windows (x86_64) et Linux (x86_64). La CLI s'exécute directement depuis l'exécutable de l'application, vous n'avez donc pas besoin d'installer un binaire DuckDB CLI séparé.

Le plus rapide pour l'ajouter à votre PATH est de passer par l'application (0.1.1 et versions ultérieures) : ouvrez **Ligne de commande et IA…** — le bouton robot de la barre de titre, ou le menu DuckLocal — puis cliquez sur **Installer la commande**. La même boîte de dialogue installe la compétence pour les agents IA ; voir [Installer la compétence officielle](#install-the-official-skill). Si vous sautez l'installation, appelez l'exécutable là où il se trouve :

```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
```

Depuis un dépôt source, `cargo build --locked` construit `./target/debug/ducklocal`. Les exemples ci-dessous supposent que `ducklocal` est dans votre PATH. Les anciennes versions peuvent ne pas avoir `query` ; vérifiez d'abord `--help`. Le support JSON et Parquet est intégré, pas téléchargé au moment de la requête.

## Options de requête {#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"
```

- Il faut exactement l'un de `--sql SQL` et `--sql-file FILE`. Les fichiers doivent être en UTF-8 ; `-` lit stdin. Le SQL doit contenir exactement une instruction. Le parseur de DuckDB le vérifie avant d'ouvrir la base cible ou d'exécuter quoi que ce soit ; les commentaires, les points-virgules entre guillemets et le point-virgule final passent. Les scripts sont refusés, pas exécutés partiellement.
- `--database PATH` ouvre un **fichier existant, en lecture seule par défaut**. Omettez-la pour une base en mémoire neuve. `--read-write` exige `--database` et autorise explicitement les écritures et la création d'une base (pas des dossiers parents). Une erreur de base ne retombe jamais sur la mémoire. Quand DuckDB refuse un fichier, le message d'erreur commence par la raison que DuckLocal lit dans l'en-tête du fichier — écrit par un DuckDB plus récent, fichier de l'époque v0.9, fichier SQLite, ou pas une base du tout — et par ce qu'il faut lancer à la place (pour un fichier plus récent, la copie `ATTACH … (STORAGE_VERSION)` / `COPY FROM DATABASE` à faire dans cette version ; pour SQLite, l'`ATTACH` qui le lit), avant le message de DuckDB lui-même.
- `--limit N` est un entier positif, vaut 1000 par défaut et plafonne les lignes renvoyées. Un budget de 2 000 000 de cellules s'applique aussi. Une fois le plafond atteint, la CLI continue à compter jusqu'à 100 000 lignes de plus sans encoder leurs valeurs, en rapportant `total_rows` et `total_rows_exact`. Cela limite la sortie, pas le calcul ni la mémoire : un tri ou une agrégation peut encore traiter toute l'entrée. Une erreur d'exécution rencontrée après le plafond de sortie fait quand même échouer la commande.
- `--format json` (par défaut) est le contrat décrit plus bas. `--format md` rend le même résultat en tableau Markdown, pour un document ou un agent qui le lit. `--format html` le rend en une seule page web autonome ; voir [Sortie HTML](#html-output). Rien d'autre ne change : le même SQL, les mêmes limites, les mêmes erreurs.
- Les options répétées ou inconnues, les valeurs manquantes, le SQL vide et les limites invalides sont des erreurs. Les options prennent une valeur séparée, pas `--flag=value`. Les chemins relatifs se résolvent par rapport au répertoire de travail du processus, pas au répertoire du fichier SQL. Mettez les chemins du shell entre guillemets ; dans le SQL, doublez les apostrophes (`'O''Brien.csv'`). Les identifiants SQL utilisent des guillemets doubles.

**Le mode lecture seule n'est pas un bac à sable de fichiers ni de réseau.** Un SQL comme `COPY` peut écrire des fichiers même quand la base est en lecture seule. Autorisez les chemins de sortie, les écrasements, les modifications de la base, l'installation d'extensions et les accès externes avant exécution. DuckLocal n'installe pas d'extensions automatiquement et ne réessaie pas les opérations. Un `INSTALL`/`LOAD` explicite reste possible avec autorisation ; les extensions installées peuvent se charger automatiquement. Une commande échouée peut déjà avoir eu des effets de bord (par exemple avant une erreur de sortie) ; inspectez la destination avant de réessayer.

### Sortie Markdown

`--format md` est un rendu, pas un second contrat : les valeurs sont celles que contient le JSON, écrites comme la grille de résultats les affiche.

| Valeur | Rendu |
| --- | --- |
| `NULL` | `NULL` |
| entier, décimal, flottant | les chiffres que la valeur porte, exactement — un `DECIMAL(38,10)` garde son échelle, `NaN`/`inf`/`-inf` sont écrits en toutes lettres |
| `DATE` | `YYYY-MM-DD` |
| `TIMESTAMP` | `YYYY-MM-DD HH:MM:SS[.fffffffff]`, avec la fraction seulement quand la valeur en a une, et autant de chiffres qu'elle en a. Aucun fuseau n'est ajouté ; `--format json` garde le compte brut |
| `TIME` | `HH:MM:SS[.ffffff]` |
| `INTERVAL` | comme DuckDB l'écrit : `1 month 2 days 00:00:00.000003` |
| `BLOB`, `GEOMETRY` | `0x00ff`, abrégé par `…` quand c'est long |
| `LIST`, `STRUCT`, `MAP` | `[1, 2]`, `{x: 1}`, abrégé par `…` au-delà de 120 caractères |

Un `|` dans une cellule est échappé et un saut de ligne devient `<br>`, si bien qu'une valeur ne peut pas casser le tableau qui la contient. Un résultat sans ligne est suivi de `_0 rows._`, et un résultat écourté par `--limit` ou le budget de cellules par `_Truncated at 2 of 5000 rows, so this is not the whole answer._` (`of at least …` au-delà du comptage de 100 000 lignes) — un aperçu ne doit pas se lire comme une réponse complète. Les erreurs ne changent pas : JSON sur stderr, stdout vide.

### Sortie HTML {#html-output}

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

`--format html` écrit les mêmes valeurs que `--format md` sous forme d'une seule page web :

- Le nombre de lignes et de colonnes, le temps écoulé et le SQL à l'origine du résultat, replié.
- Les noms des colonnes avec leurs types. Les nombres sont alignés à droite et les `NULL` sont signalés.
- Cliquez sur un en-tête pour trier ; les `NULL` restent à la fin. Tapez dans le champ de filtre pour ne garder que les lignes qui correspondent.
- Un résultat tronqué par `--limit` ou par le budget de cellules l'indique, comme en Markdown.

Le style et le script sont intégrés et la page ne télécharge rien : elle s'ouvre depuis le disque et peut être publiée telle quelle, par exemple sur GitHub Pages. Chaque cellule est échappée en HTML.

## Cartographier ce qui est interrogeable {#map-what-can-be-queried}

`ducklocal schema` répond en un appel à « qu'y a-t-il, et quelles sont ses colonnes ? », là où `DESCRIBE` répond une relation à la fois. C'est la première chose qu'un agent devrait lancer.

```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
```

Les PATH s'étendent comme un fichier déposé sur la fenêtre : les fichiers de données d'un dossier récursivement (les fichiers cachés sont ignorés, 256 au plus), les correspondances d'un glob, et un fichier de base comme s'il était passé avec `--database`. Un objet JSON revient :

```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}
```

| Champ | Sens |
| --- | --- |
| `name` | Le chemin d'un fichier tel que donné (relatif au répertoire de travail quand il est en dessous), ou le nom d'une table tel que le SQL l'atteint sur cette connexion : nu dans le schéma par défaut, `schema.table` ailleurs |
| `kind` | `file`, `glob`, `table`, `view` ou `workbook` |
| `from` | Le SQL qui le lit, prêt à suivre `FROM` : un chemin entre guillemets, ou un identifiant entre guillemets quand il en faut un |
| `rows` | L'estimation du catalogue pour une table, exacte pour Parquet (d'après sa fin de fichier), `null` quand il faudrait un scan pour le savoir — CSV, JSON, vues |
| `column_count`, `columns` | Les colonnes telles que DuckDB les décrit |
| `files` | Pour un `glob` : combien de fichiers il correspond |

Un glob dont toutes les correspondances ont un seul format est une seule relation, lue comme le fait un `source` de `.dash` (`ducklocal schema 'logs/*.csv'`) ; `--stats` le profile comme tel. Un glob sur des formats mélangés, et un dossier, listent leurs fichiers un par un.

Un petit catalogue revient en entier (`"detail": "full"`). Au-delà de 12 relations ou 400 colonnes, c'est un **résumé** (`"detail": "summary"`) à la place. Les 5 relations qui ont le plus de lignes gardent leurs colonnes ; les autres listent nom, type, lignes et nombre de colonnes, et `without_columns` les compte. Pour en obtenir plus, `hint` nomme les deux moyens : `--table NAME` pour une relation (appariée par son nom, son nom de table nu ou le nom d'un fichier) et `--full` pour tout. Un classeur est listé avec ses `sheets` et sans colonnes, puisqu'il n'a pas de fonction de table ; `--stats` lit sa première feuille. Un PATH qui n'existe pas, ou un `--table` qui ne nomme rien, sort en code 2.

Le texte compressé en gzip, comme `.json.gz` et `.csv.gz`, est ici un fichier de données, tout comme pour les blocs `source` et la fenêtre. Un fichier dont les enregistrements tiennent dans une seule liste — `{"Records": [...]}` de CloudTrail, par exemple — revient avec un `hint` : le SQL qui lit ces enregistrements comme des lignes, puisque la ligne et la colonne uniques ne décrivent sinon que l'enveloppe.

## Explorer et convertir des fichiers

Après avoir confirmé que le fichier existe réellement :

```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'"
```

Ne supposez pas que `amount` existe : lancez d'abord `ducklocal schema` ou `DESCRIBE`. Calculez les agrégats complets en SQL plutôt que de sommer un aperçu tronqué. Les appels CLI ne partagent pas les vues enregistrées de l'interface, ni les tables en mémoire les uns des autres. Persistez explicitement quand il le faut :

```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 conflit de verrou de base est une erreur. Fermez l'autre écrivain (y compris l'interface), ou utilisez une copie autorisée ; ne supprimez jamais les fichiers de verrou et ne créez pas silencieusement une autre base.

## JSONL et JSON imbriqué {#jsonl-and-nested-json}

`read_ndjson_objects` est le lecteur des JSON délimités par retours à la ligne (un objet par ligne, `.jsonl`/`.ndjson`) ; `read_json`/`read_json_auto` lisent des documents JSON (un tableau ou un objet unique). Nommez le lecteur explicitement pour un fichier JSONL plutôt que de compter sur la détection automatique. `json_extract_string(col, '$.a.b[0].c')` parcourt un chemin imbriqué — clés d'objet et index de tableau — et répond en 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"
```

Utilisez plutôt `json_extract` quand la feuille n'est pas une chaîne et que vous la voulez en JSON.

## Statistiques de colonnes

`ducklocal schema --stats` répond aux questions qui décident d'un graphique, d'une échelle et d'un format de nombre, avant que quoi que ce soit ne se construise dessus. `DESCRIBE` dit qu'une colonne est un `DOUBLE` ; ses statistiques disent qu'elle utilise deux décimales, que sa plus grande valeur vaut mille fois sa médiane et que ses dates sautent onze jours au milieu.

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

`--stats` profile une seule relation : la seule que les arguments nomment, ou celle que `--table` choisit — deux ou plus sans `--table`, c'est le code 2, avec un hint qui le dit. Il ne se combine pas avec `--full`. `ducklocal profile TARGET [--database PATH]` vient des versions précédentes et produit le même rapport ; il fonctionne toujours.

La relation est un fichier de données — `csv`, `tsv`, `txt`, `parquet`, `json`, `ndjson`, `jsonl` — ou un classeur (`xlsx`, `xls`, `xlsb`, `ods` ; sa première feuille est importée comme table TEMP et profilée), ou, avec `--database`, un nom de table ou de vue. Un nom avec un point est lu comme `schema.table` et chaque partie est mise entre guillemets, si bien qu'un nom avec un espace ou une majuscule fonctionne tel qu'écrit. Une relation qui ne nomme rien est une erreur d'argument (code 2), pas une erreur SQL.

Un objet JSON revient : `target`, `relation` (le SQL sur lequel les statistiques ont tourné), `row_count`, `elapsed_ms`, et `columns` dans l'ordre propre à la relation. Par colonne :

| Champ | Sens |
| --- | --- |
| `name`, `type` | tels que `DESCRIBE` les rapporte |
| `nulls` | lignes où la colonne vaut `NULL` |
| `distinct` | exact, pas estimé |
| `unique` | présent et `true` quand `distinct` égale `row_count` |
| `min`, `max` | en texte, pour qu'un `DECIMAL` garde ses chiffres |
| `decimals` | chiffres après la virgule que la colonne **utilise réellement**, ce qui n'est pas son échelle déclarée |
| `median` | une valeur que la colonne contient, pas une interpolation entre deux d'entre elles |
| `max_over_median` | combien de fois la plus grande valeur dépasse la médiane — le nombre qui décide d'un axe linéaire ou logarithmique |
| `covered_days`, `span_days`, `missing_days` | jours que la colonne nomme, jours entre ses extrémités, et la différence : `0` est une série continue, tout le reste est un trou qu'une ligne tracerait par-dessus |

`decimals`, `median` et `max_over_median` apparaissent sur les colonnes numériques ; les champs de jours sur les dates et les horodatages. Les colonnes `LIST`, `STRUCT`, `MAP` et `UNION` ne rapportent que `nulls` — `min` et `max` n'y sont pas définis.

Une colonne de texte qui contient des nombres et un mot court, comme `NA` de R, rapporte aussi `null_marker` et `null_marker_rows`. Le rapport ajoute alors un `hint` nommant l'appel `read_csv` qui lit la colonne comme des nombres.

Les statistiques sont exactes et lisent toute la relation : elles coûtent donc un scan complet. `--limit` ne s'applique pas : le profil d'un échantillon n'est pas un profil.

## Montrer le travail dans la fenêtre en cours {#show-work-in-the-running-window}

`ducklocal open` remet quelque chose à la fenêtre DuckLocal déjà en cours — en démarrant une s'il n'y en a pas — et la met au premier plan. C'est ainsi qu'un agent met son travail devant une personne, là où elle peut continuer à partir de lui :

```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
```

- Les PATH s'ouvrent comme un fichier déposé sur la fenêtre : un fichier `.dash` en onglet, un fichier de base DuckDB comme base de la fenêtre, des fichiers de données, des dossiers et des globs attachés en vues. Les PATH relatifs se résolvent par rapport au répertoire de la commande. Une demande qui arrive pendant que la fenêtre démarre encore attend que son ouverture initiale soit terminée.
- `--sql` ou `--sql-file` (`-` lit stdin) ouvre un nouvel onglet de requête, intitulé `--title`. `--run` l'exécute une fois les PATH attachés.
- `--no-launch` échoue avec le type `not_running` au lieu de démarrer une fenêtre — pour une machine où une fenêtre apparaissant sans qu'on l'ait demandé serait malvenue.

Le succès affiche `{"delivered": true, "launched": BOOL}` : une livraison, pas un résultat. Ce qui s'ouvre tourne dans la session propre à la fenêtre — sa connexion, ses vues attachées, son historique — et toute erreur s'affiche là, pas sur stdout. Code 2 pour les arguments ; 1 avec le type `not_running` (aucune fenêtre joignable), `refused` (la fenêtre a rejeté la demande) ou `launch`.

La fenêtre écoute sur un port de bouclage. Elle écrit le port et un jeton aléatoire dans un fichier que seul votre compte peut lire (voir [Paramètres et données de l'app](settings-and-data.md#where-things-are-stored)) ; un autre utilisateur de la machine, ou une page web visant localhost, ne peut pas l'atteindre.

### Lire ce que la fenêtre affiche

`ducklocal open --state` va dans l'autre sens : il n'ouvre rien, ne démarre jamais de fenêtre et affiche ce que montre la fenêtre en cours — ainsi un agent peut reprendre là où une personne s'est arrêtée, au lieu de lui demander de coller sa requête.

```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` est le fichier de base ouvert, ou `":memory:"` ; `attached` liste les fichiers que la fenêtre a enregistrés comme vues, avec le `name` de la vue. Une requête CLI ne peut pas lire ces vues — utilisez le `path`.
- Un onglet **requête** a `sql`, le texte de l'éditeur, qu'il ait été exécuté ou non, et `result` : `status` vaut `empty`, `running`, `rows`, `affected`, `failed`, `explain` ou `profile`. Pour des lignes : `columns`, `row_count`, `truncated`, `preview` (les 20 premières lignes telles que la grille les montre, en chaînes), `elapsed_ms` et le `sql` qui les a produites ; pour `affected`, `count` et `elapsed_ms` ; pour un échec, `error`.
- Une fois que la personne a choisi des colonnes dans l'onglet Graphique, un résultat a aussi `chart` : `type`, `x`, `y`, `split`, et `dash`, un bloc `query` et un bloc `plot` qui dessinent le même graphique dans un tableau de bord.
- `explain` est ce qu'affiche **Expliquer** : `plan`, la sortie d'`EXPLAIN` de DuckDB sous forme de liste de lignes de texte, et `elapsed_ms`.
- `profile` est ce qu'affiche **Profiler** (voir [Éditeur SQL](sql-editor.md)) : `plan`, l'arbre d'opérateurs qu'`EXPLAIN ANALYZE` a mesuré, sous forme de liste de racines, chacune `{operator, seconds, rows, estimated, children}` — `seconds` est le temps propre de l'opérateur, ses enfants exclus, `rows` ce qu'il a produit, `estimated` l'estimation de l'optimiseur pour `rows` (`null` quand le plan n'en donne pas), `children` la même forme à nouveau. `operator_seconds` est la somme du temps propre de chaque opérateur, ce à quoi les parts s'additionnent, pas le temps réel écoulé ; `elapsed_ms` est l'exécution entière.
- Un onglet **tableau de bord** a `path`, `unsaved`, et `dashboard` : son chemin `comments_file`, ses `plots` (nom, type, titre, requête, lignes, `open_comments`, et `failure` quand l'un ne peut pas se dessiner) et ses `filters` avec ce que chacun a choisi : `picked`, `value` (la première valeur), `values` (toutes les valeurs choisies, dans l'ordre) et `multiple`. `value: null` avec `picked: true` signifie que la valeur NULL a été choisie.

Utilisez `--state sales.dash` pour ne garder que les onglets montrant ce tableau de bord, ou `--state --active` pour seulement l'onglet actif. Un chemin qui n'est pas ouvert renvoie le code 1, type `not_open`, avec les tableaux de bord ouverts dans le hint. `active_tab` est l'index de l'onglet actif dans les `tabs` renvoyés, ou `null` s'il n'en fait pas partie ; `database` et `attached` restent inclus.

`--state` accepte soit un PATH `.dash`, soit `--active`, pas les deux. `--no-launch` est accepté et ne change rien. Les autres options, dont `--sql` et `--run`, sont invalides (code 2). Code 1 avec le type `not_running` quand aucune fenêtre n'est ouverte, et `timeout` quand elle ne répond pas en 5 secondes.

## Vérifier une spec de tableau de bord {#check-a-dashboard-spec}

Le format lui-même — blocs, attributs, types de graphique, règles SQL et messages courants — est décrit dans [Tableaux de bord (.dash)](dashboards.md) ; cette section couvre la commande.

Un fichier `.dash` déclare un tableau de bord comme Terraform déclare de l'infrastructure — des requêtes et des graphiques en blocs, des références entre eux — plutôt que de le scripter. Une personne ou un agent peut facilement l'écrire et le comparer dans un diff.

```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 bloc `source` nomme des fichiers de données, relatifs au fichier `.dash`, que les requêtes lisent, et un bloc `view` contient du SQL que plusieurs requêtes partagent. Un bloc `query` contient un attribut `sql` — une instruction en lecture seule, sous forme de heredoc ou de chaîne. `SELECT`, `WITH`, les requêtes commençant par `FROM`, `VALUES`, `SHOW`, `DESCRIBE`, `SUMMARIZE` et `PIVOT` sont acceptés ; tout ce qui pourrait écrire — DDL, DML, `COPY`, `ATTACH`, `INSTALL` — est un diagnostic, et l'interface refuse de l'exécuter, parce que les requêtes d'un tableau de bord tournent à chaque ouverture du fichier. Un bloc `plot` contient `type` (l'un de `line`, `bar`, `stacked_bar`, `area`, `scatter`, `pie`, `heatmap`, `histogram`, `map`, `timeline`, `table`, `card`, `text`), `query` (une référence comme `query.latency` vers un bloc de requête du même fichier), ses colonnes, et éventuellement `title` et `width`. Un bloc `filter` rend un graphique en barres ou un tableau cliquable — une valeur, ou plusieurs avec `multiple = true` sur un graphique en barres — et une requête lit le choix comme `$name`. `#` et `//` commentent jusqu'à la fin de la ligne. [Tableaux de bord (.dash)](dashboards.md) donne chaque attribut.

Un graphique `text` est l'exception : il contient `title`, `text`, ou les deux, et ne prend pas de `query`. Les cartes peuvent aussi utiliser `note` et `tone` ; voir [Cartes et panneaux de texte](dashboards.md#cards-and-text-panels).

D'abord les vérifications statiques : le SQL de chaque requête passe par le vrai parseur DuckDB sur une connexion jetable, comme `query` le valide avant d'exécuter, et chaque `$name` est confronté aux blocs de filtre — le SQL est analysé, puis exécuté, avec chaque `$name` à `TRUE`, ce que le tableau de bord exécute avant tout choix.

Puis chaque requête s'exécute, exactement comme l'ouverture du tableau de bord l'exécuterait — en lecture seule, avec ses sources, par le même chemin de code et le même budget de lignes — et les colonnes de chaque graphique sont vérifiées contre les colonnes que la requête renvoie réellement : un `y` non numérique est une erreur pour tous les types de graphique, comme des coordonnées ou un `size` non numériques pour une carte, ou une `column` de filtre que la requête de son graphique ne renvoie pas.

- **Sans `--database`**, les requêtes tournent en mémoire, ce qui suffit à un tableau de bord construit sur ses propres fichiers `source`. Une requête qui lit une table qu'aucune source ne définit peut viser une base qui n'a pas été fournie à la vérification : elle est listée sous `unresolved` (requête, ligne, raison) plutôt que mise en échec, et les colonnes de ses graphiques ne sont pas vérifiées.
- **Avec `--database PATH`** (fichier existant, en lecture seule), elles tournent sur cette base. Passez-la dès que les requêtes lisent les tables d'une base : tout ce qui est sous `unresolved` n'a pas été vérifié.

Chaque requête qui lit un filtre est aussi liée à une valeur choisie, sans exécuter cette variante. Cela détecte une colonne de filtre absente d'une requête consommatrice, même quand la version initiale `$name = TRUE` fonctionne. Un filtre doit aussi référencer une colonne renvoyée par son graphique de sélection.

Exécuter, et pas seulement planifier, a son importance : certaines défaillances, comme un cast que la construction ne sait pas faire ou une valeur qui ne se convertit pas, n'apparaissent qu'une fois des lignes lues, et une vérification qui les laisserait passer livrerait un tableau de bord incapable de se dessiner. Les requêtes tournent en entier, donc une vérification sur une grande base prend aussi longtemps que l'ouverture du tableau de bord.

Le succès est un objet JSON listant les sources du fichier (avec chaque chemin `resolved`), les vues, les requêtes (avec leurs colonnes de résultat et `rows`, combien chacune a renvoyé sans aucun choix, plus `truncated: true` quand le budget de lignes du tableau de bord l'a coupée), les filtres (avec les `queries` qui lisent chacun d'eux), les graphiques, `unresolved` et `empty` — les requêtes qui ont tourné et n'ont renvoyé aucune ligne. Une requête vide passe toutes les autres vérifications, mais c'est en général une regex, un filtre ou une jointure qui n'a rien trouvé : regardez chacune. Avec `--summary`, le succès tient en une ligne JSON compacte :

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

Les cinq champs de blocs sont des comptes ; `unresolved` liste les requêtes qui n'ont pas pu être vérifiées, et `empty` celles qui n'ont renvoyé aucune ligne.

Un bloc fautif est écarté tandis que les blocs valides continuent d'être validés. Les erreurs de spec et les échecs de requête sont rassemblés dans la même exécution, un `file:line: message` chacun. S'il existe un diagnostic de spec, la sortie est en code 2 avec le type `spec` ; si seule l'exécution ou la liaison SQL échoue, le code est 1 avec le type `sql`. Les échecs de base et d'E/S sortent aussi en 1. `--summary` ne cache pas les diagnostics.

Le même fichier s'ouvre comme onglet de tableau de bord dans l'interface — `ducklocal dashboard.dash`, `ducklocal open dashboard.dash`, ou en le faisant glisser sur la fenêtre — avec les graphiques sur une grille de 12 colonnes et un graphique qui ne peut pas se dessiner affichant la raison sur place. Voir [Tableaux de bord (.dash)](dashboards.md).

## Métriques d'un modèle sémantique {#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` lit un modèle Apache Ossie, `model.ossie.yaml`, et liste ses métriques et ses champs. `compile` affiche l'unique `SELECT` DuckDB qui répond à une requête, sans lire de données ; `query` l'exécute comme le fait `ducklocal query`, avec un objet `semantic` qui indique le SQL et le `sha256` du modèle. Une requête à laquelle le modèle ne peut pas répondre exactement est refusée, code de sortie 2, avec un `kind` comme `metric_fanout`. [Métriques sémantiques](metrics.md) décrit le format du modèle, chaque option et chaque refus.

## Revoir les commentaires d'un tableau de bord {#review-comments-on-a-dashboard}

On relit un tableau de bord en commentant ses graphiques dans la fenêtre — survolez un graphique, cliquez sur la bulle (voir [Revoir avec des commentaires](dashboards.md#review-with-comments)). `ducklocal comments` est le côté agent : il lit les fils et y répond, sans fenêtre.

```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?"
```

- Sans action, affiche les fils ouverts : `{file, comments_file, open, threads}`. `--all` inclut ceux qui sont résolus.
- Chaque fil a `id`, `plot`, et ce dont l'agent a besoin pour le retrouver dans la spec : `plot_title`, `plot_query`, et `plot_lines`, la première et la dernière ligne du bloc `plot` (`null` quand la spec ne s'analyse pas). `plot_missing` vaut `true` quand aucun graphique de ce nom ne reste. Puis `resolved`, et `comments`, chacun avec `author` (`user` ou `agent`), sur un commentaire d'agent son `name` (le nom que montre [`presence`](#agent-presence)), `text` et `at` (RFC 3339, heure locale).
- `--reply ID --text TEXT` ajoute la réponse de l'agent. Une réponse à un fil résolu le rouvre, sauf si `--resolve` est aussi donné.
- `--resolve ID` et `--reopen ID` changent l'état d'un fil ; `--add PLOT --text TEXT` en ouvre un, signé comme l'agent.
- Le numéro d'un fil vaut son identifiant : `--reply 1` signifie `c1`. `--add` refuse un graphique que la spec n'a pas (code 2), et le hint liste ses graphiques.
- Une action affiche `{thread}`, tel que modifié.

Les fils sont conservés à côté de la spec, dans `FILE.comments.json`. Une fenêtre en cours remarque un changement en moins d'une seconde et l'affiche sur le graphique. Un identifiant de fil inconnu sort en code 2, avec un hint pour lister les fils ; un fichier de spec inexistant sort en code 1.

Une relecture, de bout en bout : lire les fils ouverts, modifier la spec, lancer `ducklocal check`, puis répondre à chaque fil avec ce qui a changé et le `--resolve`. Utilisez `--reply` sans `--resolve` pour poser une question à la personne.

## Montrer l'activité de l'agent {#agent-presence}

`check` et `comments` informent automatiquement une fenêtre en cours du tableau de bord sur lequel l'agent travaille. `presence` peut annoncer une modification avant qu'elle n'ait lieu :

```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` accepte `reading`, `editing` ou `idle` (`done` est un alias d'`idle`).
- `--plot` prend des noms de graphique séparés par des virgules. Avec `editing`, les nouveaux noms sont permis et apparaissent comme des espaces réservés. Avec `reading` ou `idle`, un nom inconnu sort en code 2.
- Le nom affiché vient de `--agent`, puis `DUCKLOCAL_AGENT`, puis de l'environnement d'agent détecté (Claude, Codex, Cursor ou Gemini), et à défaut `Agent`.
- La sortie est `{delivered}`. Sans fenêtre en cours, la sortie est `{"delivered":false}`, sans erreur et sans lancer de fenêtre.

Le nom reste dans le coin du tableau de bord tant que des commandes gardent la session active. Cliquez dessus pour le journal d'activité. Trente secondes de silence ou `--doing idle` terminent la session ; les graphiques modifiés et ajoutés restent marqués jusqu'à ce qu'ils soient vus, et les avis de graphique supprimé restent jusqu'à ce qu'ils soient écartés. Voir [Voir un agent au travail](dashboards.md#agent-presence).

## Modifier une spec de tableau de bord avec LSP {#edit-a-dashboard-spec-with-lsp}

`ducklocal lsp` est un serveur Language Server Protocol pour les fichiers `.dash`, sur stdio, que les éditeurs lancent. Il donne à tout éditeur compatible LSP ce que l'éditeur de spec de l'interface a :

- **Diagnostics** : ceux que rapporte `check`, publiés à chaque ouverture et modification (synchronisation du document entier, tous en sévérité Error — ce sont des fautes, pas du style).
- **Complétion** : types de blocs, noms d'attributs, types de graphique et les noms après `query.` et `plot.`, chacun avec une édition de texte qui remplace le mot en cours de frappe.
- **Survol** : documentation des blocs, attributs et références.
- **Aller à la définition** : depuis une référence `query.name` ou `plot.name` vers le nom de son bloc.

Avec `--database PATH`, le SQL de chaque requête est en plus validé par le vrai parseur DuckDB, comme le fait `check --database`.

Pointez le support LSP générique de votre éditeur vers `ducklocal lsp` pour les fichiers `*.dash` — la commande ne prend aucun argument de document ; l'éditeur lui parle sur stdio. Dans 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,
})
```

Dans VS Code, n'importe quelle extension LSP générique fait de même avec la commande `ducklocal`, les arguments `["lsp"]`, un sélecteur de document `dash`. Codes de sortie : **0** après un `shutdown`/`exit` propre, **1** quand le client disparaît sans lui, **2** pour une ligne de commande fautive ou une poignée de main de protocole échouée.

## Contrat JSON

Les requêtes réussies écrivent exactement un objet JSON sur stdout, suivi d'un saut de ligne :

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

`columns` et chaque ligne préservent l'ordre des colonnes et les noms de colonnes en double. `type` est la **représentation de débogage Arrow**, pas le nom du type SQL DuckDB d'origine (par exemple HUGEINT et DECIMAL peuvent partager un porteur Arrow). `row_count` compte les lignes renvoyées. `total_rows` compte les lignes produites, y compris celles comptées après le plafond de sortie ; `total_rows_exact: false` signifie que le comptage s'est arrêté après jusqu'à 100 000 lignes supplémentaires, donc ce total est une borne inférieure. Aucun des deux comptes n'est un compte de lignes affectées. `elapsed_ms` mesure la préparation, l'exécution et l'encodage des lignes, pas le chargement des fichiers ni l'établissement de la connexion. Les résultats à zéro ligne gardent leurs métadonnées. DDL/DML exposent le résultat DuckDB réel, y compris les colonnes `Count` : INSERT/COPY renvoient couramment `[[N]]` ; CREATE TABLE ne renvoie couramment aucune ligne. Ils ne sont pas classés d'après le premier mot-clé SQL.

Encodages de cellules :

| Valeur SQL | Encodage JSON |
| --- | --- |
| NULL | `null` (jamais la chaîne `"NULL"`) |
| Booléen, flottant fini | booléen/nombre JSON |
| Entier dans ±9 007 199 254 740 991 | nombre JSON |
| Entier plus grand, y compris HUGEINT/UHUGEINT | `{"encoding":"integer","value":"9007199254740992"}` |
| Décimal | `{"encoding":"decimal","value":"123.450"}` avec le texte décimal exact |
| Texte, énumération | chaîne JSON |
| Blob, géométrie | `{"encoding":"hex","value":"00ff"}` ; octets en minuscules, la géométrie utilise WKB |
| Date | `{"encoding":"date","unit":"Day","value":"1","iso":"1970-01-02"}` ; jours depuis 1970-01-01 |
| Horodatage | `{"encoding":"timestamp","unit":"Nanosecond","value":"123456789","iso":"1970-01-01T00:00:00.123456789"}` ; compte signé depuis l'époque Unix ; l'unité peut aussi être Second/Millisecond/Microsecond |
| Heure | `{"encoding":"time","unit":"Microsecond","value":"123456","iso":"00:00:00.123456"}` ; compte depuis minuit |
| Intervalle | `{"encoding":"interval","months":1,"days":2,"nanos":"3000"}` |
| NaN, infini positif/négatif | `{"encoding":"float","value":"NaN"}` / `"inf"` / `"-inf"` |
| Liste, tableau | tableau JSON, encodé récursivement (y compris les valeurs nulles imbriquées) |
| Structure | `{"encoding":"struct","fields":[["name",VALUE],...]}` |
| Map | `{"encoding":"map","entries":[[KEY,VALUE],...]}` ; pas un objet JSON, donc les clés gardent leurs types |
| Union | `{"encoding":"union-value","value":VALUE}` ; valeur active seulement, l'étiquette de membre n'est pas conservée |

Les `value` temporelles sont des comptes exacts, donc aucune précision fractionnaire n'est perdue ; les sentinelles d'infini de date et d'horodatage restent des comptes bruts. À côté de chacune, `iso` donne la même valeur en texte ISO 8601 pour la lecture, avec autant de chiffres de fraction que l'unité en tient. Un horodatage issu d'une colonne avec fuseau horaire (métadonnées Arrow) est un instant UTC, et son `iso` finit par `Z`. `--format md` rend aussi les dates et les horodatages lisibles. Comme le wrapper Arrow de DuckDB épinglé ne distingue pas les HUGEINT, UHUGEINT et DECIMAL(38,0) imbriqués, les occurrences non nulles produisent une erreur claire au lieu de changer silencieusement de signe ou de précision. Convertissez explicitement ces champs en VARCHAR dans le SQL. Les types inconnus non pris en charge produisent aussi une erreur ; ne prenez pas une erreur pour un résultat vide. L'encodage Union est une représentation de la valeur active, pas un aller-retour sans perte d'une union.

Les erreurs écrivent un objet JSON sur **stderr**, laissant stdout vide :

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

`hint` est là quand l'étape suivante est connue, dans les termes de cette CLI : l'option qu'un nom mal orthographié visait, `--read-write` pour une écriture refusée sur une base en lecture seule, `ducklocal schema` pour une table qui n'existe pas, `TRY_CAST` pour une valeur qui ne se convertit pas, le découpage d'un script qui contient plus d'une instruction, ou `AS` pour un mot-clé utilisé comme alias de colonne nu (`SELECT count(*) AS minutes`, ou mettez-le entre guillemets). Un agent devrait agir dessus avant de réécrire le SQL. Il est absent quand il n'y a rien à ajouter au message de DuckDB, comme pour une erreur de syntaxe.

Codes de sortie : **0** succès, **2** arguments ou nombre d'instructions invalides, **1** échec SQL, de base, d'E/S ou de sortie. Les types d'erreur sont `argument`, `sql`, `database`, `io`, `output`, `spec` pour `check`, et `not_running`, `not_open`, `refused`, `timeout` ou `launch` pour `open`. Vérifiez le code de sortie avant d'analyser stdout et inspectez `truncated` avant de déclarer une réponse complète. L'aide et la version sont des exceptions en texte brut. Les échecs de transport, comme un tube stdout fermé, ne peuvent pas garantir un flux de sortie vide ou complet.

## Installer la compétence officielle {#install-the-official-skill}

La compétence enseigne à un agent les habitudes qui gardent ses réponses honnêtes : inspecter le schéma, prévisualiser un échantillon borné, calculer les agrégats en SQL, vérifier `truncated` et répondre à partir des valeurs renvoyées. Elle couvre l'inspection de schéma, les statistiques de colonnes, les conversions, les requêtes de base, les tableaux de bord `.dash` et leurs commentaires de relecture, ainsi que la remise du travail à la fenêtre et sa relecture ; elle ne fournit ni navigation S3, ni commandes propres au spatial, ni mémoire de session, ni serveur MCP.

**Depuis l'application.** Ouvrez **Ligne de commande et IA…** (le bouton robot de la barre de titre, ou le menu DuckLocal) :

- **Installer la commande** met `ducklocal` dans votre `PATH`, pour que le shell d'un agent puisse la lancer.
- **Ajouter à Claude Code** écrit la compétence dans `~/.claude/skills/ducklocal`, où Claude Code la trouve dans chaque projet. Seuls les deux fichiers de la compétence sont écrits ; tout le reste de ce dossier est conservé. Quand une mise à jour de DuckLocal livre une compétence plus récente, la boîte de dialogue propose **Mettre à jour la compétence**.
- **Copier le résumé** copie une courte explication pour tout autre agent — Codex, Cursor, une fenêtre de chat — nommant la commande et son usage.

**À la main.** La compétence est [`skills/ducklocal`](https://github.com/JetSquirrel/ducklocal/tree/main/skills/ducklocal). Pour l'ajouter à un seul projet à la place (exemple pour 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/
```

Inspectez d'abord une destination existante plutôt que d'écraser des modifications locales. Les autres agents peuvent utiliser le même `SKILL.md` plus `references/cli.md` dans le répertoire de compétences qu'ils prennent en charge.
