# CLI de IA y habilidad oficial

> Usa la CLI de SQL de DuckDB de DuckLocal con agentes de IA: inspecciona esquemas de archivos locales, ejecuta una sentencia y devuelve JSON acotado sin GUI ni servidor.

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

Para una visión general orientada a tareas, consulta [SQL para agentes de IA sobre datos locales](https://ducklocal.app/use-cases/ai-agent-sql/). Esta página es la referencia completa de comandos y salida.

## Ejecuta sin ventana

`ducklocal --help` lista diez subcomandos:

| Comando | Qué hace |
| --- | --- |
| `ducklocal query` | Ejecuta una sentencia SQL e imprime el resultado como JSON |
| `ducklocal schema` | Lista qué se puede consultar, con sus columnas; `--stats` para las estadísticas de columnas de una relación |
| `ducklocal open` | Muestra SQL, un panel o datos en la ventana en ejecución; `--state` vuelve a leer lo que muestra |
| `ducklocal check` | Valida un panel `.dash` |
| `ducklocal metrics` | Lista las métricas de un modelo semántico; `compile` o `query` para compilarlas o consultarlas |
| `ducklocal comments` | Lee y responde los comentarios de revisión que la gente dejó en un panel |
| `ducklocal propose` | Propone un cambio en un panel para que la persona lo revise y lo aplique |
| `ducklocal project` | Comprueba una carpeta de análisis portátil y lo que necesita; `relink` arregla rutas movidas |
| `ducklocal session` | Vuelve a leer cómo llegó un análisis adonde llegó |
| `ducklocal presence` | Muestra quién está trabajando en un panel abierto y dónde caerá una edición |

`ducklocal lsp`, el servidor de lenguaje que los editores lanzan para archivos `.dash`, y `ducklocal profile`, el alias heredado de `schema --stats`, siguen funcionando, pero se omiten de `--help`.

`propose`, `project` y `session`, y las opciones `--restricted`, `--wait` y `--if-revision`, llegaron en 0.4.0 y se tratan en [Flujos de trabajo de agentes](agent-workflows.md). `metrics` y `--format html` son posteriores a 0.4.1: están en la rama `main` y llegarán con la próxima versión. `metrics` se trata en [Métricas semánticas](metrics.md).

`ducklocal query` ejecuta SQL sin inicializar la GUI, el historial, los archivos registrados, los ajustes de idioma ni la conexión global de la GUI. Cada invocación crea una conexión dedicada. Invocar DuckLocal sin comandos —o solo con rutas de archivo, carpetas y patrones glob— abre la GUI normal. Para abrir en la GUI una ruta cuyo nombre coincide con un comando (`query`, `schema`, `open`, `check`, `metrics`, `comments`, `propose`, `project`, `session`, `presence`, `profile` o `lsp`), antepón `./`, por ejemplo `./query`.

## Obtén el comando {#get-the-command}

DuckLocal admite macOS 12+ en Apple silicon, Windows (x86_64) y Linux (x86_64). La CLI se ejecuta directamente desde el ejecutable de la aplicación, así que no necesitas instalar un binario de la CLI de DuckDB aparte.

La forma más rápida de tenerlo en tu PATH es desde la app (0.1.1 y posteriores): abre **Línea de comandos e IA…** —el botón del robot de la barra de título, o el menú de DuckLocal— y haz clic en **Instalar comando**. Ese mismo diálogo instala la habilidad para agentes de IA; consulta [Instala la habilidad oficial](#install-the-official-skill). Si te saltas la instalación, llama al ejecutable donde está:

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

Desde un checkout del código, `cargo build --locked` compila `./target/debug/ducklocal`. Los ejemplos de aquí abajo dan por hecho que `ducklocal` está en tu PATH. Las versiones antiguas puede que no tengan `query`; comprueba `--help` primero. La compatibilidad con JSON y Parquet viene incluida, no se descarga en el momento de la consulta.

## Opciones de 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"
```

- Se requiere exactamente uno de `--sql SQL` y `--sql-file FILE`. Los archivos deben ser UTF-8; `-` lee de stdin. El SQL debe contener exactamente una sentencia. El analizador de DuckDB lo valida antes de abrir la base de datos de destino o de ejecutar nada; los comentarios, los puntos y coma entre comillas y el punto y coma final funcionan. Los scripts se rechazan, no se ejecutan a medias.
- `--database PATH` abre un **archivo existente, de solo lectura de forma predeterminada**. Omítelo para una base de datos en memoria nueva. `--read-write` requiere `--database` y permite explícitamente escribir y crear una base de datos (no las carpetas superiores). Los errores de base de datos nunca recurren a la memoria. Cuando DuckDB rechaza un archivo, el mensaje de error empieza por el motivo que DuckLocal lee de la cabecera del archivo —escrito por una DuckDB más nueva, un archivo de la época de la v0.9, un archivo SQLite o algo que no es una base de datos— y por lo que hay que ejecutar en su lugar (para un archivo más nuevo, la copia con `ATTACH … (STORAGE_VERSION)` / `COPY FROM DATABASE` que hay que hacer en esa versión; para SQLite, el `ATTACH` que lo lee), por delante del mensaje propio de DuckDB.
- `--limit N` es un entero positivo, vale 1000 por defecto y limita las filas devueltas. También se aplica un presupuesto de 2.000.000 de celdas. Después del límite, la CLI sigue contando hasta 100.000 filas más sin codificar sus valores, e informa de `total_rows` y `total_rows_exact`. Esto limita la salida, no el cálculo ni la memoria: la ordenación y las agregaciones pueden seguir procesando toda la entrada. Un error de ejecución que aparezca después del límite de salida sigue haciendo fallar el comando.
- `--format json` (el valor predeterminado) es el contrato que hay más abajo. `--format md` representa el mismo resultado como una tabla Markdown, para un documento o para un agente que lo lea. `--format html` lo representa como una única página web autónoma; consulta [Salida HTML](#html-output). Nada más cambia: el mismo SQL, los mismos límites, los mismos errores.
- Las flags repetidas o desconocidas, los valores que faltan, el SQL vacío y los límites no válidos son errores. Las opciones usan valores separados, no `--flag=value`. Las rutas relativas se resuelven contra el directorio de trabajo del proceso, no contra el del archivo SQL. Pon comillas en las rutas del shell; dentro del SQL, duplica los apóstrofos (`'O''Brien.csv'`). Los identificadores SQL usan comillas dobles.

**Solo lectura no es una sandbox de sistema de archivos ni de red.** SQL como `COPY` puede escribir archivos incluso cuando la base de datos es de solo lectura. Autoriza las rutas de salida, las sobrescrituras, las mutaciones de la base de datos, la instalación de extensiones y el acceso externo antes de ejecutar. DuckLocal no instala extensiones automáticamente ni reintenta operaciones. El SQL explícito `INSTALL`/`LOAD` sigue siendo posible con autorización; las extensiones instaladas pueden cargarse solas. Un comando que falla puede haber causado ya efectos secundarios (por ejemplo, antes de un fallo de salida); inspecciona el destino antes de reintentar.

### Salida Markdown

`--format md` es una representación, no un segundo contrato: los valores son los que contiene el JSON, escritos como los muestra la cuadrícula de resultados.

| Valor | Se representa como |
| --- | --- |
| `NULL` | `NULL` |
| entero, decimal, float | los dígitos que lleva el valor, exactamente — un `DECIMAL(38,10)` conserva su escala, `NaN`/`inf`/`-inf` se escriben tal cual |
| `DATE` | `YYYY-MM-DD` |
| `TIMESTAMP` | `YYYY-MM-DD HH:MM:SS[.fffffffff]`, con la fracción solo cuando el valor la tiene, y con tantos dígitos como tenga. No se añade zona horaria; `--format json` conserva el recuento en bruto |
| `TIME` | `HH:MM:SS[.ffffff]` |
| `INTERVAL` | como lo escribe DuckDB: `1 month 2 days 00:00:00.000003` |
| `BLOB`, `GEOMETRY` | `0x00ff`, elidido con `…` cuando es largo |
| `LIST`, `STRUCT`, `MAP` | `[1, 2]`, `{x: 1}`, elidido con `…` a partir de 120 caracteres |

Un `|` en una celda se escapa y un salto de línea pasa a ser `<br>`, así que un valor no puede romper la tabla en la que está. A un resultado sin filas le sigue `_0 rows._`, y a un resultado que `--limit` o el presupuesto de celdas cortaron, `_Truncated at 2 of 5000 rows, so this is not the whole answer._` (`of at least …` cuando pasó del recuento de 100.000 filas): una previsualización no debería leerse como una respuesta completa. Los errores no cambian: JSON en stderr, stdout vacío.

### Salida HTML {#html-output}

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

`--format html` escribe los mismos valores que `--format md` como una sola página web:

- El número de filas y columnas, el tiempo transcurrido y el SQL detrás del resultado, plegado.
- Los nombres de las columnas con sus tipos. Los números se alinean a la derecha y los `NULL` se marcan.
- Haz clic en un encabezado para ordenar; los `NULL` quedan al final. Escribe en el cuadro de filtro para quedarte solo con las filas que coinciden.
- Un resultado recortado por `--limit` o por el presupuesto de celdas lo indica, como en Markdown.

El estilo y el script van incrustados y la página no descarga nada, así que se abre desde el disco y se puede publicar tal cual, por ejemplo en GitHub Pages. Cada celda se escapa como HTML.

## Mapea qué se puede consultar {#map-what-can-be-queried}

`ducklocal schema` responde a «¿qué hay y cuáles son sus columnas?» en una sola llamada, mientras que `DESCRIBE` lo responde relación a relación. Es lo primero que debería ejecutar un agente.

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

Las rutas PATH se expanden como cuando arrastras algo a la ventana: los archivos de datos de una carpeta de forma recursiva (se omiten los ocultos, como máximo 256), las coincidencias de un glob y un archivo de base de datos como si se diera con `--database`. Vuelve un único objeto 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 | Significado |
| --- | --- |
| `name` | La ruta de un archivo tal como se dio (relativa al directorio de trabajo cuando está dentro de él), o el nombre de una tabla tal como lo alcanza el SQL en esta conexión: sin calificar en el esquema predeterminado, `schema.table` en otro caso |
| `kind` | `file`, `glob`, `table`, `view` o `workbook` |
| `from` | El SQL que lo lee, listo para seguir a `FROM`: una ruta entre comillas, o un identificador entre comillas cuando hace falta |
| `rows` | La estimación del catálogo para una tabla, exacta para Parquet (desde su footer), `null` donde saberlo exigiría un escaneo: CSV, JSON, vistas |
| `column_count`, `columns` | Las columnas tal como las describe DuckDB |
| `files` | Para un `glob`: cuántos archivos coinciden |

Un glob cuyas coincidencias son todas de un mismo formato es una sola relación, leída como la lee un `source` de `.dash` (`ducklocal schema 'logs/*.csv'`); `--stats` la perfila como una. Un glob con formatos mezclados, y una carpeta, listan sus archivos uno a uno.

Un catálogo pequeño vuelve entero (`"detail": "full"`). A partir de 12 relaciones o 400 columnas es un **resumen** (`"detail": "summary"`). Las 5 relaciones con más filas conservan sus columnas; el resto lista nombre, tipo, filas y número de columnas, y `without_columns` las cuenta. Para obtener más, `hint` nombra las dos maneras: `--table NAME` para una relación (buscada por su nombre, por su nombre de tabla sin calificar o por el nombre de un archivo) y `--full` para todas. Un libro se lista con sus `sheets` y sin columnas, ya que no tiene función de tabla; `--stats` lee su primera hoja. Una ruta PATH que no existe, o un `--table` que no nombra nada, sale con código 2.

El texto con gzip como `.json.gz` y `.csv.gz` es aquí un archivo de datos, igual que lo es para los bloques `source` y para la ventana. Un archivo cuyos registros están en una sola lista —el `{"Records": [...]}` de CloudTrail, por ejemplo— vuelve con un `hint`: el SQL que lee esos registros como filas, ya que de otro modo la única fila y la única columna describen solo el envoltorio.

## Explora y convierte archivos

Después de confirmar que el archivo real existe:

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

No des por hecho que `amount` existe: ejecuta `ducklocal schema` o `DESCRIBE` primero. Calcula las agregaciones completas en SQL en lugar de sumar una previsualización truncada. Las llamadas de la CLI no comparten las vistas registradas de la GUI ni las tablas en memoria de otras llamadas. Persiste de forma explícita cuando haga falta:

```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 conflicto de bloqueo de la base de datos es un error. Cierra el otro escritor (incluida la GUI) o usa una copia autorizada; nunca borres archivos de bloqueo ni crees en silencio una base de datos distinta.

## JSONL y JSON anidado {#jsonl-and-nested-json}

`read_ndjson_objects` es el lector para JSON delimitado por saltos de línea (un objeto por línea, `.jsonl`/`.ndjson`); `read_json`/`read_json_auto` leen documentos JSON (un array o un único objeto). Nombra el lector de forma explícita para un archivo JSONL en lugar de confiar en la detección automática. `json_extract_string(col, '$.a.b[0].c')` recorre una ruta anidada —claves de objeto e índices de array— y devuelve 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 `json_extract` en su lugar cuando la hoja no sea una cadena y la quieras como JSON.

## Estadísticas de columnas

`ducklocal schema --stats` responde a las preguntas que deciden un gráfico, una escala y un formato de número, antes de construir nada sobre ellas. `DESCRIBE` dice que una columna es `DOUBLE`; sus estadísticas dicen que usa dos decimales, que su valor mayor es mil veces su mediana y que sus fechas se saltan once días en medio.

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

`--stats` perfila una sola relación: la única que nombran los argumentos, o la que elige `--table` —dos o más sin `--table` es código 2, con un hint que lo dice—. No se puede combinar con `--full`. `ducklocal profile TARGET [--database PATH]`, de versiones anteriores, es el mismo informe y sigue funcionando.

La relación es un archivo de datos —`csv`, `tsv`, `txt`, `parquet`, `json`, `ndjson`, `jsonl`—, un libro (`xlsx`, `xls`, `xlsb`, `ods`; su primera hoja se importa como tabla TEMP y se perfila) o, con `--database`, el nombre de una tabla o vista. Un nombre con puntos se lee como `schema.table` y cada parte va entre comillas, así que un nombre con un espacio o una mayúscula funciona tal como se escribe. Una relación que no nombra nada es un error de argumentos (código 2), no uno de SQL.

Vuelve un único objeto JSON: `target`, `relation` (el SQL sobre el que se ejecutaron las estadísticas), `row_count`, `elapsed_ms` y `columns` en el orden propio de la relación. Por columna:

| Campo | Significado |
| --- | --- |
| `name`, `type` | tal como los informa `DESCRIBE` |
| `nulls` | filas en las que la columna es `NULL` |
| `distinct` | exacto, no estimado |
| `unique` | presente y `true` cuando `distinct` es igual a `row_count` |
| `min`, `max` | como texto, para que un `DECIMAL` conserve sus dígitos |
| `decimals` | dígitos después del punto que la columna **usa realmente**, que no es su escala declarada |
| `median` | un valor que la columna contiene, no una interpolación entre dos de ellos |
| `max_over_median` | cuántas veces el valor mayor es más grande que la mediana: el número que decide un eje lineal frente a uno logarítmico |
| `covered_days`, `span_days`, `missing_days` | días que nombra la columna, días entre sus extremos y la diferencia: `0` es una serie continua, cualquier otra cosa son huecos que una línea dibujaría por encima |

`decimals`, `median` y `max_over_median` aparecen en las columnas numéricas; los campos de días, en fechas y timestamps. Las columnas `LIST`, `STRUCT`, `MAP` y `UNION` solo informan de `nulls`: `min` y `max` no están definidos en ellas.

Una columna de texto que contiene números y una palabra corta, como el `NA` de R, informa además de `null_marker` y `null_marker_rows`. El informe añade entonces un `hint` que nombra la llamada a `read_csv` que lee la columna como números.

Las estadísticas son exactas y leen toda la relación, así que cuestan un escaneo completo. `--limit` no se aplica: el perfil de una muestra no es un perfil.

## Muestra el trabajo en la ventana en ejecución {#show-work-in-the-running-window}

`ducklocal open` entrega algo a la ventana de DuckLocal que ya está en ejecución —y la inicia si no hay ninguna— y la trae al frente. Es cómo un agente pone su trabajo delante de una persona, para que pueda seguir desde ahí:

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

- Las rutas PATH se abren como cuando arrastras algo a la ventana: un archivo `.dash` como pestaña, un archivo de base de datos DuckDB como base de datos de la ventana, y archivos de datos, carpetas y globs adjuntos como vistas. Las rutas PATH relativas se resuelven contra el directorio del comando. Una petición que llega mientras la ventana aún está arrancando espera a que termine su apertura de inicio.
- `--sql` o `--sql-file` (`-` lee de stdin) abre una pestaña de consulta nueva, titulada `--title`. `--run` la ejecuta una vez que las rutas PATH se han adjuntado.
- `--no-launch` falla con kind `not_running` en lugar de iniciar una ventana, para una máquina donde una ventana que aparece sin pedirla no sería bien recibida.

El éxito imprime `{"delivered": true, "launched": BOOL}`: la entrega, no un resultado. Lo que se abre se ejecuta en la sesión propia de la ventana —su conexión, sus vistas adjuntas, su historial— y cualquier error aparece allí, no en stdout. Código 2 para los argumentos; 1 con kind `not_running` (no se alcanza ninguna ventana), `refused` (la ventana rechazó la petición) o `launch`.

La ventana escucha en un puerto de loopback. Escribe el puerto y un token aleatorio en un archivo que solo tu cuenta puede leer (consulta [Ajustes y datos de la app](settings-and-data.md#where-things-are-stored)); otro usuario de la máquina, o una página web que apunte a localhost, no puede alcanzarla.

### Lee lo que muestra la ventana

`ducklocal open --state` va en la otra dirección: no abre nada, nunca inicia una ventana e imprime lo que muestra la ventana en ejecución, para que un agente pueda retomar donde lo dejó una persona en lugar de pedirle que pegue su consulta.

```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` es el archivo de base de datos abierto, o `":memory:"`; `attached` lista los archivos que la ventana registró como vistas, con el `name` de la vista. Una consulta de la CLI no puede leer esas vistas: usa el `path`.
- Una pestaña de **consulta** tiene `sql`, el texto del editor se haya ejecutado o no, y `result`: `status` es `empty`, `running`, `rows`, `affected`, `failed`, `explain` o `profile`. Para filas: `columns`, `row_count`, `truncated`, `preview` (las primeras 20 filas tal como las muestra la cuadrícula, como cadenas), `elapsed_ms` y el `sql` que las produjo; para `affected`, `count` y `elapsed_ms`; para un fallo, `error`.
- Una vez que la persona ha elegido columnas en la pestaña Gráfico, un resultado tiene además `chart`: `type`, `x`, `y`, `split` y `dash`, un bloque `query` y otro `plot` que dibujan el mismo gráfico en un panel.
- `explain` es lo que muestra **Explain**: `plan`, la salida de `EXPLAIN` de DuckDB como un array de líneas de texto, y `elapsed_ms`.
- `profile` es lo que muestra **Perfil** (consulta [Editor SQL](sql-editor.md)): `plan`, el árbol de operadores que midió `EXPLAIN ANALYZE`, como un array de raíces, cada una `{operator, seconds, rows, estimated, children}` — `seconds` es el tiempo propio del operador sin sus hijos, `rows` lo que produjo, `estimated` la estimación del optimizador para `rows` (`null` donde el plan no indica ninguna) y `children` la misma forma otra vez. `operator_seconds` es la suma del tiempo propio de cada operador, que es a lo que suman las partes, no el tiempo de reloj; `elapsed_ms` es la ejecución completa.
- Una pestaña de **panel** tiene `path`, `unsaved` y `dashboard`: la ruta de su `comments_file`, sus `plots` (nombre, tipo, título, consulta, filas, `open_comments` y `failure` cuando uno no puede dibujar) y sus `filters` con lo que ha elegido cada uno: `picked`, `value` (el primer valor), `values` (todos los valores elegidos, en orden) y `multiple`. `value: null` con `picked: true` significa que se eligió el valor NULL.

Usa `--state sales.dash` para quedarte solo con las pestañas que muestran ese panel, o `--state --active` para solo la pestaña activa. Una ruta que no está abierta devuelve código 1, kind `not_open`, con los paneles abiertos en el hint. `active_tab` es el índice de la pestaña activa dentro de las `tabs` devueltas, o `null` si no está entre ellas; `database` y `attached` se siguen incluyendo.

`--state` acepta una ruta `.dash` o `--active`, no ambas. `--no-launch` se acepta y no cambia nada. Otras opciones, incluidas `--sql` y `--run`, no son válidas (código 2). Código 1 con kind `not_running` cuando no hay ninguna ventana en marcha, y `timeout` cuando no responde en 5 segundos.

## Comprueba una especificación de panel {#check-a-dashboard-spec}

El formato en sí —bloques, atributos, tipos de gráfico, reglas de SQL y mensajes habituales— se describe en [Paneles (.dash)](dashboards.md); esta sección cubre el comando.

Un archivo `.dash` declara un panel como Terraform declara infraestructura —consultas y gráficos como bloques, referencias entre ellos— en lugar de programarlo. Es fácil de escribir y de comparar con diff, tanto para una persona como para 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 bloque `source` nombra archivos de datos, relativos al archivo `.dash`, para que los lean las consultas, y un bloque `view` contiene SQL que comparten varias consultas. Un bloque `query` contiene un atributo `sql` —una sentencia de solo lectura, como heredoc o como cadena—. Se aceptan `SELECT`, `WITH`, los que empiezan por `FROM`, `VALUES`, `SHOW`, `DESCRIBE`, `SUMMARIZE` y `PIVOT`; cualquier cosa que pueda escribir —DDL, DML, `COPY`, `ATTACH`, `INSTALL`— es un diagnóstico, y la GUI se niega a ejecutarla, porque las consultas de un panel se ejecutan cada vez que se abre el archivo. Un bloque `plot` contiene `type` (uno de `line`, `bar`, `stacked_bar`, `area`, `scatter`, `pie`, `heatmap`, `histogram`, `map`, `timeline`, `table`, `card`, `text`), `query` (una referencia como `query.latency` a un bloque de consulta del mismo archivo), sus columnas y, opcionalmente, `title` y `width`. Un bloque `filter` hace que un gráfico de barras o una tabla sean clicables —un valor, o varios con `multiple = true` en una barra— y una consulta lee la elección como `$name`. `#` y `//` comentan hasta el final de la línea. [Paneles (.dash)](dashboards.md) tiene todos los atributos.

Un gráfico `text` es la excepción: contiene `title`, `text` o ambos y no acepta `query`. Las tarjetas también pueden usar `note` y `tone`; consulta [Tarjetas y paneles de texto](dashboards.md#cards-and-text-panels).

Primero las comprobaciones estáticas: el SQL de cada consulta pasa por el analizador real de DuckDB en una conexión desechable, como lo valida `query` antes de ejecutar, y cada `$name` se contrasta con los bloques `filter`: el SQL se analiza y se ejecuta con cada `$name` como `TRUE`, que es lo que ejecuta el panel antes de que se elija nada.

Después se ejecuta cada consulta, exactamente como la ejecutaría abrir el panel —de solo lectura, con sus fuentes, por el mismo código y con el mismo presupuesto de filas—, y las columnas de cada gráfico se comprueban contra las columnas que la consulta devuelve realmente: un `y` que no es numérico es un error para cualquier tipo de gráfico, y también lo son las coordenadas no numéricas de un mapa o su `size`, y una `column` de filtro que la consulta de su gráfico no devuelve.

- **Sin `--database`** las consultas se ejecutan en memoria, que es todo lo que necesita un panel sobre sus propios archivos `source`. Una consulta que lee una tabla que ninguna fuente define puede estar pensada para una base de datos que no se le pasó a la comprobación: se lista en `unresolved` (consulta, línea, motivo) en lugar de fallar, y las columnas de sus gráficos no se comprueban.
- **Con `--database PATH`** (archivo existente, de solo lectura) se ejecutan sobre esa base de datos. Pásala siempre que las consultas lean tablas de una base de datos: todo lo que quede en `unresolved` no se comprobó.

Toda consulta que lee un filtro se vincula además con un valor elegido, sin ejecutar esa variante. Así se detecta una columna de filtro que falta en una consulta consumidora, incluso cuando la versión inicial con `$name = TRUE` funciona. Un filtro también debe referenciar una columna que devuelva su gráfico selector.

Ejecutar y no solo planificar importa: algunos fallos, como un cast que la compilación no puede hacer o un valor que no se convertirá, aparecen solo cuando se leen filas, y una comprobación que los dejara pasar entregaría un panel que no puede dibujar. Las consultas se ejecutan enteras, así que una comprobación contra una base de datos grande tarda lo mismo que abrir el panel.

El éxito es un único objeto JSON que lista las fuentes del archivo (con su ruta `resolved`), las vistas, las consultas (con sus columnas de resultado y `rows`, cuántas devolvió cada una sin nada elegido, además de `truncated: true` cuando el presupuesto de filas del panel la cortó), los filtros (con las `queries` que lee cada uno), los gráficos, `unresolved` y `empty`: las consultas que se ejecutaron y no devolvieron filas. Una consulta vacía pasa todas las demás comprobaciones, pero normalmente es una regex, un filtro o un join que no encontró nada, así que revísalas una a una. Con `--summary`, el éxito es una línea JSON compacta:

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

Los cinco campos de bloque son recuentos; `unresolved` lista las consultas que no se pudieron comprobar y `empty` las que no devolvieron filas.

Un bloque defectuoso se omite mientras los bloques válidos siguen por la validación. Los errores de especificación y los fallos de consulta se reúnen en la misma ejecución, uno `file:line: message` cada uno. Si hay algún diagnóstico de especificación, la salida es 2 con kind `spec`; si solo falla la ejecución o el vínculo de SQL, es 1 con kind `sql`. Los fallos de base de datos y de E/S también salen con 1. `--summary` no oculta los diagnósticos.

El mismo archivo se abre como pestaña de panel en la GUI — `ducklocal dashboard.dash`, `ducklocal open dashboard.dash`, o arrástralo a la ventana — con los gráficos en una cuadrícula de 12 columnas y un gráfico que no puede dibujar mostrando el motivo en línea. Consulta [Paneles (.dash)](dashboards.md).

## Métricas de un modelo semántico {#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` lee un modelo de Apache Ossie, `model.ossie.yaml`, y lista sus métricas y campos. `compile` imprime el único `SELECT` de DuckDB que responde a una petición, sin leer datos; `query` lo ejecuta como lo hace `ducklocal query`, con un objeto `semantic` que indica el SQL y el `sha256` del modelo. Una petición que el modelo no puede responder con exactitud se rechaza, con código de salida 2 y un `kind` como `metric_fanout`. [Métricas semánticas](metrics.md) describe el formato del modelo, cada opción y cada rechazo.

## Revisa los comentarios de un panel {#review-comments-on-a-dashboard}

La gente revisa un panel comentando sus gráficos en la ventana: pasa el cursor por un gráfico y haz clic en la burbuja de diálogo (consulta [Revisar con comentarios](dashboards.md#review-with-comments)). `ducklocal comments` es el lado del agente: lee los hilos y los responde, sin ventana.

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

- Sin ninguna acción, imprime los hilos abiertos: `{file, comments_file, open, threads}`. `--all` incluye los resueltos.
- Cada hilo tiene `id`, `plot` y lo que el agente necesita para encontrarlo en la especificación: `plot_title`, `plot_query` y `plot_lines`, la primera y la última línea del bloque `plot` (`null` cuando la especificación no se analiza). `plot_missing` es `true` cuando ya no queda ningún gráfico con ese nombre. Luego `resolved` y `comments`, cada uno con `author` (`user` o `agent`), en un comentario de agente su `name` (el nombre que muestra [`presence`](#agent-presence)), `text` y `at` (RFC 3339, hora local).
- `--reply ID --text TEXT` añade la respuesta del agente. Una respuesta a un hilo resuelto lo reabre, a menos que se dé también `--resolve`.
- `--resolve ID` y `--reopen ID` cambian el estado de un hilo; `--add PLOT --text TEXT` inicia un hilo, firmado como el agente.
- El número de un hilo sirve como su ID: `--reply 1` significa `c1`. `--add` rechaza un gráfico que la especificación no tiene (código 2), y el hint lista sus gráficos.
- Una acción imprime `{thread}`, tal como quedó.

Los hilos se guardan junto a la especificación, en `FILE.comments.json`. Una ventana en ejecución nota un cambio en menos de un segundo y lo muestra en el gráfico. Un id de hilo desconocido es código 2, con un hint para listar los hilos; un archivo de especificación que no existe es código 1.

Una revisión, de principio a fin: lee los hilos abiertos, edita la especificación, ejecuta `ducklocal check` y luego responde a cada hilo con lo que cambió y `--resolve`. Usa `--reply` sin `--resolve` para preguntarle algo a la persona.

## Muestra la actividad del agente {#agent-presence}

`check` y `comments` avisan automáticamente a una ventana en ejecución de en qué panel está trabajando el agente. `presence` puede anunciar una edición antes de que ocurra:

```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` acepta `reading`, `editing` o `idle` (`done` es un alias de `idle`).
- `--plot` toma nombres de gráfico separados por comas. Con `editing`, se permiten nombres nuevos y aparecen como marcadores de posición. Con `reading` o `idle`, un nombre desconocido es código 2.
- El nombre que se muestra viene de `--agent`, luego de `DUCKLOCAL_AGENT`, luego del entorno de agente detectado (Claude, Codex, Cursor o Gemini), y si no, de `Agent`.
- La salida es `{delivered}`. Sin una ventana en ejecución produce `{"delivered":false}` sin error y sin iniciar ninguna ventana.

El nombre se queda en la esquina del panel mientras los comandos mantienen la sesión activa. Haz clic en él para ver el registro de actividad. Treinta segundos de silencio o `--doing idle` terminan la sesión; los gráficos modificados y añadidos siguen marcados hasta que se ven, y los avisos de gráficos eliminados, hasta que se descartan. Consulta [Ver a un agente trabajar](dashboards.md#agent-presence).

## Edita una especificación de panel con LSP {#edit-a-dashboard-spec-with-lsp}

`ducklocal lsp` es un servidor del Protocolo de Servidor de Lenguaje para archivos `.dash`, sobre stdio, para que lo lancen los editores. Da a cualquier editor compatible con LSP lo mismo que tiene el editor de especificaciones de la GUI:

- **Diagnósticos**: los que informa `check`, publicados en cada apertura y cada cambio (sincronización de documento completo, todos con severidad Error: son errores, no estilo).
- **Autocompletado**: tipos de bloque, nombres de atributo, tipos de gráfico y los nombres tras `query.` y `plot.`, cada uno con una edición de texto que sustituye la palabra que se está escribiendo.
- **Hover**: documentación de bloques, atributos y referencias.
- **Ir a la definición**: desde una referencia `query.name` o `plot.name` hasta el nombre de su bloque.

Con `--database PATH`, el SQL de cada consulta se valida además con el analizador real de DuckDB, como hace `check --database`.

Apunta el soporte LSP genérico de tu editor a `ducklocal lsp` para archivos `*.dash`: el comando no toma argumentos de documento; el editor habla con él por stdio. En 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,
})
```

En VS Code, cualquier extensión de LSP genérico hace lo mismo con el comando `ducklocal`, los argumentos `["lsp"]` y el selector de documento `dash`. Códigos de salida: **0** tras un `shutdown`/`exit` limpio, **1** cuando el cliente se va sin hacerlo, **2** para una línea de comandos incorrecta o un handshake de protocolo fallido.

## Contrato JSON

Las consultas correctas escriben exactamente un objeto JSON en stdout, seguido de un salto de línea:

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

`columns` y cada fila conservan el orden de las columnas y los nombres duplicados. `type` es la **representación de depuración de Arrow**, no el nombre de tipo SQL original de DuckDB (por ejemplo, HUGEINT y DECIMAL pueden compartir un portador de Arrow). `row_count` cuenta las filas devueltas. `total_rows` cuenta las filas producidas, incluidas las contadas después del límite de salida; `total_rows_exact: false` significa que el recuento se detuvo tras hasta 100.000 filas adicionales, así que ese total es un límite inferior. Ninguno de los dos recuentos es un recuento de filas afectadas. `elapsed_ms` mide la preparación, la ejecución y la codificación de filas, no la carga de archivos ni la creación de la conexión. Los resultados con cero filas conservan los metadatos. DDL/DML exponen el resultado real de DuckDB, incluidas las columnas `Count`: INSERT/COPY suelen devolver `[[N]]`; CREATE TABLE normalmente no devuelve filas. No se clasifican a partir de la primera palabra clave del SQL.

Codificación de las celdas:

| Valor SQL | Codificación JSON |
| --- | --- |
| NULL | `null` (nunca la cadena `"NULL"`) |
| Booleano, float finito | booleano o número JSON |
| Entero dentro de ±9.007.199.254.740.991 | número JSON |
| Entero mayor, incluidos HUGEINT/UHUGEINT | `{"encoding":"integer","value":"9007199254740992"}` |
| Decimal | `{"encoding":"decimal","value":"123.450"}` con el texto decimal exacto |
| Texto, enum | cadena JSON |
| Blob, geometry | `{"encoding":"hex","value":"00ff"}`; bytes en minúsculas, geometry usa WKB |
| Date | `{"encoding":"date","unit":"Day","value":"1","iso":"1970-01-02"}`; días desde 1970-01-01 |
| Timestamp | `{"encoding":"timestamp","unit":"Nanosecond","value":"123456789","iso":"1970-01-01T00:00:00.123456789"}`; recuento con signo desde la época Unix; la unidad también puede ser Second/Millisecond/Microsecond |
| Time | `{"encoding":"time","unit":"Microsecond","value":"123456","iso":"00:00:00.123456"}`; recuento desde medianoche |
| Interval | `{"encoding":"interval","months":1,"days":2,"nanos":"3000"}` |
| NaN, infinito positivo o negativo | `{"encoding":"float","value":"NaN"}` / `"inf"` / `"-inf"` |
| List, array | array JSON, codificado de forma recursiva (incluidos los null anidados) |
| Struct | `{"encoding":"struct","fields":[["name",VALUE],...]}` |
| Map | `{"encoding":"map","entries":[[KEY,VALUE],...]}`; no es un objeto JSON, así que las claves conservan sus tipos |
| Union | `{"encoding":"union-value","value":VALUE}`; solo el valor activo, la etiqueta de miembro no se conserva |

Los `value` temporales son recuentos exactos, así que no se pierde precisión fraccionaria; los centinelas de infinito de fecha y timestamp siguen siendo recuentos en bruto. Junto a cada uno, `iso` es el mismo valor como texto ISO 8601 para leerlo, con tantos dígitos de fracción como admite la unidad. Un timestamp de una columna con zona horaria (metadatos de Arrow) es un instante UTC, y su `iso` termina en `Z`. `--format md` también representa fechas y timestamps de forma legible. Como el envoltorio de Arrow de DuckDB que está fijado no puede distinguir HUGEINT, UHUGEINT y DECIMAL(38,0) anidados, las apariciones no nulas producen un error claro en lugar de cambiar el signo o la precisión en silencio. Convierte esos campos explícitamente a VARCHAR en SQL. Los tipos no admitidos desconocidos también producen un error; no confundas un error con un resultado vacío. La codificación de union es una representación del valor activo, no un viaje de ida y vuelta sin pérdidas de una union.

Los errores escriben un objeto JSON en **stderr**, dejando stdout vacío:

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

`hint` está cuando se conoce el paso siguiente, en los términos de esta CLI: la flag que se quería escribir, `--read-write` para una escritura rechazada en una base de datos de solo lectura, `ducklocal schema` para una tabla que no existe, `TRY_CAST` para un valor que no se convertirá, dividir un script que tiene más de una sentencia, o `AS` para una palabra clave usada como alias de columna sin calificar (`SELECT count(*) AS minutes`, o ponlo entre comillas). Un agente debería actuar según él antes de reescribir el SQL. Falta cuando no hay nada que añadir al mensaje propio de DuckDB, como en un error de sintaxis.

Códigos de salida: **0** éxito, **2** argumentos o número de sentencias no válidos, **1** fallo de SQL, base de datos, E/S o salida. Los kinds de error son `argument`, `sql`, `database`, `io`, `output`, `spec` para `check`, y `not_running`, `not_open`, `refused`, `timeout` o `launch` para `open`. Comprueba el estado de salida antes de analizar stdout e inspecciona `truncated` antes de informar de que algo está completo. La ayuda y la versión son excepciones en texto plano. Los fallos de transporte, como un pipe de stdout cerrado, no pueden garantizar un flujo de salida vacío ni completo.

## Instala la habilidad oficial {#install-the-official-skill}

La habilidad enseña al agente los hábitos que mantienen honestas sus respuestas: inspeccionar el esquema, previsualizar una muestra acotada, calcular las agregaciones en SQL, comprobar `truncated` y responder a partir de los valores devueltos. Cubre la inspección de esquemas, las estadísticas de columnas, las conversiones, las consultas a bases de datos, los paneles `.dash` y sus comentarios de revisión, y entregar trabajo a la ventana y volver a leerlo; no ofrece navegación por S3, comandos específicos de datos espaciales, memoria de sesión ni un servidor MCP.

**Desde la app.** Abre **Línea de comandos e IA…** (el botón del robot de la barra de título, o el menú de DuckLocal):

- **Instalar comando** pone `ducklocal` en tu `PATH`, para que el shell de un agente pueda ejecutarlo.
- **Añadir a Claude Code** escribe la habilidad en `~/.claude/skills/ducklocal`, donde Claude Code la encuentra en todos los proyectos. Solo se escriben los dos archivos propios de la habilidad; cualquier otra cosa en esa carpeta se conserva. Cuando una actualización de DuckLocal trae una habilidad más nueva, el diálogo ofrece **Actualizar habilidad**.
- **Copiar resumen** copia una explicación breve para cualquier otro agente —Codex, Cursor, una ventana de chat—, con el nombre del comando y cómo usarlo.

**A mano.** La habilidad está en [`skills/ducklocal`](https://github.com/JetSquirrel/ducklocal/tree/main/skills/ducklocal). Para añadirla a un solo proyecto en su lugar (ejemplo para 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/
```

Inspecciona primero un destino que ya exista en lugar de sobrescribir cambios locales. Otros agentes pueden usar el mismo `SKILL.md` más `references/cli.md` en el directorio de habilidades que admitan.
