# AI CLI と公式スキル

> DuckLocal の DuckDB SQL CLI を AI エージェントと一緒に使います。ローカルファイルのスキーマを確認し、1 つのステートメントを実行して、GUI もサーバーもなしで上限付きの JSON を返します。

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

タスク中心の概要は [ローカルデータのための AI エージェント向け SQL](https://ducklocal.app/use-cases/ai-agent-sql/) を参照してください。このページはコマンドと出力の完全なリファレンスです。

## ウィンドウなしで実行する

`ducklocal --help` は 10 個のサブコマンドを一覧表示します:

| コマンド | 内容 |
| --- | --- |
| `ducklocal query` | 1 つの SQL ステートメントを実行し、結果を JSON で出力します |
| `ducklocal schema` | クエリできる対象を列とともに一覧表示します。`--stats` で 1 つのリレーションの列統計を表示します |
| `ducklocal open` | 実行中のウィンドウに SQL、ダッシュボード、データを表示します。`--state` で表示内容を読み戻します |
| `ducklocal check` | `.dash` ダッシュボードを検証します |
| `ducklocal metrics` | セマンティックモデルの指標を一覧表示します。`compile` や `query` でコンパイル・実行します |
| `ducklocal comments` | ダッシュボードに付けられたレビューコメントを読み、返信します |
| `ducklocal propose` | ダッシュボードの変更を提案し、人がレビューして適用できるようにします |
| `ducklocal project` | ポータブルな分析フォルダーとその必要なものを確認します。`relink` は移動したパスを修復します |
| `ducklocal session` | 分析がどのように現在の状態に至ったかを読み戻します |
| `ducklocal presence` | 開いているダッシュボードで誰が作業しているか、編集がどこに反映されるかを表示します |

エディタが `.dash` ファイルのために起動する言語サーバー `ducklocal lsp` と、`schema --stats` の従来の別名である `ducklocal profile` は引き続き動作しますが、`--help` には表示されません。

`propose`、`project`、`session`、および `--restricted`、`--wait`、`--if-revision` オプションは 0.4.0 で追加され、[エージェントのワークフロー](agent-workflows.md) で説明しています。`metrics` と `--format html` は 0.4.1 より新しい機能です。`main` ブランチにあり、次のリリースで提供されます。`metrics` は [セマンティック指標](metrics.md) で説明しています。

`ducklocal query` は、GUI、履歴、登録済みファイル、言語設定、GUI のグローバル接続を初期化せずに SQL を実行します。呼び出しごとに専用の接続を作成します。コマンドを付けずに DuckLocal を起動した場合、またはファイルパス、ディレクトリ、glob パターンだけを指定した場合は、通常の GUI が開きます。コマンド名（`query`、`schema`、`open`、`check`、`metrics`、`comments`、`propose`、`project`、`session`、`presence`、`profile`、`lsp`）と同名の GUI パスを開くには、`./query` のように `./` を前に付けます。

## コマンドを入手する {#get-the-command}

DuckLocal は Apple silicon 上の macOS 12 以降、Windows（x86_64）、Linux（x86_64）をサポートします。CLI はアプリケーションの実行ファイルから直接動作するため、別途 DuckDB CLI のバイナリをインストールする必要はありません。

PATH に追加する最短の方法はアプリから行うことです（0.1.1 以降）。**コマンドラインと AI…**（タイトルバーのロボットボタン、または DuckLocal メニュー）を開き、**コマンドをインストール** をクリックします。同じダイアログで AI エージェント向けのスキルもインストールできます。詳しくは [公式スキルをインストールする](#install-the-official-skill) を参照してください。インストールせずに使う場合は、実行ファイルをその場所で呼び出します:

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

ソースのチェックアウトからは、`cargo build --locked` で `./target/debug/ducklocal` をビルドできます。以下の例では `ducklocal` が PATH にあることを前提としています。古いリリースには `query` がない場合があるため、まず `--help` を確認してください。JSON と Parquet のサポートは同梱されており、クエリ時にダウンロードされることはありません。

## クエリのオプション {#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"
```

- `--sql SQL` と `--sql-file FILE` のどちらか一方が必須です。ファイルは UTF-8 である必要があり、`-` は標準入力を読みます。SQL には 1 つのステートメントだけを含める必要があります。DuckDB のパーサーが、対象データベースを開く前、何かを実行する前にこれを検証します。コメント、引用符で囲まれたセミコロン、末尾のセミコロンは問題ありません。スクリプトは部分的に実行されることなく、拒否されます。
- `--database PATH` は **既存のファイルを、デフォルトでは読み取り専用で** 開きます。省略すると新しいインメモリデータベースになります。`--read-write` は `--database` を必要とし、書き込みとデータベースの作成（親ディレクトリは対象外）を明示的に許可します。データベースのエラーがメモリにフォールバックすることはありません。DuckDB がファイルを拒否した場合、エラーメッセージは DuckDB 自身のメッセージより前に、DuckLocal がファイルのヘッダーから読み取った理由（より新しい DuckDB で書かれた、v0.9 時代のファイル、SQLite ファイル、データベースではない）と、代わりに実行すべきこと（より新しいファイルなら、そのリリースで作成する `ATTACH … (STORAGE_VERSION)` / `COPY FROM DATABASE` のコピー、SQLite ならそれを読み取る `ATTACH`）で始まります。
- `--limit N` は正の整数で、デフォルトは 1000 で、返される行数の上限です。2,000,000 セルの予算も適用されます。上限に達した後も、CLI は値をエンコードせずに最大 100,000 行までカウントを続け、`total_rows` と `total_rows_exact` を報告します。これは出力を制限するもので、計算やメモリを制限するものではありません。並べ替えや集計は入力全体を処理する可能性があります。出力の上限に達した後に発生した実行エラーでも、コマンドは失敗します。
- `--format json`（デフォルト）は以下の契約です。`--format md` は同じ結果を Markdown の表として描画し、ドキュメントやそれを読むエージェント向けです。`--format html` は自己完結した 1 つの Web ページとして描画します。[HTML 出力](#html-output) を参照してください。それ以外は何も変わりません。同じ SQL、同じ上限、同じエラーです。
- フラグの重複や不明なフラグ、値の欠落、空の SQL、不正な上限はエラーです。オプションは `--flag=value` ではなく、値を別に指定します。相対パスは SQL ファイルのディレクトリではなく、プロセスの作業ディレクトリを基準に解決されます。シェルのパスは引用符で囲み、SQL 内ではアポストロフィを 2 つ重ねます（`'O''Brien.csv'`）。SQL の識別子は二重引用符を使います。

**読み取り専用は、ファイルシステムやネットワークのサンドボックスではありません。** データベースが読み取り専用でも、`COPY` などの SQL はファイルを書き込めます。実行前に、出力パス、上書き、データベースの変更、拡張機能のインストール、外部アクセスを承認してください。DuckLocal は拡張機能を自動でインストールしたり、操作を再試行したりしません。承認があれば、明示的な `INSTALL`/`LOAD` SQL は引き続き可能です。インストールされた拡張機能は自動読み込みされる場合があります。失敗したコマンドがすでに副作用を実行している可能性があります（たとえば出力の失敗の前など）。再試行する前に出力先を確認してください。

### Markdown 出力

`--format md` は描画であり、2 つ目の契約ではありません。値は JSON が保持しているもので、結果グリッドでの表示方法で書かれます。

| 値 | 表示 |
| --- | --- |
| `NULL` | `NULL` |
| 整数、decimal、float | 値が持つ桁そのまま — `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 文字を超えると `…` で省略されます |

セル内の `|` はエスケープされ、改行は `<br>` になるため、値が入っている表を壊すことはありません。行のない結果の後には `_0 rows._` が付き、`--limit` やセルの予算で途中で切られた結果には `_Truncated at 2 of 5000 rows, so this is not the whole answer._`（100,000 行のカウントを超える場合は `of at least …`）が付きます。プレビューは完全な回答のように読めるべきではありません。エラーは変わりません。stderr に JSON、stdout は空です。

### HTML 出力 {#html-output}

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

`--format html` は `--format md` と同じ値を 1 つの Web ページとして書き出します:

- 行数と列数、経過時間、結果のもとになった SQL（折りたたみ表示）。
- 列名とその型。数値は右寄せされ、`NULL` には印が付きます。
- 見出しをクリックすると並べ替えます。`NULL` は常に最後です。フィルター欄に入力すると、一致する行だけが残ります。
- `--limit` やセル数の上限で途中までになった結果は、Markdown と同じくその旨を表示します。

スタイルとスクリプトはインラインで、ページは何も取得しません。そのためディスクから直接開け、GitHub Pages などにそのまま公開できます。すべてのセルは HTML エスケープされます。

## クエリできる対象を把握する {#map-what-can-be-queried}

`ducklocal schema` は「何があり、その列は何か」を 1 回の呼び出しで答えます。`DESCRIBE` はリレーションを 1 つずつ答えるものです。エージェントが最初に実行すべきコマンドです。

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

PATH はウィンドウへのドロップと同じように展開されます。フォルダーのデータファイルは再帰的に（隠しファイルはスキップし、最大 256 件）、glob は一致したもの、データベースファイルは `--database` で指定した場合と同じように扱います。1 つの 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.table` |
| `kind` | `file`、`glob`、`table`、`view`、`workbook` のいずれか |
| `from` | それを読む SQL で、`FROM` の後にそのまま置けます。引用符で囲んだパス、または必要な場合は引用符で囲んだ識別子 |
| `rows` | テーブルではカタログの推定値、Parquet では正確な値（フッターから）、知るのにスキャンが必要な場合（CSV、JSON、ビュー）は `null` |
| `column_count`, `columns` | DuckDB が記述するとおりの列 |
| `files` | `glob` の場合、一致するファイル数 |

一致するものがすべて同じ形式の glob は 1 つのリレーションで、`.dash` の `source` が読むように読み取られます（`ducklocal schema 'logs/*.csv'`）。`--stats` もそれを 1 つとしてプロファイルします。形式が混在する glob とフォルダーは、ファイルを 1 つずつ一覧表示します。

小さいカタログは全体が返ります（`"detail": "full"`）。12 リレーションまたは 400 列を超えると、代わりに**サマリー**（`"detail": "summary"`）になります。行数が最も多い 5 つのリレーションは列を保持し、残りは名前、種類、行数、列数のみを一覧表示し、`without_columns` がその数を示します。さらに取得するには、`hint` が 2 つの方法を挙げます。1 つのリレーションには `--table NAME`（名前、裸のテーブル名、ファイル名で一致）、すべてには `--full` です。ワークブックはテーブル関数を持たないため、`sheets` とともに列なしで一覧表示されます。`--stats` は最初のシートを読みます。存在しない PATH、または何も指さない `--table` は終了コード 2 です。

`.json.gz` や `.csv.gz` のような gzip 圧縮されたテキストは、`source` ブロックやウィンドウと同様に、ここでもデータファイルとして扱われます。レコードが 1 つのリストに入っているファイル（たとえば CloudTrail の `{"Records": [...]}`）は、`hint` を付けて返ります。1 行 1 列のままではラッパーしか説明できないため、`hint` にはそのレコードを行として読む SQL が示されます。

## ファイルを調べて変換する

実際のファイルが存在することを確認した後で:

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

`amount` が存在すると推測しないでください。まず `ducklocal schema` または `DESCRIBE` を実行します。切り詰められたプレビューを合計するのではなく、SQL で全体の集計を計算します。CLI の呼び出しは、GUI の登録済みビューや、互いのインメモリテーブルを共有しません。必要な場合は明示的に永続化します:

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

データベースのロック競合はエラーです。もう一方の書き込み側（GUI を含む）を閉じるか、承認されたコピーを使います。ロックファイルを削除したり、別のデータベースを黙って作成したりしないでください。

## JSONL とネストした JSON {#jsonl-and-nested-json}

`read_ndjson_objects` は改行区切り JSON（1 行に 1 オブジェクト、`.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` だと述べますが、統計は小数点以下を 2 桁使っていること、最大値が中央値の 1000 倍であること、日付が途中で 11 日飛んでいることを示します。

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

`--stats` は 1 つのリレーションをプロファイルします。引数が指す唯一のもの、または `--table` が選ぶものです。`--table` なしで 2 つ以上を指定すると終了コード 2 になり、その旨のヒントが表示されます。`--full` とは併用できません。以前のリリースの `ducklocal profile TARGET [--database PATH]` は同じレポートで、引き続き動作します。

リレーションはデータファイル（`csv`、`tsv`、`txt`、`parquet`、`json`、`ndjson`、`jsonl`）、ワークブック（`xlsx`、`xls`、`xlsb`、`ods`。最初のシートが TEMP テーブルとしてインポートされ、プロファイルされます）、または `--database` がある場合はテーブル名かビュー名です。ドット付きの名前は `schema.table` として読まれ、各部分は引用符で囲まれるため、スペースや大文字を含む名前も書いたとおりに動作します。何も指さないリレーションは、SQL のエラーではなく引数のエラー（終了コード 2）です。

1 つの 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` | 列が保持する値そのもので、2 つの値の間の補間ではありません |
| `max_over_median` | 最大値が中央値の何倍か。線形軸と対数軸のどちらにするかを決める数値です |
| `covered_days`, `span_days`, `missing_days` | 列が示す日数、その両端の間の日数、その差。`0` は連続した系列で、それ以外は線が上を通ってしまう穴です |

`decimals`、`median`、`max_over_median` は数値の列に現れ、日のフィールドは日付とタイムスタンプに現れます。`LIST`、`STRUCT`、`MAP`、`UNION` の列は `nulls` のみを報告します。`min` と `max` はこれらには定義されていません。

数値と 1 つの短い単語（R の `NA` など）を含むテキスト列は、`null_marker` と `null_marker_rows` も報告します。その場合、レポートには列を数値として読む `read_csv` 呼び出しを示す `hint` が追加されます。

統計は正確でリレーション全体を読むため、フルスキャンのコストがかかります。`--limit` は適用されません。サンプルのプロファイルはプロファイルではありません。

## 実行中のウィンドウに作業を表示する {#show-work-in-the-running-window}

`ducklocal open` は、すでに実行中の DuckLocal ウィンドウに何かを渡し（なければ起動し）、そのウィンドウを前面に出します。エージェントが自分の作業を人の前に出し、そこから続けてもらうための方法です:

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

- PATH はウィンドウへのドロップと同じように開きます。`.dash` ファイルはタブ、DuckDB データベースファイルはウィンドウのデータベース、データファイル、フォルダー、glob はビューとしてアタッチされます。相対 PATH はコマンドのディレクトリを基準に解決されます。ウィンドウの起動中に届いたリクエストは、起動時の open が完了するまで待機します。
- `--sql` または `--sql-file`（`-` は標準入力を読む）は、`--title` というタイトルで新しいクエリタブを開きます。`--run` は PATH がアタッチされた後にそれを実行します。
- `--no-launch` はウィンドウを起動せずに、種類 `not_running` で失敗します。頼まれずにウィンドウが現れるのを好まないマシン向けです。

成功すると `{"delivered": true, "launched": BOOL}` を出力します。結果ではなく、配信の成否です。開かれたものはウィンドウ自身のセッション（その接続、アタッチされたビュー、履歴）で実行され、エラーは stdout ではなくそこに表示されます。引数のエラーは終了コード 2、それ以外は終了コード 1 で、種類は `not_running`（到達できるウィンドウがない）、`refused`（ウィンドウがリクエストを拒否した）、`launch` です。

ウィンドウはループバックポートで待ち受けます。ポートとランダムなトークンを、あなたのアカウントだけが読めるファイルに書き込みます（[設定とアプリデータ](settings-and-data.md#where-things-are-stored) を参照）。同じマシンの別のユーザーや、localhost を狙う Web ページからは到達できません。

### ウィンドウの表示内容を読み取る

`ducklocal open --state` は逆方向です。何も開かず、ウィンドウも起動せず、実行中のウィンドウが表示している内容を出力します。これにより、エージェントは人にクエリを貼り付けてもらう代わりに、人がやめたところから引き継げます。

```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`、および同じグラフをダッシュボードで描画する `query` ブロックと `plot` ブロックである `dash` です。
- `explain` は **Explain** が表示するものです。DuckDB の `EXPLAIN` 出力をテキスト行の配列にした `plan` と、`elapsed_ms` です。
- `profile` は **Profile** が表示するものです（[SQL エディタ](sql-editor.md) を参照）。`EXPLAIN ANALYZE` が計測した演算子ツリーをルートの配列にした `plan` で、各要素は `{operator, seconds, rows, estimated, children}` です。`seconds` は子を除いた演算子自身の時間、`rows` は生成した行数、`estimated` はオプティマイザーが推定した `rows`（プランに記載がない場合は `null`）、`children` は同じ形です。`operator_seconds` はすべての演算子自身の時間の合計で、シェアが合計する対象であり、実時間ではありません。`elapsed_ms` は実行全体です。
- **ダッシュボード** タブは `path`、`unsaved`、`dashboard` を持ちます。`dashboard` には `comments_file` のパス、`plots`（名前、種類、タイトル、クエリ、行数、`open_comments`、描画できない場合の `failure`）、および各フィルターが選んだ値を持つ `filters` があります。`filters` の各要素は `picked`、`value`（最初の値）、`values`（選ばれたすべての値、順序どおり）、`multiple` を持ちます。`value: null` と `picked: true` は NULL 値が選ばれたことを意味します。

`--state sales.dash` を使うとそのダッシュボードを表示しているタブだけを、`--state --active` を使うとアクティブなタブだけを取得できます。開いていないパスは終了コード 1、種類 `not_open` を返し、ヒントに開いているダッシュボードが示されます。`active_tab` は返された `tabs` 内でのアクティブなタブのインデックスで、そこに含まれない場合は `null` です。`database` と `attached` は引き続き含まれます。

`--state` は 1 つの `.dash` PATH か `--active` のどちらかを受け付け、両方は受け付けません。`--no-launch` は受け付けられますが何も変わりません。`--sql` や `--run` を含むその他のオプションは無効です（終了コード 2）。ウィンドウが起動していない場合は終了コード 1、種類 `not_running`、5 秒以内に応答しない場合は `timeout` です。

## ダッシュボードの仕様を検証する {#check-a-dashboard-spec}

形式そのもの（ブロック、属性、グラフの種類、SQL のルール、よくあるメッセージ）は [ダッシュボード（.dash）](dashboards.md) で説明しています。このセクションではコマンドについて説明します。

`.dash` ファイルは、Terraform がインフラを宣言するのと同じように、ダッシュボードをスクリプトで書くのではなく宣言します。クエリとグラフをブロックとして記述し、それらの間で参照します。人にもエージェントにも書きやすく、差分も取りやすい形式です。

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

`source` ブロックは、クエリが読むデータファイルを `.dash` ファイルからの相対パスで指定し、`view` ブロックは複数のクエリが共有する SQL を保持します。`query` ブロックは 1 つの `sql` 属性、つまりヒアドキュメントか文字列で書かれた 1 つの読み取り専用ステートメントを持ちます。`SELECT`、`WITH`、`FROM` で始まるもの、`VALUES`、`SHOW`、`DESCRIBE`、`SUMMARIZE`、`PIVOT` が受け付けられます。書き込みの可能性があるもの（DDL、DML、`COPY`、`ATTACH`、`INSTALL`）は診断となり、GUI はその実行を拒否します。ダッシュボードのクエリはファイルを開くたびに実行されるためです。`plot` ブロックは `type`（`line`、`bar`、`stacked_bar`、`area`、`scatter`、`pie`、`heatmap`、`histogram`、`map`、`timeline`、`table`、`card`、`text` のいずれか）、`query`（同じファイル内のクエリブロックへの `query.latency` のような参照）、その列、および省略可能な `title` と `width` を持ちます。`filter` ブロックは棒グラフや表をクリック可能にし、1 つの値、または棒グラフでは `multiple = true` で複数の値を選べるようにします。クエリは選ばれた値を `$name` として読み取ります。`#` と `//` は行末までコメントになります。すべての属性は [ダッシュボード（.dash）](dashboards.md) にあります。

`text` グラフは例外で、`title`、`text`、またはその両方を持ち、`query` を取りません。カードは `note` と `tone` も使えます。[カードとテキストパネル](dashboards.md#cards-and-text-panels) を参照してください。

まず静的チェックを行います。各クエリの SQL を、`query` が実行前に検証するのと同じ方法で、使い捨ての接続上で実際の DuckDB パーサーに通し、すべての `$name` をフィルターブロックと照合します。SQL は各 `$name` を `TRUE` として解析・実行されます。これはダッシュボードが何も選ばれる前に実行する内容です。

次に、すべてのクエリが、ダッシュボードを開いたときとまったく同じように実行され（読み取り専用、ソース付き、同じコードパスと同じ行予算）、各グラフの列がクエリが実際に返す列と照合されます。数値でない `y` はすべてのグラフの種類でエラーであり、map の数値でない座標や `size` も同様です。また、グラフのクエリが返さない `column` を持つフィルターもエラーです。

- **`--database` なし** の場合、クエリはメモリ内で実行されます。独自の `source` ファイルを使うダッシュボードにはこれで十分です。ソースが定義していないテーブルを読むクエリは、検証に渡されなかったデータベースを対象としている可能性があります。その場合は失敗ではなく `unresolved`（クエリ、行、理由）に一覧表示され、そのグラフの列はチェックされません。
- **`--database PATH` あり**（既存のファイル、読み取り専用）の場合、そのデータベース上で実行されます。クエリがデータベースのテーブルを読む場合は常に指定してください。`unresolved` にあるものはチェックされていません。

フィルターを読むすべてのクエリは、そのバリアントを実行することなく、選ばれた値でも束縛されます。これにより、最初の `$name = TRUE` のバージョンが動作していても、消費するクエリからフィルターの列が欠けていることを検出できます。フィルターは、それを選ぶグラフが返す列も参照している必要があります。

計画だけでなく実行することが重要です。ビルドが実行できないキャストや、変換できない値など、一部の失敗は行を読んだ後に初めて現れます。それらを見逃す検証は、描画できないダッシュボードを渡してしまうことになります。クエリは全体が実行されるため、大きなデータベースに対する検証はダッシュボードを開くのと同じくらいの時間がかかります。

成功すると、ファイルのソース（それぞれの `resolved` パス付き）、ビュー、クエリ（結果の列と `rows`、何も選ばれていない状態で返した行数、ダッシュボードの行予算で切られた場合は `truncated: true` 付き）、フィルター（それぞれを読む `queries` 付き）、グラフ、`unresolved`、および `empty`（実行されて 0 行を返したクエリ）を一覧表示する 1 つの JSON オブジェクトが返ります。空のクエリは他のすべてのチェックに合格しますが、通常は正規表現、フィルター、結合が何にも一致しなかったことを意味するため、それぞれを確認してください。`--summary` を指定すると、成功時は 1 行のコンパクトな JSON になります:

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

5 つのブロックのフィールドは件数です。`unresolved` はチェックできなかったクエリ、`empty` は 0 行を返したクエリを一覧表示します。

不具合のあるブロックは除外され、有効なブロックは検証を続けます。仕様のエラーとクエリの失敗は同じ実行で収集され、それぞれ 1 つの `file:line: message` になります。仕様の診断が 1 つでもある場合、終了コードは 2 で種類は `spec` です。SQL の実行または束縛だけが失敗する場合は、終了コードは 1 で種類は `sql` です。データベースと I/O の失敗も終了コード 1 です。`--summary` は診断を隠しません。

同じファイルは GUI でダッシュボードのタブとして開きます。`ducklocal dashboard.dash`、`ducklocal open dashboard.dash`、またはウィンドウへのドラッグです。グラフは 12 列のグリッドに配置され、描画できないグラフは理由をその場に表示します。[ダッシュボード（.dash）](dashboards.md) を参照してください。

## セマンティックモデルの指標 {#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` は Apache Ossie のモデル `model.ossie.yaml` を読み、その指標とフィールドを一覧表示します。`compile` はリクエストに答える DuckDB の `SELECT` を 1 つ出力し、データは読みません。`query` はそれを `ducklocal query` と同じように実行し、SQL とモデルの `sha256` を記した `semantic` オブジェクトを付けます。モデルが正確に答えられないリクエストは、`metric_fanout` などの `kind` 付きで拒否され、終了コードは 2 です。モデルの形式、すべてのオプション、すべての拒否理由は [セマンティック指標](metrics.md) にあります。

## ダッシュボードのレビューコメント {#review-comments-on-a-dashboard}

人はウィンドウでグラフにコメントすることでダッシュボードをレビューします。グラフにカーソルを合わせ、吹き出しをクリックします（[コメントでレビューする](dashboards.md#review-with-comments) を参照）。`ducklocal comments` はエージェント側で、ウィンドウなしでスレッドを読み、返信します。

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

- アクションを指定しない場合、開いているスレッドを出力します: `{file, comments_file, open, threads}`。`--all` は解決済みのものも含めます。
- 各スレッドには `id`、`plot`、およびエージェントが仕様内でそれを見つけるために必要な情報（`plot_title`、`plot_query`、`plot` ブロックの最初と最後の行である `plot_lines`（仕様が解析できない場合は `null`））があります。その名前のグラフが残っていない場合は `plot_missing` が `true` です。続いて `resolved` と `comments` があり、それぞれに `author`（`user` または `agent`）があり、エージェントのコメントには `name`（[`presence`](#agent-presence) が表示する名前）、`text`、`at`（RFC 3339、ローカル時刻）があります。
- `--reply ID --text TEXT` はエージェントの回答を追加します。解決済みのスレッドへの返信は、`--resolve` も指定しない限り、そのスレッドを再び開きます。
- `--resolve ID` と `--reopen ID` はスレッドの状態を変更します。`--add PLOT --text TEXT` はスレッドを開始し、エージェントとして署名します。
- スレッドの番号は ID として使えます。`--reply 1` は `c1` を意味します。`--add` は仕様にないグラフを拒否し（終了コード 2）、ヒントにそのグラフの一覧が表示されます。
- アクションは変更後の `{thread}` を出力します。

スレッドは仕様の隣の `FILE.comments.json` に保存されます。実行中のウィンドウは 1 秒以内に変更を検知し、グラフ上に表示します。不明なスレッド ID は終了コード 2 で、スレッドを一覧表示するヒントが付きます。存在しない仕様ファイルは終了コード 1 です。

レビューの流れを最初から最後まで: 開いているスレッドを読み、仕様を編集し、`ducklocal check` を実行し、変更内容を各スレッドに返信して `--resolve` します。人に質問を返したい場合は、`--resolve` なしで `--reply` を使います。

## エージェントのアクティビティを表示する {#agent-presence}

`check` と `comments` は、エージェントがどのダッシュボードで作業しているかを実行中のウィンドウに自動的に伝えます。`presence` は編集が行われる前にそれを通知できます:

```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` は `reading`、`editing`、`idle` を受け付けます（`done` は `idle` の別名です）。
- `--plot` はカンマ区切りのグラフ名を取ります。`editing` の場合、新しい名前も許可され、プレースホルダーとして表示されます。`reading` または `idle` の場合、不明な名前は終了コード 2 です。
- 表示される名前は `--agent`、次に `DUCKLOCAL_AGENT`、次に検出されたエージェント環境（Claude、Codex、Cursor、Gemini）から取得され、どれもなければ `Agent` になります。
- 出力は `{delivered}` です。実行中のウィンドウがない場合は、エラーもウィンドウの起動もなしに `{"delivered":false}` を返します。

コマンドがセッションをアクティブに保つ間、名前はダッシュボードの隅に表示されます。クリックするとアクティビティログが開きます。30 秒間の無音または `--doing idle` でセッションは終了します。変更・追加されたグラフは表示されるまでマークが残り、削除されたグラフの通知は閉じられるまで残ります。[エージェントの作業を表示する](dashboards.md#agent-presence) を参照してください。

## LSP でダッシュボードの仕様を編集する {#edit-a-dashboard-spec-with-lsp}

`ducklocal lsp` は、エディタが起動する `.dash` ファイル用の Language Server Protocol サーバーで、stdio 経由で動作します。LSP に対応したあらゆるエディタに、GUI 自体の仕様エディタと同じ機能を提供します:

- **診断**: `check` が報告するもので、開くたび、変更するたびに公開されます（ドキュメント全体の同期、すべて重大度 Error です。スタイルではなく誤りです）。
- **補完**: ブロックの種類、属性名、グラフの種類、`query.` と `plot.` の後の名前。それぞれに入力中の単語を置き換えるテキスト編集が付きます。
- **ホバー**: ブロック、属性、参照のドキュメント。
- **定義へ移動**: `query.name` または `plot.name` の参照から、そのブロックの名前に移動します。

`--database PATH` を指定すると、各クエリの SQL が `check --database` と同じ方法で、実際の DuckDB パーサーによって追加で検証されます。

エディタの汎用 LSP サポートを `*.dash` ファイルに対して `ducklocal lsp` に向けてください。このコマンドはドキュメント引数を取らず、エディタは stdio で通信します。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,
})
```

VS Code では、汎用 LSP 拡張機能がコマンド `ducklocal`、引数 `["lsp"]`、ドキュメントセレクター `dash` で同じことを行います。終了コード: 正常な `shutdown`/`exit` の後は **0**、クライアントがそれをせずに消えた場合は **1**、不正なコマンドラインまたはプロトコルハンドシェイクの失敗は **2** です。

## JSON の契約

成功したクエリは、stdout に 1 つの JSON オブジェクトを書き込み、その後ろに改行を付けます:

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

`columns` と各行は列の順序と重複した列名を保持します。`type` は **Arrow のデバッグ表現** であり、元の DuckDB SQL の型名ではありません（たとえば HUGEINT と DECIMAL が同じ Arrow のキャリアを共有できます）。`row_count` は返された行数を数えます。`total_rows` は生成された行数を数え、出力の上限の後に数えたものも含みます。`total_rows_exact: false` は最大 100,000 行の追加カウントの後に数えるのをやめたことを意味するため、その合計は下限です。どちらのカウントも影響を受けた行数ではありません。`elapsed_ms` は準備、実行、行のエンコードを計測し、ファイルの読み込みや接続の設定は含みません。0 行の結果もメタデータを保持します。DDL/DML は実際の DuckDB の結果を公開し、`Count` 列も含みます。INSERT/COPY は通常 `[[N]]` を返し、CREATE TABLE は通常行を返しません。最初の SQL キーワードから分類されることはありません。

セルのエンコード:

| SQL の値 | JSON のエンコード |
| --- | --- |
| NULL | `null`（文字列 `"NULL"` にはなりません） |
| Boolean、有限の float | JSON の真偽値/数値 |
| ±9,007,199,254,740,991 以内の整数 | JSON の数値 |
| それより大きい整数（HUGEINT/UHUGEINT を含む） | `{"encoding":"integer","value":"9007199254740992"}` |
| Decimal | `{"encoding":"decimal","value":"123.450"}`。正確な decimal のテキスト付き |
| テキスト、enum | JSON の文字列 |
| Blob、geometry | `{"encoding":"hex","value":"00ff"}`。小文字のバイト列、geometry は WKB を使用 |
| Date | `{"encoding":"date","unit":"Day","value":"1","iso":"1970-01-02"}`。1970-01-01 からの日数 |
| Timestamp | `{"encoding":"timestamp","unit":"Nanosecond","value":"123456789","iso":"1970-01-01T00:00:00.123456789"}`。Unix エポックからの符号付きカウント。単位は Second/Millisecond/Microsecond の場合もあります |
| Time | `{"encoding":"time","unit":"Microsecond","value":"123456","iso":"00:00:00.123456"}`。深夜 0 時からのカウント |
| Interval | `{"encoding":"interval","months":1,"days":2,"nanos":"3000"}` |
| NaN、正/負の無限大 | `{"encoding":"float","value":"NaN"}` / `"inf"` / `"-inf"` |
| List、array | JSON の配列で、再帰的にエンコードされます（ネストした null を含む） |
| Struct | `{"encoding":"struct","fields":[["name",VALUE],...]}` |
| Map | `{"encoding":"map","entries":[[KEY,VALUE],...]}`。JSON オブジェクトではないため、キーは型を保持します |
| Union | `{"encoding":"union-value","value":VALUE}`。アクティブな値のみで、メンバーのタグは保持されません |

時間値の `value` は正確なカウントであるため、小数の精度は失われません。日付/タイムスタンプの無限大のセンチネルは生のカウントのままです。それぞれの隣の `iso` は、読み取り用に ISO 8601 のテキストにした同じ値で、単位が保持するのと同じ桁数の小数部を持ちます。タイムゾーン付きの列（Arrow メタデータ）のタイムスタンプは UTC の瞬間で、その `iso` は `Z` で終わります。`--format md` も日付とタイムスタンプを読みやすく描画します。固定された DuckDB の Arrow ラッパーはネストした HUGEINT、UHUGEINT、DECIMAL(38,0) を区別できないため、null でない値が出現すると、符号や精度を黙って変える代わりに明確なエラーを出します。そのようなフィールドは SQL で明示的に VARCHAR にキャストしてください。未知の未サポートの型もエラーになります。エラーを空の結果と間違えないでください。Union のエンコードはアクティブな値の表現であり、ロスレスな union の往復ではありません。

エラーは **stderr** に 1 つの JSON オブジェクトを書き、stdout は空のままにします:

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

`hint` は、次のステップがこの CLI 自身の言葉でわかる場合に含まれます。綴りを間違えたフラグが意図していたフラグ、読み取り専用データベースで拒否された書き込みに対する `--read-write`、存在しないテーブルに対する `ducklocal schema`、変換できない値に対する `TRY_CAST`、複数のステートメントを含むスクリプトの分割、裸の列の別名として使われたキーワードに対する `AS`（`SELECT count(*) AS minutes`、または引用符で囲む）などです。エージェントは SQL を書き直す前にそれに従うべきです。構文エラーなど、DuckDB 自身のメッセージに付け加えることがない場合は含まれません。

終了コード: 成功は **0**、無効な引数やステートメント数は **2**、SQL、データベース、I/O、出力の失敗は **1** です。エラーの種類は `argument`、`sql`、`database`、`io`、`output`、`check` の場合は `spec`、`open` の場合は `not_running`、`not_open`、`refused`、`timeout`、`launch` です。stdout を解析する前に終了ステータスを確認し、完全性を報告する前に `truncated` を確認してください。ヘルプとバージョンはプレーンテキストの例外です。stdout のパイプが閉じられたなどの転送の失敗は、空または完全な出力ストリームを保証できません。

## 公式スキルをインストールする {#install-the-official-skill}

このスキルは、エージェントの回答を誠実に保つ習慣を教えます。スキーマを確認し、上限付きのサンプルをプレビューし、SQL で集計を計算し、`truncated` を確認し、返された値から答えます。スキーマの確認、列の統計、変換、データベースのクエリ、`.dash` ダッシュボードとそのレビューコメント、ウィンドウへの作業の受け渡しと読み戻しを扱います。S3 のブラウズ、空間専用のコマンド、セッションの記憶、MCP サーバーは提供しません。

**アプリから。** **コマンドラインと AI…**（タイトルバーのロボットボタン、または DuckLocal メニュー）を開きます:

- **コマンドをインストール** は `ducklocal` を `PATH` に追加し、エージェントのシェルから実行できるようにします。
- **Claude Code に追加** はスキルを `~/.claude/skills/ducklocal` に書き込み、Claude Code がすべてのプロジェクトで見つけられるようにします。書き込まれるのはスキル自身の 2 つのファイルだけです。そのフォルダーにある他のものは保持されます。DuckLocal の更新で新しいスキルが提供されると、ダイアログに **スキルを更新** が表示されます。
- **概要をコピー** は、他のエージェント（Codex、Cursor、チャットウィンドウ）向けの短い説明をコピーします。説明にはコマンド名とその使い方が含まれます。

**手動で。** スキルは [`skills/ducklocal`](https://github.com/JetSquirrel/ducklocal/tree/main/skills/ducklocal) です。代わりに 1 つのプロジェクトに追加する場合（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/
```

ローカルの変更を上書きする前に、既存の出力先を確認してください。他のエージェントは、サポートされているスキルディレクトリで同じ `SKILL.md` と `references/cli.md` を使えます。
