콘텐츠로 이동

AI CLI와 공식 스킬 ​

작업 중심의 개요는 로컬 데이터를 위한 AI 에이전트용 SQL을 참고하세요. 이 페이지는 명령과 출력에 대한 전체 레퍼런스입니다.

창 없이 실행하기 ​

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

명령하는 일
ducklocal querySQL 문 하나를 실행하고 결과를 JSON으로 출력합니다
ducklocal schema쿼리할 수 있는 대상을 열과 함께 나열합니다. --stats를 주면 한 릴레이션의 열 통계를 보여 줍니다
ducklocal openSQL, 대시보드, 데이터를 실행 중인 창에 표시합니다. --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에서 추가되었으며 에이전트 워크플로에서 다룹니다. metrics와 --format html은 0.4.1보다 새로운 기능으로, main 브랜치에 있으며 다음 릴리스에 포함됩니다. metrics는 시맨틱 지표에서 다룹니다.

ducklocal query는 GUI, 기록, 등록된 파일, 언어 설정, GUI 전역 연결을 초기화하지 않고 SQL을 실행합니다. 호출할 때마다 전용 연결을 만듭니다. 명령 없이, 또는 파일 경로와 디렉터리, glob 패턴만으로 DuckLocal을 실행하면 일반 GUI가 열립니다. 명령 이름(query, schema, open, check, metrics, comments, propose, project, session, presence, profile, lsp)과 같은 이름의 GUI 경로를 열려면 ./query처럼 ./를 앞에 붙입니다.

명령 설치하기 ​

DuckLocal은 Apple silicon에서 macOS 12 이상, Windows(x86_64), Linux(x86_64)를 지원합니다. CLI는 애플리케이션 실행 파일에서 직접 동작하므로 별도의 DuckDB CLI 바이너리를 설치할 필요가 없습니다.

PATH에 추가하는 가장 빠른 방법은 앱에서 하는 것입니다(0.1.1 이상). 명령줄 및 AI…(제목 표시줄의 로봇 버튼 또는 DuckLocal 메뉴)를 열고 명령 설치를 클릭합니다. 같은 대화상자에서 AI 에이전트용 스킬도 설치합니다. 자세한 내용은 공식 스킬 설치하기를 참고하세요. 설치를 건너뛰려면 실행 파일이 있는 위치에서 호출합니다:

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 지원은 함께 포함되어 있으며 쿼리 시점에 다운로드하지 않습니다.

쿼리 옵션 ​

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 출력을 참고하세요. 다른 것은 바뀌지 않습니다: 같은 SQL, 같은 한도, 같은 오류.
  • 반복되거나 알 수 없는 플래그, 값 누락, 빈 SQL, 잘못된 한도는 오류입니다. 옵션은 --flag=value가 아니라 별도의 값을 사용합니다. 상대 경로는 SQL 파일 디렉터리가 아니라 프로세스 작업 디렉터리를 기준으로 해석됩니다. 셸 경로는 따옴표로 감싸고, SQL 안에서는 작은따옴표를 두 번 씁니다('O''Brien.csv'). SQL 식별자는 큰따옴표를 씁니다.

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

Markdown 출력 ​

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

값렌더링 방식
NULLNULL
integer, decimal, float값이 지닌 숫자를 정확히 — DECIMAL(38,10)은 스케일을 유지하고 NaN/inf/-inf는 그대로 표기합니다
DATEYYYY-MM-DD
TIMESTAMPYYYY-MM-DD HH:MM:SS[.fffffffff], 소수부는 값에 있을 때만, 값이 가진 만큼의 자릿수로. 시간대는 붙지 않으며 --format json은 원시 카운트를 유지합니다
TIMEHH:MM:SS[.ffffff]
INTERVALDuckDB가 쓰는 방식대로: 1 month 2 days 00:00:00.000003
BLOB, GEOMETRY0x00ff, 길면 …로 생략
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 출력 ​

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

--format html은 --format md와 같은 값을 하나의 웹 페이지로 씁니다:

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

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

쿼리할 수 있는 것 파악하기 ​

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
kindfile, glob, table, view, workbook
from그것을 읽는 SQL로, FROM 뒤에 바로 쓸 수 있습니다: 따옴표로 감싼 경로, 또는 필요할 때 따옴표로 감싼 식별자
rows테이블이면 카탈로그의 추정치, Parquet이면 정확한 값(푸터 기준), 알려면 스캔이 필요한 경우 null — CSV, JSON, 뷰
column_count, columnsDuckDB가 기술하는 열
filesglob이면 일치하는 파일 수

일치 항목이 모두 한 형식인 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 ​

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, typeDESCRIBE가 보고하는 그대로
nulls그 열이 NULL인 행
distinct추정이 아닌 정확한 값
uniquedistinct가 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은 적용되지 않습니다. 표본의 프로파일은 프로파일이 아닙니다.

실행 중인 창에 작업 표시하기 ​

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입니다.

창은 루프백 포트에서 수신합니다. 포트와 무작위 토큰을 본인 계정만 읽을 수 있는 파일에 기록합니다(설정 및 앱 데이터 참고). 같은 머신의 다른 사용자나 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 편집기 참고): 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입니다.

대시보드 명세 검증하기 ​

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

.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)에 있습니다.

text 플롯은 예외입니다: title, text 또는 둘 다를 담고 query를 받지 않습니다. 카드는 note와 tone도 쓸 수 있습니다. 카드와 텍스트 패널을 참고하세요.

먼저 정적 검사가 있습니다: 각 쿼리의 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)를 참고하세요.

시맨틱 모델의 지표 ​

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입니다. 모델 형식, 모든 옵션, 모든 거부 사유는 시맨틱 지표에 있습니다.

대시보드의 리뷰 주석 확인하기 ​

사람들은 창에서 플롯에 주석을 달아 대시보드를 리뷰합니다. 플롯에 마우스를 올리고 말풍선을 클릭하세요(주석으로 리뷰하기 참고). 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가 보여 주는 이름), 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를 사용하세요.

에이전트 활동 표시하기 ​

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이 세션을 끝냅니다. 변경되거나 추가된 플롯은 볼 때까지, 제거된 플롯 알림은 닫을 때까지 표시가 남습니다. 에이전트가 작업하는 모습 보기를 참고하세요.

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 인코딩
NULLnull (문자열 "NULL"이 아님)
Boolean, finite floatJSON boolean/number
±9,007,199,254,740,991 이내의 정수JSON number
더 큰 정수, HUGEINT/UHUGEINT 포함{"encoding":"integer","value":"9007199254740992"}
Decimal정확한 decimal 텍스트와 함께 {"encoding":"decimal","value":"123.450"}
Text, enumJSON 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, arrayJSON 배열, 재귀적으로 인코딩(중첩 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 파이프 같은 전송 실패는 빈/완전한 출력 스트림을 보장할 수 없습니다.

공식 스킬 설치하기 ​

이 스킬은 에이전트에게 답을 정직하게 유지하는 습관을 가르칩니다: 스키마를 살펴보고, 제한된 표본을 미리 보고, SQL에서 집계를 계산하고, truncated를 확인하고, 반환된 값으로 답합니다. 스키마 검사와 열 통계, 변환, 데이터베이스 쿼리, .dash 대시보드와 그 리뷰 주석, 창에 작업을 넘기고 다시 읽어 오기를 다루며, S3 탐색이나 공간 전용 명령, 세션 메모리, MCP 서버는 제공하지 않습니다.

앱에서. 명령줄 및 AI…(제목 표시줄의 로봇 버튼 또는 DuckLocal 메뉴)를 엽니다:

  • 명령 설치는 ducklocal을 PATH에 넣어 에이전트의 셸이 그것을 실행할 수 있게 합니다.
  • Claude Code에 추가는 스킬을 ~/.claude/skills/ducklocal에 기록하여 Claude Code가 모든 프로젝트에서 찾게 합니다. 스킬 자체의 두 파일만 기록되며 그 폴더의 다른 것은 유지됩니다. DuckLocal 업데이트가 더 새로운 스킬을 포함하면 대화상자가 스킬 업데이트를 제안합니다.
  • 브리프 복사는 Codex, Cursor, 채팅 창 등 다른 에이전트를 위해 명령과 사용 방법을 설명하는 짧은 글을 복사합니다.

직접 설치. 스킬은 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를 지원하는 스킬 디렉터리에서 사용할 수 있습니다.

Apache-2.0 라이선스로 공개되었습니다.