# AI CLI와 공식 스킬

> DuckLocal DuckDB SQL CLI를 AI 에이전트와 함께 사용하세요. 로컬 파일 스키마를 살펴보고, 문 하나를 실행하고, GUI나 서버 없이 제한된 JSON을 반환합니다.

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

작업 중심의 개요는 [로컬 데이터를 위한 AI 에이전트용 SQL](https://ducklocal.app/use-cases/ai-agent-sql/)을 참고하세요. 이 페이지는 명령과 출력에 대한 전체 레퍼런스입니다.

## 창 없이 실행하기

`ducklocal --help`는 열 개의 하위 명령을 나열합니다:

| 명령 | 하는 일 |
| --- | --- |
| `ducklocal query` | SQL 문 하나를 실행하고 결과를 JSON으로 출력합니다 |
| `ducklocal schema` | 쿼리할 수 있는 대상을 열과 함께 나열합니다. `--stats`를 주면 한 릴레이션의 열 통계를 보여 줍니다 |
| `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을 실행합니다. 호출할 때마다 전용 연결을 만듭니다. 명령 없이, 또는 파일 경로와 디렉터리, glob 패턴만으로 DuckLocal을 실행하면 일반 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이어야 하며 `-`는 stdin을 읽습니다. SQL은 정확히 하나의 문을 포함해야 합니다. 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`은 하나의 독립된 웹 페이지로 렌더링합니다. [HTML 출력](#html-output)을 참고하세요. 다른 것은 바뀌지 않습니다: 같은 SQL, 같은 한도, 같은 오류.
- 반복되거나 알 수 없는 플래그, 값 누락, 빈 SQL, 잘못된 한도는 오류입니다. 옵션은 `--flag=value`가 아니라 별도의 값을 사용합니다. 상대 경로는 SQL 파일 디렉터리가 아니라 프로세스 작업 디렉터리를 기준으로 해석됩니다. 셸 경로는 따옴표로 감싸고, SQL 안에서는 작은따옴표를 두 번 씁니다(`'O''Brien.csv'`). SQL 식별자는 큰따옴표를 씁니다.

**읽기 전용은 파일 시스템이나 네트워크 샌드박스가 아닙니다.** `COPY` 같은 SQL은 데이터베이스가 읽기 전용이어도 파일을 쓸 수 있습니다. 실행 전에 출력 경로와 덮어쓰기, 데이터베이스 변경, 확장 기능 설치, 외부 접근을 승인하세요. DuckLocal은 확장 기능을 자동으로 설치하거나 작업을 재시도하지 않습니다. 승인을 받으면 명시적 `INSTALL`/`LOAD` SQL은 여전히 가능하며, 설치된 확장 기능은 자동 로드될 수 있습니다. 실패한 명령이 이미 부작용을 일으켰을 수 있으므로(예: 출력 실패 전) 재시도하기 전에 대상을 살펴보세요.

### Markdown 출력

`--format md`는 렌더링일 뿐 두 번째 계약이 아닙니다. 값은 JSON이 담고 있는 그대로이며, 결과 그리드가 보여 주는 방식으로 기록됩니다.

| 값 | 렌더링 방식 |
| --- | --- |
| `NULL` | `NULL` |
| integer, 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`와 같은 값을 하나의 웹 페이지로 씁니다:

- 행 수와 열 수, 경과 시간, 결과를 만든 SQL(접힌 상태).
- 열 이름과 타입. 숫자는 오른쪽 정렬되고 `NULL`은 표시됩니다.
- 헤더를 클릭하면 정렬되며 `NULL`은 항상 마지막에 남습니다. 필터 상자에 입력하면 일치하는 행만 남습니다.
- `--limit`이나 셀 예산 때문에 잘린 결과는 Markdown과 마찬가지로 그 사실을 알립니다.

스타일과 스크립트는 인라인이고 페이지는 아무것도 가져오지 않으므로, 디스크에서 바로 열 수 있고 GitHub Pages 같은 곳에 그대로 게시할 수 있습니다. 모든 셀은 HTML 이스케이프됩니다.

## 쿼리할 수 있는 것 파악하기 {#map-what-can-be-queried}

`ducklocal schema`는 "무엇이 있고 그 열은 무엇인가?"를 한 번의 호출로 답하며, `DESCRIBE`는 그것을 한 릴레이션씩 답합니다. 에이전트가 가장 먼저 실행해야 하는 명령입니다.

```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`로 준 것과 같습니다. 하나의 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이면 정확한 값(푸터 기준), 알려면 스캔이 필요한 경우 `null` — CSV, JSON, 뷰 |
| `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`(이름, 기본 테이블 이름, 파일 이름으로 일치), 전부에는 `--full`. 워크북은 테이블 함수가 없으므로 `sheets`와 함께 열 없이 나열되고, `--stats`는 첫 시트를 읽습니다. 존재하지 않는 PATH나 아무것도 가리키지 않는 `--table`은 종료 코드 2입니다.

`.json.gz`, `.csv.gz`처럼 gzip으로 압축된 텍스트는 여기서도 데이터 파일입니다. `source` 블록과 창에서도 마찬가지입니다. 레코드가 하나의 목록에 들어 있는 파일(예를 들어 CloudTrail의 `{"Records": [...]}`)은 `hint`와 함께 반환됩니다. 그 한 행과 한 열만으로는 껍데기만 설명되므로, `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(한 줄에 객체 하나, `.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`이라고 말하지만, 그 통계는 그 열이 소수 두 자리를 쓰고, 최댓값이 중앙값의 천 배이며, 날짜가 중간에 11일을 건너뛴다고 알려 줍니다.

```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입니다. `--full`과 함께 쓸 수 없습니다. 이전 릴리스의 `ducklocal profile TARGET [--database PATH]`는 같은 보고서이며 여전히 동작합니다.

릴레이션은 데이터 파일 — `csv`, `tsv`, `txt`, `parquet`, `json`, `ndjson`, `jsonl` — 이거나 워크북(`xlsx`, `xls`, `xlsb`, `ods`; 첫 시트를 TEMP 테이블로 가져와 프로파일링)이거나, `--database`와 함께면 테이블이나 뷰 이름입니다. 점이 있는 이름은 `schema.table`로 읽고 각 부분을 따옴표로 감싸므로 공백이나 대문자가 있는 이름도 쓴 그대로 동작합니다. 아무것도 가리키지 않는 릴레이션은 SQL 오류가 아니라 인수 오류(종료 코드 2)입니다.

하나의 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`은 숫자 열에 나타나고, 날짜 관련 필드는 날짜와 타임스탬프에 나타납니다. `LIST`, `STRUCT`, `MAP`, `UNION` 열은 `nulls`만 보고합니다 — `min`과 `max`는 이들에 정의되지 않습니다.

숫자와 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는 명령의 디렉터리를 기준으로 해석됩니다. 창이 아직 시작 중일 때 도착한 요청은 시작 시 열기가 끝날 때까지 기다립니다.
- `--sql` 또는 `--sql-file`(`-`은 stdin을 읽음)은 `--title` 제목으로 새 쿼리 탭을 엽니다. `--run`은 PATH가 연결된 뒤 그것을 실행합니다.
- `--no-launch`는 창을 시작하지 않고 종류 `not_running`으로 실패합니다 — 창이 묻지도 않고 나타나는 것이 반갑지 않은 머신을 위한 것입니다.

성공하면 `{"delivered": true, "launched": BOOL}`을 출력합니다. 결과가 아니라 전달입니다. 열리는 것은 창 자체의 세션 — 그 연결, 연결된 뷰, 기록 — 에서 실행되며 어떤 오류도 stdout이 아니라 그곳에 표시됩니다. 인수 오류이면 종료 코드 2, 종류 `not_running`(도달 가능한 창 없음), `refused`(창이 요청을 거부), `launch`이면 1입니다.

창은 루프백 포트에서 수신합니다. 포트와 무작위 토큰을 본인 계정만 읽을 수 있는 파일에 기록합니다([설정 및 앱 데이터](settings-and-data.md#where-things-are-stored) 참고). 같은 머신의 다른 사용자나 localhost를 겨냥한 웹 페이지는 여기에 접근할 수 없습니다.

### 창이 보여 주는 내용 읽기

`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 탭에서 열을 고르면 결과에 `chart`도 붙습니다: `type`, `x`, `y`, `split`, 그리고 같은 차트를 대시보드에서 그리는 `query`와 `plot` 블록인 `dash`.
- `explain`은 **Explain**이 보여 주는 것입니다: `plan`(DuckDB `EXPLAIN` 출력을 텍스트 줄 배열로)과 `elapsed_ms`.
- `profile`은 **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`. `filters`에는 `picked`, `value`(첫 값), `values`(고른 모든 값, 순서대로), `multiple`이 있습니다. `picked: true`와 함께 `value: null`이면 NULL 값이 선택된 것입니다.

`--state sales.dash`로 그 대시보드를 보여 주는 탭만 남기거나, `--state --active`로 활성 탭만 볼 수 있습니다. 열려 있지 않은 경로는 힌트에 열린 대시보드를 담아 종료 코드 1, 종류 `not_open`을 반환합니다. `active_tab`은 반환된 `tabs` 안에서 활성 탭의 인덱스이며, 그 안에 없으면 `null`입니다. `database`와 `attached`는 그대로 포함됩니다.

`--state`는 `.dash` PATH 하나 또는 `--active` 중 하나만 받고 둘 다는 받지 않습니다. `--no-launch`는 받아들이지만 아무것도 바꾸지 않습니다. `--sql`과 `--run`을 포함한 다른 옵션은 유효하지 않습니다(종료 코드 2). 창이 없으면 종류 `not_running`, 5초 안에 응답하지 않으면 `timeout`으로 종료 코드 1입니다.

## 대시보드 명세 검증하기 {#check-a-dashboard-spec}

형식 자체 — 블록, 속성, 플롯 유형, SQL 규칙, 흔한 메시지 — 는 [대시보드(.dash)](dashboards.md)에서 설명하며, 이 절은 명령을 다룹니다.

`.dash` 파일은 Terraform이 인프라를 선언하듯 대시보드를 선언합니다 — 쿼리와 플롯을 블록으로, 그 사이의 참조로 — 스크립트로 작성하는 것이 아닙니다. 사람이나 에이전트가 쓰고 diff하기 쉽습니다.

```hcl
query "latency" {
  sql = <<SQL
    SELECT timestamp, service, avg(latency) AS latency
    FROM logs
    GROUP BY timestamp, service
  SQL
}

plot "latency" {
  type   = "line"
  query  = query.latency
  x      = timestamp
  y      = latency
  series = service
}
```

```bash
ducklocal check dashboard.dash
ducklocal check dashboard.dash --database warehouse.duckdb
ducklocal check dashboard.dash --summary
```

`source` 블록은 쿼리가 읽을 데이터 파일을 `.dash` 파일 기준 상대 경로로 지정하고, `view` 블록은 여러 쿼리가 공유하는 SQL을 담습니다. `query` 블록은 `sql` 속성 하나 — 읽기 전용 문 하나, heredoc 또는 문자열 — 를 담습니다. `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` 블록은 막대 차트나 표를 클릭 가능하게 하고 — 값 하나, 또는 막대에서 `multiple = true`로 여러 값 — 쿼리는 선택 값을 `$name`으로 읽습니다. `#`과 `//`는 줄 끝까지 주석입니다. 모든 속성은 [대시보드(.dash)](dashboards.md)에 있습니다.

`text` 플롯은 예외입니다: `title`, `text` 또는 둘 다를 담고 `query`를 받지 않습니다. 카드는 `note`와 `tone`도 쓸 수 있습니다. [카드와 텍스트 패널](dashboards.md#cards-and-text-panels)을 참고하세요.

먼저 정적 검사가 있습니다: 각 쿼리의 SQL을 일회용 연결에서 실제 DuckDB 파서로(`query`가 실행 전에 검증하는 방식대로), 그리고 모든 `$name`을 필터 블록과 대조합니다 — SQL은 각 `$name`을 `TRUE`로 하여 파싱되고 실행됩니다. 이것이 대시보드가 아무것도 선택되기 전에 실행하는 방식입니다.

그다음 모든 쿼리가 대시보드를 열 때와 정확히 같은 방식으로 — 읽기 전용으로, 그 소스와 함께, 같은 코드 경로와 행 예산을 거쳐 — 실행되고, 각 플롯의 열이 쿼리가 실제로 반환하는 열과 대조됩니다. 숫자가 아닌 `y`는 모든 차트 유형에서 오류이며, 지도의 숫자가 아닌 좌표나 `size`도, 플롯의 쿼리가 반환하지 않는 필터 `column`도 마찬가지입니다.

- **`--database` 없이** 쿼리는 인메모리에서 실행되며, 자체 `source` 파일만 가진 대시보드에는 이것으로 충분합니다. 어떤 소스도 정의하지 않은 테이블을 읽는 쿼리는 검사에 주어지지 않은 데이터베이스를 위한 것일 수 있습니다. 그런 쿼리는 실패가 아니라 `unresolved`(쿼리, 줄, 이유) 아래 나열되고 그 플롯의 열은 검사되지 않습니다.
- **`--database PATH`와 함께**(기존 파일, 읽기 전용) 그 데이터베이스에서 실행됩니다. 쿼리가 데이터베이스의 테이블을 읽는다면 항상 지정하세요. `unresolved`에 있는 것은 검사되지 않았습니다.

필터를 읽는 모든 쿼리는 그 변형을 실행하지 않은 채 선택된 값으로도 바인딩됩니다. 이는 초기 `$name = TRUE` 버전이 동작하더라도 소비 쿼리에서 빠진 필터 열을 잡아냅니다. 필터는 또한 자신을 고르는 플롯이 반환하는 열을 참조해야 합니다.

계획만 세우는 것이 아니라 실행하는 것이 중요합니다. 빌드가 수행할 수 없는 캐스트나 변환되지 않는 값 같은 일부 실패는 행을 읽은 뒤에야 나타나며, 이를 통과시키는 검사는 그릴 수 없는 대시보드를 넘겨주게 됩니다. 쿼리는 전체가 실행되므로 큰 데이터베이스에 대한 검사는 대시보드를 여는 데 걸리는 시간만큼 걸립니다.

성공하면 파일의 소스(각 `resolved` 경로 포함), 뷰, 쿼리(결과 열과 `rows`, 아무것도 선택되지 않은 상태에서 각각 반환한 수, 대시보드의 행 예산으로 잘렸으면 `truncated: true`), 필터(각각을 읽는 `queries`), 플롯, `unresolved`, `empty`(실행되었지만 행을 반환하지 않은 쿼리)를 나열하는 하나의 JSON 객체입니다. 빈 쿼리는 다른 모든 검사를 통과하지만 보통 아무것도 일치하지 않은 정규식이나 필터, 조인일 수 있으니 하나씩 확인하세요. `--summary`를 주면 성공은 한 줄의 압축된 JSON입니다:

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

다섯 블록 필드는 개수이고, `unresolved`는 검사할 수 없었던 쿼리를, `empty`는 행을 반환하지 않은 쿼리를 나열합니다.

문제가 있는 블록은 제외되고 유효한 블록은 검증을 계속 진행합니다. 명세 오류와 쿼리 실패는 같은 실행에서 각각 `file:line: message`로 모입니다. 명세 진단이 하나라도 있으면 종료 코드 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` 하나를 출력하며 데이터는 읽지 않습니다. `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_lines`(`plot` 블록의 첫 줄과 마지막 줄, 명세가 파싱되지 않으면 `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에 정확히 하나의 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`은 원래 DuckDB SQL 타입 이름이 아니라 **Arrow 디버그 표현**입니다(예를 들어 HUGEINT와 DECIMAL은 같은 Arrow 캐리어를 공유할 수 있습니다). `row_count`는 반환된 행을 셉니다. `total_rows`는 출력 한도 이후에 센 것까지 포함해 산출된 행을 세며, `total_rows_exact: false`는 최대 100,000개 추가 행 이후 집계가 멈췄음을 뜻하므로 그 총계는 하한입니다. 어느 쪽도 affected 행 수가 아닙니다. `elapsed_ms`는 준비와 실행, 행 인코딩을 측정하며 파일 로딩이나 연결 설정은 포함하지 않습니다. 행이 없는 결과도 메타데이터를 유지합니다. DDL/DML은 `Count` 열을 포함해 실제 DuckDB 결과를 노출합니다: INSERT/COPY는 보통 `[[N]]`을 반환하고 CREATE TABLE은 보통 행이 없습니다. 첫 SQL 키워드로 분류하지 않습니다.

셀 인코딩:

| SQL 값 | JSON 인코딩 |
| --- | --- |
| NULL | `null` (문자열 `"NULL"`이 아님) |
| Boolean, finite float | JSON boolean/number |
| ±9,007,199,254,740,991 이내의 정수 | JSON number |
| 더 큰 정수, HUGEINT/UHUGEINT 포함 | `{"encoding":"integer","value":"9007199254740992"}` |
| Decimal | 정확한 decimal 텍스트와 함께 `{"encoding":"decimal","value":"123.450"}` |
| Text, enum | JSON string |
| 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 epoch 이후 부호 있는 카운트; 단위는 Second/Millisecond/Microsecond일 수도 있습니다 |
| Time | `{"encoding":"time","unit":"Microsecond","value":"123456","iso":"00:00:00.123456"}`; 자정 이후 카운트 |
| 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**에 하나의 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** 잘못된 인수/문 개수, **1** SQL, 데이터베이스, I/O 또는 출력 실패. 오류 종류는 `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가 모든 프로젝트에서 찾게 합니다. 스킬 자체의 두 파일만 기록되며 그 폴더의 다른 것은 유지됩니다. DuckLocal 업데이트가 더 새로운 스킬을 포함하면 대화상자가 **스킬 업데이트**를 제안합니다.
- **브리프 복사**는 Codex, Cursor, 채팅 창 등 다른 에이전트를 위해 명령과 사용 방법을 설명하는 짧은 글을 복사합니다.

**직접 설치.** 스킬은 [`skills/ducklocal`](https://github.com/JetSquirrel/ducklocal/tree/main/skills/ducklocal)에 있습니다. 대신 단일 프로젝트에 추가하려면(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`를 지원하는 스킬 디렉터리에서 사용할 수 있습니다.
