# AI CLI 与官方 skill > 用 ducklocal CLI 无界面执行 DuckDB SQL：查看本地文件 schema、输出有边界的 JSON、校验仪表盘，并配合官方 AI agent skill。 Source: https://ducklocal.app/docs/zh/cli **[English](../cli.md)** ## 无窗口运行 `ducklocal --help` 列出九个子命令： | 命令 | 作用 | | --- | --- | | `ducklocal query` | 执行一条 SQL，把结果输出为 JSON | | `ducklocal schema` | 列出有哪些东西可查、各有哪些列；`--stats` 给出单个关系的逐列统计 | | `ducklocal open` | 把 SQL、仪表盘或数据显示到运行中的窗口里；`--state` 读回窗口当前的内容 | | `ducklocal check` | 校验 `.dash` 仪表盘 | | `ducklocal comments` | 读取并回复别人在仪表盘上留下的审阅评论 | | `ducklocal propose` | 提议一处仪表盘修改，由人审阅后应用 | | `ducklocal project` | 检查可移动的分析文件夹及其依赖；`relink` 修正移动后失效的路径 | | `ducklocal session` | 读回一次分析是怎么一步步得出结论的 | | `ducklocal presence` | 显示谁正在处理已打开的仪表盘，以及接下来要改哪些图表 | `ducklocal lsp`（编辑器为 `.dash` 文件启动的 language server）和 `ducklocal profile`（`schema --stats` 的旧写法）仍然可用，只是不列在 `--help` 里。 `propose`、`project`、`session` 三个子命令，以及 `--restricted`、`--wait`、`--if-revision` 选项，都是 0.4.0 新增的，详见 [Agent 工作流](agent-workflows.md)。 `ducklocal query` 执行 SQL 时，不会初始化 GUI、历史记录、已注册文件、语言设置，也不会创建 GUI 的全局连接。每次调用都会新建连接。若不带子命令（或仅传入文件、目录、glob 参数），则正常启动 GUI；若要在 GUI 中打开与子命令同名的路径（`query`、`schema`、`open`、`check`、`comments`、`propose`、`project`、`session`、`presence`、`profile`、`lsp`），请在前面加上 `./`，例如 `./query`。 ## 获取命令 {#get-the-command} DuckLocal 支持 macOS 12 及以上（Apple 芯片）、Windows（x86_64）和 Linux（x86_64）。CLI 就是应用本身的可执行文件，不需要另装 DuckDB CLI。 把命令加入 PATH，最快的办法是在应用里操作（0.1.1 及以上）：打开 **命令行与 AI…**（标题栏的机器人按钮，或 DuckLocal 菜单），点击 **安装命令**。同一个对话框还能为 agent（AI 助手）安装 skill，见[安装官方 skill](#安装官方-skill)。不安装的话，也可以按所在路径直接调用可执行文件： ```bash # macOS /Applications/DuckLocal.app/Contents/MacOS/ducklocal --help # Linux：tar 包解压到的位置 ./ducklocal-linux-x86_64/ducklocal --help # Windows（PowerShell）：zip 解压到的位置 .\ducklocal-windows-x86_64\ducklocal.exe --help ``` 从源码构建：在 DuckLocal 源码仓库运行 `cargo build --locked`，得到 `./target/debug/ducklocal`。以下示例假定 `ducklocal` 已在 PATH 中。旧版可能没有 `query`，先查看 `--help`。JSON 和 Parquet 支持已编入二进制，查询时不会再下载。 ## 查询选项 ```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" ``` - 必须且只能提供 `--sql SQL` 或 `--sql-file FILE`。文件必须为 UTF-8；`-` 从 stdin 读取。SQL 只能包含一条语句，DuckDB 解析器会在打开目标数据库、执行任何操作之前检查这一点；注释、引号里的分号、末尾的分号都没问题。多语句脚本直接拒绝，不会只执行其中一部分。 - `--database PATH` 默认以**只读**打开**已有文件**；省略则用新的内存数据库。`--read-write` 必须和 `--database` 一起用，明确允许写入和新建数据库（但不会创建父目录）。数据库出错时不会退回内存数据库。DuckDB 打不开某个文件时，错误信息开头是 DuckLocal 从文件头读出的原因（由更新的 DuckDB 写入、v0.9 时代的文件、SQLite 文件，或者根本不是数据库）以及该怎么办（更新版本写的文件，给出在那个版本里执行的 `ATTACH … (STORAGE_VERSION)` / `COPY FROM DATABASE` 复制语句；SQLite 文件，给出读取它的 `ATTACH`），后面才是 DuckDB 自己的报错。 - `--limit N` 为正整数，默认 1000，限制返回行数；另有 2,000,000 个单元格的预算。达到输出上限后，CLI 仍会继续统计最多额外 100,000 行，不再编码这些行的值，并报告 `total_rows` 与 `total_rows_exact`。这限制的是输出量，不是计算量或内存；排序、聚合仍可能处理全部输入。输出上限之后遇到的执行错误仍会使命令失败。 - `--format json`（默认）输出下文的 JSON 契约；`--format md` 把同一份结果输出为 Markdown 表格，方便放进文档或交给 agent 阅读。其他一概不变：同样的 SQL、同样的限制、同样的错误。 - 重复/未知参数、缺失值、空 SQL、非法 limit 均报错。参数和值要分开写，不支持 `--flag=value`。相对路径以进程的工作目录为准，而不是 SQL 文件所在的目录。shell 里的路径要加引号；SQL 里的路径含单引号时写两个（`'O''Brien.csv'`）；SQL 标识符用双引号。 **数据库只读，不等于文件系统或网络沙箱。** 即使数据库只读，`COPY` 这类 SQL 照样能写文件。输出路径、覆盖文件、修改数据库、安装扩展、访问外部资源，都要在执行前确认已获授权。DuckLocal 不会自动安装扩展，也不会自动重试；获得授权后仍可显式执行 `INSTALL`/`LOAD`，已安装的扩展可能自动加载。命令失败时也可能已经产生副作用（例如输出出错之前已经写入），重试前先检查目标位置。 ### Markdown 输出 `--format md` 只是换一种呈现方式，不是另一份契约：值与 JSON 里的完全相同，写法与结果表格里的显示一致。 | 值 | 输出为 | | --- | --- | | `NULL` | `NULL` | | 整数、DECIMAL、浮点 | 值本身的全部数字，一位不差：`DECIMAL(38,10)` 保留刻度，`NaN`/`inf`/`-inf` 原样写出 | | `DATE` | `YYYY-MM-DD` | | `TIMESTAMP` | `YYYY-MM-DD HH:MM:SS[.fffffffff]`，只在确有小数时带小数，有几位显示几位。不附加时区；原始计数在 `--format json` 里 | | `TIME` | `HH:MM:SS[.ffffff]` | | `INTERVAL` | 和 DuckDB 的写法一致：`1 month 2 days 00:00:00.000003` | | `BLOB`、`GEOMETRY` | `0x00ff`，过长时以 `…` 省略 | | `LIST`、`STRUCT`、`MAP` | `[1, 2]`、`{x: 1}`，超过 120 字符时以 `…` 省略 | 单元格里的 `|` 会转义，换行写成 `
`，值里有什么都不会打乱表格。结果为零行时，表格后面跟一行 `_0 rows._`；结果因 `--limit` 或单元格预算被截断时，后面跟 `_Truncated at 2 of 5000 rows, so this is not the whole answer._`（超过 100,000 行的计数上限时是 `of at least …`），免得把预览读成完整答案。出错时的行为不变：JSON 写到 stderr，stdout 为空。 ## 看看有什么可查 {#map-what-can-be-queried} `ducklocal schema` 一次回答"有哪些东西、各有哪些列"，`DESCRIBE` 则要一个关系一个关系地问。agent 应该先跑它。 ```bash ducklocal schema ./data/ # 文件、文件夹、通配符 ducklocal schema --database warehouse.duckdb # 表和视图 ducklocal schema warehouse.duckdb --table orders # 单个关系的完整信息 ducklocal schema ./logs/ --full # 全部列出，不管多大 ``` PATH 的展开方式和拖到窗口上一样：文件夹递归找出其中的数据文件（跳过隐藏文件，最多 256 个），通配符取所有匹配，数据库文件等同于用 `--database` 指定。返回一个 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} ``` | 字段 | 含义 | | --- | --- | | `name` | 文件按给出的路径显示（在工作目录下时写成相对路径）；表按当前连接上 SQL 能访问到的名字显示：默认 schema 里只写表名，其他 schema 写 `schema.table` | | `kind` | `file`、`glob`、`table`、`view` 或 `workbook` | | `from` | 读取它的 SQL，可以直接接在 `FROM` 后面：文件是带引号的路径，需要时表名会加引号 | | `rows` | 表取目录里的估计值，Parquet 取文件尾部记录的精确值；CSV、JSON、视图要扫描才知道，给 `null` | | `column_count`、`columns` | DuckDB 描述的列 | | `files` | `glob` 匹配到的文件数 | 匹配到的文件都是同一种格式时，一个 glob 算作一个关系，读法和 `.dash` 的 `source` 一样（`ducklocal schema 'logs/*.csv'`），`--stats` 也把它当作一个整体统计。格式混杂的 glob 和文件夹，则逐个列出其中的文件。 目录小时完整返回（`"detail": "full"`）。超过 12 个关系或 400 列时改为返回**摘要**（`"detail": "summary"`）。行数最多的 5 个关系带完整的列，其余只列名字、类型、行数和列数，`without_columns` 是这类关系的个数。要看更多，`hint` 给出两种办法：`--table NAME` 看其中一个（可以按列出的名字、不带 schema 的表名或文件名匹配），`--full` 看全部。工作簿没有对应的表函数，只列出 `sheets`，不给列；`--stats` 会读它的第一个工作表。PATH 不存在，或 `--table` 找不到对应的关系，退出码为 2。 ## 探查与转换 确认文件实际存在后： ```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'" # 仅在确认此输出路径已获授权后运行： 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'" ``` 别猜 `amount` 这样的列存不存在，先跑 `ducklocal schema` 或 DESCRIBE。完整的汇总要在 SQL 里算，不要把截断的预览加起来。CLI 调用看不到 GUI 注册的视图，彼此之间也不共享内存表；需要持久化时，显式写入数据库： ```bash # 分两次调用执行，每次只有一条语句；写入必须获得授权。 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" ``` 数据库锁冲突直接报错。关闭另一个写入方（包括 GUI），或改用经过授权的副本；不要删除锁文件，也不要悄悄另建一个数据库。 ## JSONL 与嵌套 JSON `read_ndjson_objects` 是换行分隔 JSON（每行一个对象，`.jsonl`/`.ndjson`）的读取函数；`read_json`/`read_json_auto` 读取的是 JSON 文档（一个数组或单个对象）。读 JSONL 文件时显式写明读取函数，别依赖自动探测。`json_extract_string(col, '$.a.b[0].c')` 按嵌套路径（对象键和数组下标）取值，返回 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" ``` 叶子节点不是字符串、想按 JSON 取出时，改用 `json_extract`。 ## 逐列统计 动手之前，得先定下画什么图、用什么刻度、数字怎么格式化，`ducklocal schema --stats` 回答的就是这些问题。`DESCRIBE` 只说某列是 `DOUBLE`；统计则告诉你：它实际只用两位小数，最大值是中位数的一千倍，日期在中间断了十一天。 ```bash ducklocal schema sales.csv --stats ducklocal schema ./exports/ --table orders.parquet --stats ducklocal schema --database warehouse.duckdb --table "my orders" --stats ``` `--stats` 只统计一个关系：参数只指向一个时就是它，否则用 `--table` 指定；指向两个以上又没写 `--table` 时退出码为 2，并提示加 `--table`。它不能和 `--full` 一起用。早先版本的 `ducklocal profile TARGET [--database PATH]` 输出同样的报告，现在仍然可用。 关系可以是数据文件（`csv`、`tsv`、`txt`、`parquet`、`json`、`ndjson`、`jsonl`），或工作簿（`xlsx`、`xls`、`xlsb`、`ods`，取第一个工作表导入为 TEMP 表后做逐列统计）；配合 `--database` 时，也可以是表名或视图名。带点的名字按 `schema.table` 拆开并逐段加引号，所以带空格或大写的名字可以照原样写。指向的对象不存在时，报参数错误（退出码 2），而不是 SQL 错误。 返回一个 JSON 对象：`target`、`relation`（统计实际针对的 SQL）、`row_count`、`elapsed_ms`，以及 `columns`（按关系本身的列顺序排列）。每列包含： | 字段 | 含义 | | --- | --- | | `name`、`type` | 与 `DESCRIBE` 一致 | | `nulls` | 该列为 `NULL` 的行数 | | `distinct` | 精确值，不是估算 | | `unique` | `distinct` 等于 `row_count` 时出现，值为 `true` | | `min`、`max` | 以文本给出，`DECIMAL` 因此不丢位数 | | `decimals` | 小数点后**实际用到**的位数，不是声明的刻度 | | `median` | 该列真实存在的一个值，不是两个值之间的插值 | | `max_over_median` | 最大值是中位数的多少倍；用线性刻度还是对数刻度，就看这个数 | | `covered_days`、`span_days`、`missing_days` | 该列出现过的天数、首尾之间的天数，以及两者之差：`0` 表示连续，非零说明中间有空缺，折线会直接连过去 | `decimals`、`median`、`max_over_median` 只出现在数值列，日期三项只出现在 DATE/TIMESTAMP 列。`LIST`、`STRUCT`、`MAP`、`UNION` 列只报告 `nulls`，因为这些类型没有定义 `min`/`max`。 如果文本列里是数字加一个短词（比如 R 的 `NA`），还会报告 `null_marker` 和 `null_marker_rows`，报告里也会多一条 `hint`，写明能把这一列读成数字的 `read_csv` 调用。 统计值是精确的，要读完整个关系，所以一次统计就是一次全表扫描。`--limit` 对它不起作用：只看样本，算不上统计。 ## 把结果显示到运行中的窗口 {#show-work-in-the-running-window} `ducklocal open` 把东西交给已经在运行的 DuckLocal 窗口（没有就先启动一个），并把窗口提到前面。agent 用它把结果摆到人面前，人可以接着改： ```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 # 打开为仪表盘标签页 ducklocal open ./data/ --sql-file analysis.sql echo "SELECT 42" | ducklocal open --sql-file - --no-launch ``` - PATH 的打开方式和拖到窗口上一样：`.dash` 文件打开为标签页，DuckDB 数据库文件作为窗口的数据库打开，数据文件、文件夹和通配符挂载为视图。相对路径按命令所在的目录解析。窗口还在启动时收到的请求，会等启动时的打开完成后再处理。 - `--sql` 或 `--sql-file`（`-` 表示 stdin）打开一个新的查询标签页，标题为 `--title`；`--run` 会在 PATH 挂载完之后执行它。 - `--no-launch` 在没有窗口时直接失败（kind 为 `not_running`），不启动窗口。适合不希望突然弹出窗口的机器。 成功时输出 `{"delivered": true, "launched": BOOL}`：只表示送达，不是查询结果。打开的内容在窗口自己的会话里运行（它的连接、挂载的视图、历史记录），出错也显示在窗口里，不在 stdout。参数错误退出码为 2；无法送达时退出码为 1，kind 为 `not_running`（找不到窗口）、`refused`（窗口拒绝了请求）或 `launch`。 窗口在本机回环端口上监听，端口和一个随机会话令牌写在只有你自己能读的文件里（见[设置与应用数据](settings-and-data.md#where-things-are-stored)）；本机其他用户或指向 localhost 的网页都连不上。 ### 读取窗口当前的内容 `ducklocal open --state` 方向相反：什么都不打开，也从不启动窗口，只输出运行中的窗口正在显示什么。这样 agent 可以从人停下的地方接着做，而不用请人把查询贴过来。 ```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` 是当前打开的数据库文件，或 `":memory:"`；`attached` 列出窗口注册为视图的文件及视图的 `name`。CLI 查询读不到这些视图，要用 `path`。 - **查询**标签页有 `sql`（编辑器里的文本，不管执行过没有）和 `result`：`status` 为 `empty`、`running`、`rows`、`affected`、`failed`、`explain` 或 `profile`。有行时给出 `columns`、`row_count`、`truncated`、`preview`（前 20 行，和表格里显示的一样，都是字符串）、`elapsed_ms` 以及产生它们的 `sql`；`affected` 给出 `count` 和 `elapsed_ms`；失败时给出 `error`。 - 用户在图表标签页选过列之后，结果里还会有 `chart`：`type`、`x`、`y`、`split`，以及 `dash`，即能在仪表盘里画出同一张图的 `query` 和 `plot` block。 - `explain` 对应**执行计划**按钮显示的内容：`plan` 是 DuckDB `EXPLAIN` 的输出，按行组成的字符串数组；另有 `elapsed_ms`。 - `profile` 对应**性能分析**按钮显示的内容（见 [SQL 编辑器](sql-editor.md)）：`plan` 是 `EXPLAIN ANALYZE` 实测的算子树，一个根节点数组，每个节点为 `{operator, seconds, rows, estimated, children}`。`seconds` 是该算子自身的耗时，不含子节点；`rows` 是它产出的行数；`estimated` 是优化器对 `rows` 的估计（计划里没给时为 `null`）；`children` 结构相同。`operator_seconds` 是所有算子自身耗时之和，各算子的占比以它为分母，它不是墙钟时间；`elapsed_ms` 是整次运行的耗时。 - **仪表盘**标签页有 `path`、`unsaved` 和 `dashboard`：其中包含 `comments_file` 路径、`plots`（名字、类型、标题、查询、行数、`open_comments`，画不出来时有 `failure`）和 `filters`（每个 filter 当前选中了什么）。`picked: true` 而 `value: null` 表示选中的是 NULL。 `--state sales.dash` 只保留显示该仪表盘的标签页，`--state --active` 只保留当前标签页。指定路径没有打开时，退出码为 1，kind 为 `not_open`，提示中列出已打开的仪表盘。`active_tab` 是当前标签页在返回的 `tabs` 中的位置；若它不在其中，则为 `null`。`database` 与 `attached` 始终保留。 `--state` 可带一个 `.dash` PATH 或 `--active`，两者不能同时使用；可以带 `--no-launch`，但不起作用；不能再带 `--sql`、`--run` 等其他选项（退出码 2）。没有窗口时退出码为 1，kind 为 `not_running`；窗口 5 秒内没有回应时 kind 为 `timeout`。 ## 校验仪表盘规格文件 {#校验-dashboard-规格文件} 格式本身（block、属性、图表类型、SQL 规则与常见提示信息）见 [仪表盘（Dashboard，.dash）](dashboards.md)；本节讲命令本身。 `.dash` 文件用声明的方式描述仪表盘，就像 Terraform 声明基础设施：查询和图表写成 block，彼此通过引用连接，不用写脚本。人和 agent 都容易写、容易 diff。 ```hcl query "latency" { sql = <