# CLI de IA e skill oficial

> Use a CLI de SQL do DuckDB do DuckLocal com agentes de IA: inspecione esquemas de arquivos locais, execute uma instrução e devolva JSON limitado sem GUI nem servidor.

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

Para a visão geral orientada a tarefas, veja [SQL para agentes de IA sobre dados
locais](https://ducklocal.app/pt/use-cases/ai-agent-sql/). Esta página é a
referência completa de comandos e saída.

## Execute sem janela

`ducklocal --help` lista dez subcomandos:

| Comando | O que faz |
| --- | --- |
| `ducklocal query` | Executa uma instrução SQL e imprime o resultado como JSON |
| `ducklocal schema` | Lista o que há para consultar, com as colunas; `--stats` para as estatísticas de colunas de uma relação |
| `ducklocal open` | Mostra SQL, um painel ou dados na janela em execução; `--state` relê o que ela mostra |
| `ducklocal check` | Valida um painel `.dash` |
| `ducklocal metrics` | Lista as métricas de um modelo semântico; `compile` ou `query` para compilá-las ou consultá-las |
| `ducklocal comments` | Lê e responde os comentários de revisão que as pessoas deixaram em um painel |
| `ducklocal propose` | Sugere uma mudança no painel para a pessoa revisar e aplicar |
| `ducklocal project` | Verifica uma pasta de análise portátil e do que ela precisa; `relink` corrige caminhos movidos |
| `ducklocal session` | Relê como uma análise chegou onde chegou |
| `ducklocal presence` | Mostra quem está trabalhando em um painel aberto e onde uma edição vai cair |

`ducklocal lsp`, o servidor de linguagem que os editores iniciam para arquivos
`.dash`, e `ducklocal profile`, o alias legado de `schema --stats`, ainda
funcionam, mas ficam de fora do `--help`.

`propose`, `project` e `session`, e as opções `--restricted`, `--wait` e
`--if-revision`, chegaram na 0.4.0 e são tratados em
[Fluxos de trabalho de agentes](agent-workflows.md). `metrics` e
`--format html` são mais novos que a 0.4.1: estão no branch `main` e chegam na
próxima versão. `metrics` é tratado em [Métricas semânticas](metrics.md).

`ducklocal query` executa SQL sem inicializar a GUI, o histórico, os arquivos
registrados, as configurações de idioma ou a conexão global da GUI. Cada
invocação cria uma conexão dedicada. Invocar o DuckLocal sem comandos — ou
apenas com caminhos de arquivo, pastas e padrões glob — abre a GUI normal. Para
abrir na GUI um caminho cujo nome coincide com um comando (`query`, `schema`,
`open`, `check`, `metrics`, `comments`, `propose`, `project`, `session`, `presence`,
`profile` ou `lsp`), prefixe-o com `./`, como em `./query`.

## Obtenha o comando {#get-the-command}

O DuckLocal tem suporte a macOS 12+ em Apple silicon, Windows (x86_64) e Linux
(x86_64). A CLI roda direto do executável do aplicativo, então você não precisa
instalar um binário separado da CLI do DuckDB.

O jeito mais rápido de colocá-lo no seu PATH é pelo app (0.1.1 e posteriores):
abra **Linha de comando e IA…** — o botão do robô na barra de título, ou o menu
do DuckLocal — e clique em **Instalar comando**. Esse mesmo diálogo instala a
skill para agentes de IA; veja
[Instale a skill oficial](#install-the-official-skill). Se você pular a
instalação, chame o executável onde ele 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
```

A partir de um checkout do código, `cargo build --locked` compila
`./target/debug/ducklocal`. Os exemplos abaixo partem do princípio de que
`ducklocal` está no seu PATH. Versões mais antigas podem não ter `query`;
verifique `--help` primeiro. O suporte a JSON e Parquet vem incluído, não é
baixado no momento da consulta.

## Opções de consulta {#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"
```

- É obrigatório exatamente um entre `--sql SQL` e `--sql-file FILE`. Os arquivos
  devem ser UTF-8; `-` lê da entrada padrão. O SQL deve conter exatamente uma
  instrução. O parser do DuckDB valida isso antes de abrir o banco de dados de
  destino ou de executar qualquer coisa; comentários, pontos e vírgulas entre
  aspas e o ponto e vírgula final funcionam. Scripts são rejeitados, não
  executados em parte.
- `--database PATH` abre um **arquivo existente, somente leitura por padrão**.
  Omita-o para um banco de dados novo em memória. `--read-write` exige
  `--database` e permite explicitamente escritas e a criação de um banco de
  dados (não das pastas superiores). Erros de banco de dados nunca caem para a
  memória. Quando o DuckDB recusa um arquivo, a mensagem de erro começa pelo
  motivo que o DuckLocal lê do cabeçalho do arquivo — escrito por um DuckDB mais
  novo, um arquivo da época da v0.9, um arquivo SQLite ou algo que não é um banco
  de dados — e pelo que executar em vez disso (para um arquivo mais novo, a
  cópia com `ATTACH … (STORAGE_VERSION)` / `COPY FROM DATABASE` a fazer naquela
  versão; para SQLite, o `ATTACH` que o lê), antes da mensagem do próprio
  DuckDB.
- `--limit N` é um inteiro positivo, tem 1000 como padrão e limita as linhas
  devolvidas. Também se aplica um orçamento de 2.000.000 de células. Depois do
  limite, a CLI continua contando até 100.000 linhas a mais sem codificar seus
  valores, informando `total_rows` e `total_rows_exact`. Isso limita a saída, não
  o cálculo nem a memória: ordenação e agregações ainda podem processar toda a
  entrada. Um erro de execução encontrado depois do limite de saída ainda faz o
  comando falhar.
- `--format json` (o padrão) é o contrato descrito abaixo. `--format md`
  representa o mesmo resultado como uma tabela Markdown, para um documento ou
  para um agente que a leia. `--format html` o representa como uma única página
  web autocontida; veja [Saída HTML](#html-output). Nada mais muda: o mesmo SQL, os mesmos limites, os
  mesmos erros.
- Flags repetidas ou desconhecidas, valores faltando, SQL vazio e limites
  inválidos são erros. As opções usam valores separados, não `--flag=value`.
  Caminhos relativos são resolvidos a partir do diretório de trabalho do
  processo, não do diretório do arquivo SQL. Coloque aspas nos caminhos do shell;
  dentro do SQL, dobre os apóstrofos (`'O''Brien.csv'`). Identificadores SQL usam
  aspas duplas.

**Somente leitura não é uma sandbox de sistema de arquivos nem de rede.** SQL
como `COPY` pode escrever arquivos mesmo quando o banco de dados é somente
leitura. Autorize caminhos de saída, sobrescritas, mutações do banco de dados,
instalação de extensões e acesso externo antes de executar. O DuckLocal não
instala extensões automaticamente nem repete operações. SQL explícito de
`INSTALL`/`LOAD` continua possível com autorização; extensões instaladas podem se
autocarregar. Um comando que falhou pode já ter causado efeitos colaterais (por
exemplo, antes de uma falha de saída); inspecione o destino antes de tentar de
novo.

### Saída em Markdown

`--format md` é uma renderização, não um segundo contrato: os valores são os que
o JSON contém, escritos do jeito que a grade de resultados os mostra.

| Valor | Renderizado como |
| --- | --- |
| `NULL` | `NULL` |
| inteiro, decimal, float | os dígitos que o valor carrega, exatamente — um `DECIMAL(38,10)` mantém sua escala, `NaN`/`inf`/`-inf` são escritos por extenso |
| `DATE` | `YYYY-MM-DD` |
| `TIMESTAMP` | `YYYY-MM-DD HH:MM:SS[.fffffffff]`, com a fração só quando o valor tem uma, e com tantos dígitos quantos ela tiver. Nenhum fuso horário é acrescentado; `--format json` mantém a contagem bruta |
| `TIME` | `HH:MM:SS[.ffffff]` |
| `INTERVAL` | como o DuckDB escreve: `1 month 2 days 00:00:00.000003` |
| `BLOB`, `GEOMETRY` | `0x00ff`, abreviado com `…` quando longo |
| `LIST`, `STRUCT`, `MAP` | `[1, 2]`, `{x: 1}`, abreviado com `…` a partir de 120 caracteres |

Um `|` em uma célula é escapado e uma quebra de linha vira `<br>`, então um valor
não consegue quebrar a tabela em que está. Um resultado sem linhas é seguido por
`_0 rows._`, e um resultado cortado por `--limit` ou pelo orçamento de células
por `_Truncated at 2 of 5000 rows, so this is not the whole answer._`
(`of at least …` depois da contagem de 100.000 linhas) — uma prévia não deveria
soar como uma resposta completa. Os erros não mudam: JSON no stderr, stdout vazio.

### Saída HTML {#html-output}

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

`--format html` escreve os mesmos valores de `--format md` como uma única
página web:

- O número de linhas e colunas, o tempo decorrido e o SQL por trás do
  resultado, recolhido.
- Os nomes das colunas com seus tipos. Números ficam alinhados à direita e os
  `NULL` são marcados.
- Clique em um cabeçalho para ordenar; os `NULL` ficam por último. Digite na
  caixa de filtro para manter só as linhas que correspondem.
- Um resultado cortado por `--limit` ou pelo orçamento de células avisa isso,
  como no Markdown.

O estilo e o script são embutidos e a página não baixa nada, então ela abre do
disco e pode ser publicada como está, por exemplo no GitHub Pages. Cada célula
é escapada para HTML.

## Mapeie o que pode ser consultado {#map-what-can-be-queried}

`ducklocal schema` responde "o que existe e quais são suas colunas?" em uma única
chamada, enquanto `DESCRIBE` responde relação por relação. É a primeira coisa que
um agente deveria executar.

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

Caminhos PATH se expandem como quando você arrasta algo para a janela: os
arquivos de dados de uma pasta recursivamente (os ocultos são ignorados, no
máximo 256), as correspondências de um glob e um arquivo de banco de dados como
se fosse passado com `--database`. Volta um ú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` | O caminho de um arquivo como foi dado (relativo ao diretório de trabalho quando está dentro dele), ou o nome de uma tabela como o SQL nesta conexão a alcança: sem qualificação no esquema padrão, `schema.table` em outro caso |
| `kind` | `file`, `glob`, `table`, `view` ou `workbook` |
| `from` | O SQL que o lê, pronto para seguir um `FROM`: um caminho entre aspas, ou um identificador entre aspas quando necessário |
| `rows` | A estimativa do catálogo para uma tabela, exata para Parquet (a partir do footer), `null` onde saber exigiria um scan — CSV, JSON, visões |
| `column_count`, `columns` | As colunas como o DuckDB as descreve |
| `files` | Para um `glob`: quantos arquivos ele corresponde |

Um glob cujas correspondências são todas de um mesmo formato é uma única
relação, lida como um `source` de `.dash` a lê (`ducklocal schema 'logs/*.csv'`);
`--stats` a analisa como uma. Um glob com formatos misturados, e uma pasta,
listam seus arquivos um a um.

Um catálogo pequeno volta inteiro (`"detail": "full"`). A partir de 12 relações
ou 400 colunas ele é um **resumo** (`"detail": "summary"`). As 5 relações com mais
linhas mantêm suas colunas; as demais listam nome, tipo, linhas e número de
colunas, e `without_columns` as conta. Para obter mais, o `hint` nomeia as duas
maneiras: `--table NAME` para uma relação (buscada pelo nome, pelo nome da tabela
sem qualificação ou pelo nome de um arquivo) e `--full` para todas. Uma pasta de
trabalho é listada com suas `sheets` e sem colunas, já que não tem função de
tabela; `--stats` lê sua primeira planilha. Um caminho PATH que não existe, ou um
`--table` que não nomeia nada, sai com código 2.

Texto com gzip como `.json.gz` e `.csv.gz` é aqui um arquivo de dados, como é para
blocos `source` e para a janela. Um arquivo cujos registros ficam em uma única
lista — o `{"Records": [...]}` do CloudTrail, por exemplo — volta com um `hint`:
o SQL que lê esses registros como linhas, já que, de outro modo, a única linha e a
única coluna descrevem só o invólucro.

## Explore e converta arquivos

Depois de confirmar que o arquivo 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'"
```

Não presuma que `amount` existe: execute `ducklocal schema` ou `DESCRIBE` antes.
Calcule as agregações completas em SQL em vez de somar uma prévia truncada. As
chamadas da CLI não compartilham as visões registradas da GUI nem as tabelas em
memória umas das outras. Persista explicitamente quando for preciso:

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

Um conflito de bloqueio do banco de dados é um erro. Feche o outro escritor
(inclusive a GUI) ou use uma cópia autorizada; nunca apague arquivos de bloqueio
nem crie silenciosamente um banco de dados diferente.

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

`read_ndjson_objects` é o leitor para JSON delimitado por quebras de linha (um
objeto por linha, `.jsonl`/`.ndjson`); `read_json`/`read_json_auto` leem documentos
JSON (um array ou um único objeto). Nomeie o leitor explicitamente para um arquivo
JSONL em vez de depender da detecção automática.
`json_extract_string(col, '$.a.b[0].c')` percorre um caminho aninhado — chaves de
objeto e índices de array — e responde 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"
```

Use `json_extract` em vez disso quando a folha não for uma string e você a quiser
como JSON.

## Estatísticas de colunas

`ducklocal schema --stats` responde às perguntas que decidem um gráfico, uma
escala e um formato de número, antes de qualquer coisa ser construída sobre elas.
`DESCRIBE` diz que uma coluna é `DOUBLE`; suas estatísticas dizem que ela usa duas
casas decimais, que seu maior valor é mil vezes sua mediana e que suas datas
pulam onze dias no meio.

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

`--stats` analisa uma única relação: a única que os argumentos nomeiam, ou a que
`--table` escolhe — duas ou mais sem `--table` é código 2, com um hint dizendo
isso. Não pode ser combinado com `--full`. `ducklocal profile TARGET [--database PATH]`,
de versões anteriores, é o mesmo relatório e ainda funciona.

A relação é um arquivo de dados — `csv`, `tsv`, `txt`, `parquet`, `json`,
`ndjson`, `jsonl` — ou uma pasta de trabalho (`xlsx`, `xls`, `xlsb`, `ods`; sua
primeira planilha é importada como tabela TEMP e analisada), ou, com
`--database`, o nome de uma tabela ou visão. Um nome com pontos é lido como
`schema.table` e cada parte vai entre aspas, então um nome com espaço ou letra
maiúscula funciona como escrito. Uma relação que não nomeia nada é um erro de
argumento (código 2), não de SQL.

Volta um único objeto JSON: `target`, `relation` (o SQL contra o qual as
estatísticas rodaram), `row_count`, `elapsed_ms` e `columns` na ordem própria da
relação. Por coluna:

| Campo | Significado |
| --- | --- |
| `name`, `type` | como o `DESCRIBE` informa |
| `nulls` | linhas em que a coluna é `NULL` |
| `distinct` | exato, não estimado |
| `unique` | presente e `true` quando `distinct` é igual a `row_count` |
| `min`, `max` | como texto, para que um `DECIMAL` mantenha seus dígitos |
| `decimals` | dígitos depois do ponto que a coluna **realmente usa**, que não é sua escala declarada |
| `median` | um valor que a coluna contém, não uma interpolação entre dois deles |
| `max_over_median` | quantas vezes o maior valor é maior que a mediana — o número que decide um eixo linear em vez de um logarítmico |
| `covered_days`, `span_days`, `missing_days` | dias que a coluna nomeia, dias entre suas pontas e a diferença: `0` é uma série contínua, qualquer outra coisa são buracos que uma linha desenharia por cima |

`decimals`, `median` e `max_over_median` aparecem em colunas numéricas; os campos
de dias, em datas e timestamps. Colunas `LIST`, `STRUCT`, `MAP` e `UNION` informam
somente `nulls` — `min` e `max` não são definidos nelas.

Uma coluna de texto que contém números e uma palavra curta, como o `NA` do R,
também informa `null_marker` e `null_marker_rows`. O relatório então acrescenta um
`hint` nomeando a chamada de `read_csv` que lê a coluna como números.

As estatísticas são exatas e leem a relação inteira, então custam um scan
completo. `--limit` não se aplica: o perfil de uma amostra não é um perfil.

## Mostre o trabalho na janela em execução {#show-work-in-the-running-window}

`ducklocal open` entrega algo à janela do DuckLocal que já está em execução —
iniciando uma se não houver nenhuma — e a traz para a frente. É assim que um
agente põe seu trabalho na frente de uma pessoa, onde ela pode continuar a partir
dali:

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

- Caminhos PATH abrem como quando você arrasta algo para a janela: um arquivo
  `.dash` como aba, um arquivo de banco de dados DuckDB como o banco de dados da
  janela, e arquivos de dados, pastas e globs anexados como visões. Caminhos PATH
  relativos são resolvidos a partir do diretório do comando. Uma requisição que
  chega enquanto a janela ainda está iniciando espera até que sua abertura de
  inicialização termine.
- `--sql` ou `--sql-file` (`-` lê da entrada padrão) abre uma nova aba de
  consulta, com o título `--title`. `--run` a executa depois que os caminhos PATH
  foram anexados.
- `--no-launch` falha com kind `not_running` em vez de iniciar uma janela — para
  uma máquina onde uma janela aparecendo sem ser pedida seria mal recebida.

O sucesso imprime `{"delivered": true, "launched": BOOL}`: a entrega, não um
resultado. O que abre roda na sessão própria da janela — sua conexão, suas visões
anexadas, seu histórico — e qualquer erro aparece lá, não no stdout. Código 2 para
argumentos; 1 com kind `not_running` (nenhuma janela alcançável), `refused` (a
janela recusou a requisição) ou `launch`.

A janela escuta em uma porta de loopback. Ela escreve a porta e um token aleatório
em um arquivo que só a sua conta consegue ler (veja
[Configurações e dados do app](settings-and-data.md#where-things-are-stored));
outro usuário da máquina, ou uma página web apontando para localhost, não
consegue alcançá-la.

### Leia o que a janela mostra

`ducklocal open --state` vai na direção oposta: não abre nada, nunca inicia uma
janela e imprime o que a janela em execução mostra — assim um agente pode retomar
de onde uma pessoa parou, em vez de pedir que ela cole sua 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` é o arquivo de banco de dados aberto, ou `":memory:"`; `attached`
  lista os arquivos que a janela registrou como visões, com o `name` da visão. Uma
  consulta da CLI não consegue ler essas visões — use o `path`.
- Uma aba de **consulta** tem `sql`, o texto do editor, tenha ele rodado ou não, e
  `result`: `status` é `empty`, `running`, `rows`, `affected`, `failed`, `explain`
  ou `profile`. Para linhas: `columns`, `row_count`, `truncated`, `preview` (as
  primeiras 20 linhas como a grade as mostra, em strings), `elapsed_ms` e o `sql`
  que as produziu; para `affected`, `count` e `elapsed_ms`; para uma falha,
  `error`.
- Depois que a pessoa escolheu colunas na aba Gráfico, um resultado também tem
  `chart`: `type`, `x`, `y`, `split` e `dash`, um bloco `query` e um bloco `plot`
  que desenham o mesmo gráfico em um painel.
- `explain` é o que o **Explain** mostra: `plan`, a saída de `EXPLAIN` do DuckDB
  como um array de linhas de texto, e `elapsed_ms`.
- `profile` é o que o **Perfil** mostra (veja [Editor SQL](sql-editor.md)): `plan`,
  a árvore de operadores que o `EXPLAIN ANALYZE` mediu, como um array de raízes,
  cada uma `{operator, seconds, rows, estimated, children}` — `seconds` é o tempo
  próprio do operador sem os filhos, `rows` o que ele produziu, `estimated` a
  estimativa do otimizador para `rows` (`null` onde o plano não indica nenhuma),
  `children` a mesma forma outra vez. `operator_seconds` é a soma do tempo próprio
  de cada operador, que é o valor a que as parcelas somam, não o tempo de relógio;
  `elapsed_ms` é a execução inteira.
- Uma aba de **painel** tem `path`, `unsaved` e `dashboard`: o caminho do seu
  `comments_file`, seus `plots` (nome, tipo, título, consulta, linhas,
  `open_comments` e `failure` quando um não consegue desenhar) e seus `filters`
  com o que cada um selecionou: `picked`, `value` (o primeiro valor), `values`
  (todos os valores selecionados, em ordem) e `multiple`. `value: null` com
  `picked: true` significa que o valor NULL foi selecionado.

Use `--state sales.dash` para manter apenas as abas que mostram aquele painel, ou
`--state --active` para apenas a aba ativa. Um caminho que não está aberto devolve
código 1, kind `not_open`, com os painéis abertos no hint. `active_tab` é o índice
da aba ativa dentro das `tabs` devolvidas, ou `null` se ela não estiver entre
elas; `database` e `attached` continuam incluídos.

`--state` aceita um caminho `.dash` ou `--active`, não os dois. `--no-launch` é
aceito e não muda nada. Outras opções, incluindo `--sql` e `--run`, são inválidas
(código 2). Código 1 com kind `not_running` quando não há nenhuma janela aberta, e
`timeout` quando ela não responde em 5 segundos.

## Verifique uma especificação de painel {#check-a-dashboard-spec}

O formato em si — blocos, atributos, tipos de gráfico, regras de SQL e mensagens
comuns — é descrito em [Painéis (.dash)](dashboards.md); esta seção cobre o
comando.

Um arquivo `.dash` declara um painel como o Terraform declara infraestrutura —
consultas e gráficos como blocos, referências entre eles — em vez de programá-lo.
É fácil de escrever e de comparar com diff, tanto para uma pessoa quanto para um
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
```

Um bloco `source` nomeia arquivos de dados, relativos ao arquivo `.dash`, para as
consultas lerem, e um bloco `view` guarda SQL compartilhado por várias consultas.
Um bloco `query` guarda um atributo `sql` — uma instrução somente leitura, como
heredoc ou como string. `SELECT`, `WITH`, os que começam com `FROM`, `VALUES`,
`SHOW`, `DESCRIBE`, `SUMMARIZE` e `PIVOT` são aceitos; qualquer coisa que possa
escrever — DDL, DML, `COPY`, `ATTACH`, `INSTALL` — é um diagnóstico, e a GUI se
recusa a executá-la, porque as consultas de um painel rodam sempre que o arquivo é
aberto. Um bloco `plot` guarda `type` (um de `line`, `bar`, `stacked_bar`, `area`,
`scatter`, `pie`, `heatmap`, `histogram`, `map`, `timeline`, `table`, `card`,
`text`), `query` (uma referência como `query.latency` a um bloco de consulta no
mesmo arquivo), suas colunas, e `title` e `width` opcionais. Um bloco `filter`
torna um gráfico de barras ou uma tabela clicável — um valor, ou vários com
`multiple = true` em uma barra — e uma consulta lê a escolha como `$name`. `#` e
`//` comentam até o fim da linha. [Painéis (.dash)](dashboards.md) tem todos os
atributos.

Um gráfico `text` é a exceção: ele guarda `title`, `text`, ou ambos, e não aceita
`query`. Os cards também podem usar `note` e `tone`; veja
[Cards e painéis de texto](dashboards.md#cards-and-text-panels).

Primeiro as verificações estáticas: o SQL de cada consulta passa pelo parser real
do DuckDB em uma conexão descartável, como `query` valida antes de executar, e
cada `$name` é conferido contra os blocos `filter` — o SQL é analisado e executado
com cada `$name` como `TRUE`, que é o que o painel executa antes de qualquer
escolha.

Depois cada consulta roda, exatamente como abrir o painel a executaria — somente
leitura, com suas fontes, pelo mesmo caminho de código e com o mesmo orçamento de
linhas — e as colunas de cada gráfico são conferidas contra as colunas que a
consulta realmente devolve: um `y` que não é numérico é um erro para qualquer tipo
de gráfico, assim como as coordenadas não numéricas de um mapa ou seu `size`, e
uma `column` de filtro que a consulta do seu gráfico não devolve.

- **Sem `--database`** as consultas rodam em memória, que é tudo o que um painel
  sobre seus próprios arquivos `source` precisa. Uma consulta que lê uma tabela
  que nenhuma fonte define pode ser destinada a um banco de dados que não foi
  passado à verificação: ela é listada em `unresolved` (consulta, linha, motivo)
  em vez de falhar, e as colunas de seus gráficos não são conferidas.
- **Com `--database PATH`** (arquivo existente, somente leitura) elas rodam nesse
  banco de dados. Passe-o sempre que as consultas lerem tabelas de um banco de
  dados: tudo o que ficar em `unresolved` não foi conferido.

Toda consulta que lê um filtro também é vinculada com um valor selecionado, sem
executar essa variante. Isso detecta uma coluna de filtro ausente em uma consulta
consumidora, mesmo quando a versão inicial com `$name = TRUE` funciona. Um filtro
também precisa referenciar uma coluna devolvida pelo gráfico que o seleciona.

Executar e não apenas planejar importa: algumas falhas, como um cast que a
compilação não consegue fazer ou um valor que não vai converter, só aparecem
quando linhas são lidas, e uma verificação que as deixasse passar entregaria um
painel que não consegue desenhar. As consultas rodam inteiras, então uma
verificação contra um banco de dados grande leva o mesmo tempo que abrir o painel.

O sucesso é um único objeto JSON listando as fontes do arquivo (com o caminho
`resolved` de cada uma), as visões, as consultas (com suas colunas de resultado e
`rows`, quantas cada uma devolveu sem nada selecionado, mais `truncated: true`
quando o orçamento de linhas do painel a cortou), os filtros (com as `queries` que
leem cada um), os gráficos, `unresolved` e `empty` — as consultas que rodaram e
não devolveram linhas. Uma consulta vazia passa em todas as outras verificações,
mas costuma ser uma regex, um filtro ou uma junção que não encontrou nada, então
olhe cada uma. Com `--summary`, o sucesso é uma linha JSON compacta:

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

Os cinco campos de bloco são contagens; `unresolved` lista as consultas que não
puderam ser conferidas, e `empty` as que não devolveram linhas.

Um bloco com defeito fica de fora enquanto os blocos válidos seguem pela
validação. Erros de especificação e falhas de consulta são reunidos na mesma
execução, um `file:line: message` cada um. Se existir qualquer diagnóstico de
especificação, a saída é 2 com kind `spec`; se apenas a execução ou a vinculação
de SQL falhar, é 1 com kind `sql`. Falhas de banco de dados e de E/S também saem
com 1. `--summary` não esconde diagnósticos.

O mesmo arquivo abre como aba de painel na GUI — `ducklocal dashboard.dash`,
`ducklocal open dashboard.dash`, ou arraste-o para a janela — com os gráficos em
uma grade de 12 colunas e um gráfico que não consegue desenhar mostrando o motivo
na própria linha. Veja [Painéis (.dash)](dashboards.md).

## Métricas de um 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` lê um modelo do Apache Ossie, `model.ossie.yaml`, e lista
suas métricas e campos. `compile` imprime o único `SELECT` do DuckDB que
responde a um pedido, sem ler dados; `query` o executa como `ducklocal query`
faz, com um objeto `semantic` que traz o SQL e o `sha256` do modelo. Um pedido
que o modelo não consegue responder com exatidão é recusado, com código de
saída 2 e um `kind` como `metric_fanout`. [Métricas semânticas](metrics.md)
descreve o formato do modelo, cada opção e cada recusa.

## Comentários de revisão em um painel {#review-comments-on-a-dashboard}

As pessoas revisam um painel comentando seus gráficos na janela — passe o cursor
sobre um gráfico e clique no balão de fala (veja
[Revisar com comentários](dashboards.md#review-with-comments)). O
`ducklocal comments` é o lado do agente: ele lê os tópicos e os responde, sem
janela.

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

- Sem nenhuma ação, imprime os tópicos abertos:
  `{file, comments_file, open, threads}`. `--all` inclui os resolvidos.
- Cada tópico tem `id`, `plot` e o que o agente precisa para encontrá-lo na
  especificação: `plot_title`, `plot_query` e `plot_lines`, a primeira e a última
  linha do bloco `plot` (`null` quando a especificação não é analisada).
  `plot_missing` é `true` quando não resta nenhum gráfico com esse nome. Depois
  vêm `resolved` e `comments`, cada um com `author` (`user` ou `agent`), em um
  comentário de agente seu `name` (o nome que o [`presence`](#agent-presence)
  mostra), `text` e `at` (RFC 3339, hora local).
- `--reply ID --text TEXT` acrescenta a resposta do agente. Uma resposta a um
  tópico resolvido o reabre, a menos que `--resolve` também seja passado.
- `--resolve ID` e `--reopen ID` mudam o estado de um tópico;
  `--add PLOT --text TEXT` inicia um tópico, assinado como o agente.
- O número de um tópico serve como seu ID: `--reply 1` significa `c1`. `--add`
  recusa um gráfico que a especificação não tem (código 2), e o hint lista os
  gráficos dela.
- Uma ação imprime `{thread}`, como ficou.

Os tópicos são guardados ao lado da especificação, em `FILE.comments.json`. Uma
janela em execução percebe uma mudança em menos de um segundo e a mostra no
gráfico. Um id de tópico desconhecido é código 2, com um hint para listar os
tópicos; um arquivo de especificação que não existe é código 1.

Uma revisão, do começo ao fim: leia os tópicos abertos, edite a especificação,
execute `ducklocal check` e depois responda a cada tópico com o que mudou e
`--resolve`. Use `--reply` sem `--resolve` para perguntar algo de volta à pessoa.

## Mostre a atividade do agente {#agent-presence}

`check` e `comments` avisam automaticamente uma janela em execução sobre qual
painel o agente está trabalhando. `presence` pode anunciar uma edição antes que
ela aconteça:

```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` aceita `reading`, `editing` ou `idle` (`done` é um alias de `idle`).
- `--plot` recebe nomes de gráfico separados por vírgula. Com `editing`, nomes
  novos são permitidos e aparecem como espaços reservados. Com `reading` ou
  `idle`, um nome desconhecido é código 2.
- O nome exibido vem de `--agent`, depois de `DUCKLOCAL_AGENT`, depois do
  ambiente de agente detectado (Claude, Codex, Cursor ou Gemini), e por fim de
  `Agent`.
- A saída é `{delivered}`. Sem uma janela em execução, produz
  `{"delivered":false}` sem erro e sem iniciar nenhuma janela.

O nome fica no canto do painel enquanto os comandos mantêm a sessão ativa. Clique
nele para ver o log de atividade. Trinta segundos de silêncio ou `--doing idle`
encerram a sessão; gráficos alterados e adicionados continuam marcados até serem
vistos, e os avisos de gráficos removidos, até serem dispensados. Veja
[Veja um agente trabalhando](dashboards.md#agent-presence).

## Edite uma especificação de painel com LSP {#edit-a-dashboard-spec-with-lsp}

`ducklocal lsp` é um servidor do Language Server Protocol para arquivos `.dash`,
sobre stdio, para os editores iniciarem. Ele dá a qualquer editor compatível com
LSP o que o editor de especificações da própria GUI tem:

- **Diagnósticos**: os que `check` informa, publicados a cada abertura e a cada
  alteração (sincronização do documento inteiro, todos com severidade Error — são
  erros, não estilo).
- **Autocompletar**: tipos de bloco, nomes de atributo, tipos de gráfico e os
  nomes depois de `query.` e `plot.`, cada um com uma edição de texto que
  substitui a palavra que está sendo digitada.
- **Hover**: documentação de blocos, atributos e referências.
- **Ir para a definição**: de uma referência `query.name` ou `plot.name` até o
  nome do bloco dela.

Com `--database PATH`, o SQL de cada consulta também é validado pelo parser real
do DuckDB, como `check --database` faz.

Aponte o suporte genérico a LSP do seu editor para `ducklocal lsp` em arquivos
`*.dash` — o comando não recebe argumentos de documento; o editor fala com ele
por stdio. No 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,
})
```

No VS Code, qualquer extensão de LSP genérico faz o mesmo com o comando
`ducklocal`, os argumentos `["lsp"]` e o seletor de documento `dash`. Códigos de
saída: **0** depois de um `shutdown`/`exit` limpo, **1** quando o cliente vai
embora sem um, **2** para uma linha de comando ruim ou um handshake de protocolo
que falhou.

## Contrato JSON

Consultas bem-sucedidas escrevem exatamente um objeto JSON no stdout, seguido de
uma quebra de linha:

```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 cada linha preservam a ordem das colunas e nomes de coluna
duplicados. `type` é a **representação de depuração do Arrow**, não o nome do
tipo SQL original do DuckDB (por exemplo, HUGEINT e DECIMAL podem compartilhar um
portador Arrow). `row_count` conta as linhas devolvidas. `total_rows` conta as
linhas produzidas, incluindo as contadas depois do limite de saída;
`total_rows_exact: false` significa que a contagem parou depois de até 100.000
linhas adicionais, então esse total é um limite inferior. Nenhuma das duas
contagens é uma contagem de linhas afetadas. `elapsed_ms` mede a preparação, a
execução e a codificação das linhas, não o carregamento de arquivos nem a criação
da conexão. Resultados com zero linhas mantêm os metadados. DDL/DML expõem o
resultado real do DuckDB, incluindo colunas `Count`: INSERT/COPY costumam devolver
`[[N]]`; CREATE TABLE normalmente não devolve linhas. Eles não são classificados a
partir da primeira palavra-chave do SQL.

Codificação das células:

| Valor SQL | Codificação JSON |
| --- | --- |
| NULL | `null` (nunca a string `"NULL"`) |
| Booleano, float finito | booleano/número JSON |
| Inteiro dentro de ±9.007.199.254.740.991 | número JSON |
| Inteiro maior, incluindo HUGEINT/UHUGEINT | `{"encoding":"integer","value":"9007199254740992"}` |
| Decimal | `{"encoding":"decimal","value":"123.450"}` com o texto decimal exato |
| Texto, enum | string JSON |
| Blob, geometry | `{"encoding":"hex","value":"00ff"}`; bytes em minúsculas, geometry usa WKB |
| Date | `{"encoding":"date","unit":"Day","value":"1","iso":"1970-01-02"}`; dias desde 1970-01-01 |
| Timestamp | `{"encoding":"timestamp","unit":"Nanosecond","value":"123456789","iso":"1970-01-01T00:00:00.123456789"}`; contagem com sinal desde a época Unix; a unidade também pode ser Second/Millisecond/Microsecond |
| Time | `{"encoding":"time","unit":"Microsecond","value":"123456","iso":"00:00:00.123456"}`; contagem desde a meia-noite |
| Interval | `{"encoding":"interval","months":1,"days":2,"nanos":"3000"}` |
| NaN, infinito positivo/negativo | `{"encoding":"float","value":"NaN"}` / `"inf"` / `"-inf"` |
| List, array | array JSON, codificado recursivamente (incluindo nulos aninhados) |
| Struct | `{"encoding":"struct","fields":[["name",VALUE],...]}` |
| Map | `{"encoding":"map","entries":[[KEY,VALUE],...]}`; não é um objeto JSON, então as chaves mantêm seus tipos |
| Union | `{"encoding":"union-value","value":VALUE}`; apenas o valor ativo, a etiqueta do membro não é mantida |

Os `value` temporais são contagens exatas, então nenhuma precisão fracionária é
perdida; os sentinelas de infinito de data/timestamp continuam sendo contagens
brutas. Ao lado de cada um, `iso` é o mesmo valor como texto ISO 8601 para
leitura, com tantos dígitos de fração quantos a unidade comporta. Um timestamp de
uma coluna com fuso horário (metadados do Arrow) é um instante UTC, e seu `iso`
termina em `Z`. `--format md` também renderiza datas e timestamps de forma
legível. Como o wrapper Arrow do DuckDB fixado não consegue distinguir
HUGEINT, UHUGEINT e DECIMAL(38,0) aninhados, ocorrências não nulas produzem um
erro claro em vez de mudar o sinal ou a precisão em silêncio. Converta esses
campos explicitamente para VARCHAR no SQL. Tipos desconhecidos não suportados
também produzem um erro; não confunda um erro com um resultado vazio. A
codificação de union é uma representação do valor ativo, não uma ida e volta sem
perdas de uma union.

Os erros escrevem um objeto JSON no **stderr**, deixando o stdout vazio:

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

`hint` existe quando o próximo passo é conhecido, nos termos desta CLI: a flag que
uma escrita com erro de digitação queria ser, `--read-write` para uma escrita recusada em um
banco de dados somente leitura, `ducklocal schema` para uma tabela que não existe,
`TRY_CAST` para um valor que não vai converter, dividir um script que tem mais de
uma instrução, ou `AS` para uma palavra-chave usada como alias de coluna sem
qualificação (`SELECT count(*) AS minutes`, ou coloque entre aspas). Um agente
deveria agir conforme ele antes de reescrever o SQL. Ele está ausente quando não
há nada a acrescentar à mensagem do próprio DuckDB, como em um erro de sintaxe.

Códigos de saída: **0** sucesso, **2** argumentos ou número de instruções
inválidos, **1** falha de SQL, banco de dados, E/S ou saída. Os kinds de erro são
`argument`, `sql`, `database`, `io`, `output`, `spec` para `check`, e
`not_running`, `not_open`, `refused`, `timeout` ou `launch` para `open`. Verifique
o status de saída antes de analisar o stdout e inspecione `truncated` antes de
informar que algo está completo. Ajuda e versão são exceções em texto simples.
Falhas de transporte, como um pipe de stdout fechado, não conseguem garantir um
fluxo de saída vazio ou completo.

## Instale a skill oficial {#install-the-official-skill}

A skill ensina ao agente os hábitos que mantêm suas respostas honestas:
inspecionar o esquema, pré-visualizar uma amostra limitada, calcular agregações em
SQL, verificar `truncated` e responder a partir dos valores devolvidos. Ela cobre
inspeção de esquema, estatísticas de colunas, conversões, consultas a bancos de
dados, painéis `.dash` e seus comentários de revisão, e entregar trabalho à janela
e relê-lo; ela não oferece navegação no S3, comandos específicos de dados
espaciais, memória de sessão nem um servidor MCP.

**Pelo app.** Abra **Linha de comando e IA…** (o botão do robô na barra de título,
ou o menu do DuckLocal):

- **Instalar comando** coloca `ducklocal` no seu `PATH`, para que o shell de um
  agente possa executá-lo.
- **Adicionar ao Claude Code** escreve a skill em `~/.claude/skills/ducklocal`,
  onde o Claude Code a encontra em todos os projetos. Apenas os dois arquivos da
  própria skill são escritos; qualquer outra coisa nessa pasta é mantida. Quando
  uma atualização do DuckLocal traz uma skill mais nova, o diálogo oferece
  **Atualizar skill**.
- **Copiar resumo** copia uma explicação curta para qualquer outro agente — Codex,
  Cursor, uma janela de chat — nomeando o comando e como usá-lo.

**À mão.** A skill fica em
[`skills/ducklocal`](https://github.com/JetSquirrel/ducklocal/tree/main/skills/ducklocal).
Para adicioná-la a um único projeto (exemplo para o 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/
```

Inspecione um destino existente antes de sobrescrever mudanças locais. Outros
agentes podem usar o mesmo `SKILL.md` mais `references/cli.md` no diretório de
skills que eles suportam.
