CLI

pip install d2b-sdk(PyPI, 소스는 GitHub)로 d2b 커맨드도 함께 설치됩니다(pyenv 환경에서는 pipx install d2b-sdk / uvx --from d2b-sdk d2b 권장 — shim 해석 사고를 피할 수 있습니다). 출력은 JSON(stdout), 에러는 suggested_fix를 포함해 stderr, 종료 코드는 0 / 1(API 에러·동기화 거부) / 2(사용법)입니다. 대화형 프롬프트는 없습니다.

인증

브라우저 로그인이 기본입니다(원시 API 키를 손으로 다루지 않음):

d2b login   # 기본 접속 대상은 https://d2b.dev (다른 환경은 --base-url / $D2B_BASE_URL)
# → a confirmation code and URL appear and the browser opens. Check the code on
#   screen matches the terminal, tick the accounts this CLI may act for, then
#   approve. One token is issued per account and stored at
#   ~/.config/d2b/credentials.json (0600).
#   CLI tokens live 90 days — just `d2b login` again when they expire.
d2b login --scopes workbooks:read,workbooks:write
#   Default is the whole workbooks family — read + write + delete — so the CLI
#   can delete the workbooks it creates; pass --scopes only to narrow (e.g. read-only).
d2b whoami                  # includes account_id / account_name / workspace_name
d2b workspaces list         # the workspaces this credential reaches, by name (is_default = where creates land)
d2b --account acc-… whoami  # switch accounts when several were approved ($D2B_ACCOUNT_ID works too)
d2b logout   # forgets the saved login and revokes every server-side token

토큰은 항상 정확히 하나의 계정에 고정됩니다(1 토큰 = 1 계정). 승인 화면에는 기본 계정이 미리 선택되어 있고, 추가로 허용한 개발자 계정마다 토큰이 하나씩 발급됩니다. --account 를 생략하면 기본 계정의 토큰이 사용됩니다.

로그인 토큰의 도달 범위는 resource=account, 즉 고정된 계정 전체입니다 — 기본 계정이면 개인 워크스페이스와 자신이 활성 멤버인 팀 워크스페이스, 개발자 계정이면 그 계정이 자금원인 모든 워크스페이스. d2b workbooks create --workspace-id … 는 그중 어디에든 만들 수 있고, 응답의 workspace_name 이 착지 위치입니다. 도달 범위를 정하는 것은 이 핀뿐이며 scope 는 「무엇을 할 수 있는가」를 정합니다(workspaces:read 는 컨트롤 플레인의 워크스페이스 설정 읽기 권한으로, 범위를 바꾸지 않습니다). 닿지 않는 워크스페이스를 --workspace-id 에 지정하면 목록·생성 모두 403 입니다(닿는 범위는 d2b workspaces list). 하나의 워크스페이스에 갇힌 자격 증명이 필요하면 콘솔 또는 POST /api/v1/me/tokens 에서 resource: "workspace:<id>" 키를 발급해 D2B_API_KEY 로 사용하세요.

CI·에이전트 등 비대화형 환경에서는 환경 변수를 사용할 수 있습니다(우선순위: 플래그 > env > 저장된 로그인). API 키를 커맨드라인 인수로 전달하지 마십시오(--api-key는 받지 않으며, 에러 메시지에서도 시크릿 형태의 문자열은 가려집니다).

export D2B_API_KEY=d2b_pat_... D2B_BASE_URL=https://d2b.dev

주요 커맨드

d2b workbooks create --title monthly          # → {"id": "..."}
d2b workbooks list
d2b upload sales.xlsx --workbook WB --wait    # async ingest + job wait
d2b tables list --workbook WB
d2b tables schema sales --workbook WB --json-schema
d2b tables rows sales --workbook WB --limit 50
d2b tables a1 sales A1:D10 --workbook WB    # read in Excel coordinates
d2b tables write-a1 sales B2:C3 '[[10],[20]]' --workbook WB --expected-version 12
d2b tables add-column sales with_tax --type DOUBLE --workbook WB
d2b tables set-formula equipment utilization "{units_active} / {units_total}" --workbook WB
d2b query 'SELECT count(*) FROM "sales"' --workbook WB
d2b review --workbook WB --table sales --lang ko   # 근거가 있는 지적 (--agent: 검증된 지적과 요약)
d2b export --workbook WB --format xlsx -o out.xlsx
d2b sources render report.xlsx --workbook WB -o monthly.xlsx   # original formatting
d2b sources revise equipment.xlsx --workbook WB --transform-name merge_sites --range A3:N8 --sql-file merge.sql -o out.xlsx
d2b sheets list --workbook WB
d2b sheets put report --spec sheet.json --workbook WB   # blocks: heading / text / table_view / spacer
d2b sheets render report --workbook WB -o report.xlsx
d2b transforms list --workbook WB
d2b charts list --workbook WB
d2b versions commit 2026-06 --workbook WB
d2b versions revert 2026-06 --workbook WB
d2b jobs wait JOB_ID --timeout 1800

git과의 왕복

d2b pull / d2b push / d2b github-workflow — 워크북을 git으로 관리하기.

에이전트에서 사용할 때의 주의

• Bash 타임아웃이 짧은 에이전트에서는 upload --wait보다 “비동기 upload → jobs wait”의 2단계가 안전합니다
• 쓰기가 409(ConflictError)가 되면: d2b tables rows NAME --workbook $WB로 edit_version을 다시 읽고, 변경을 재적용해 재실행합니다(자동 덮어쓰기는 하지 않음)
• 리포지토리에 붙여 넣는 스니펫은 코딩 에이전트에서 사용하기

--wait 와 API 의 async=true

CLI	API	동작
d2b upload FILE --wait	POST .../sources?async=true + job 폴링	202 로 접수 후 완료까지 대기(auto 모드 전용)
d2b upload FILE(--wait 없음)	동일(폴링 없음)	job_id 반환 — d2b jobs wait JOB_ID 로 대기
--mode staged	async 없음(항상 동기)	바이트만 저장하고 즉시 응답. --wait 는 불필요(붙이면 사용법 오류)

오류 메시지에 async 가 보이면 API 파라미터 이야기입니다 — CLI 에서는 --wait 가 대응합니다(해당 오류는 CLI 어휘의 suggested_fix_cli 도 함께 보내며, CLI 는 그것을 표시합니다).

설치 가이드(pip / pipx / uvx)

• 명령으로: pipx install d2b-sdk 또는 uvx --from d2b-sdk d2b(pyenv shim 사고 방지)
• 프로젝트 의존성으로: uv add d2b-sdk + uv run d2b
• 라이브러리로(Python import): pip install d2b-sdk

파생 테이블은 CLI 에서도 만들 수 있습니다: d2b transforms create NAME --workbook WB --sql-file f.sql --arg src=table({{ src }} 플레이스홀더 + --arg 바인딩으로 lineage 유지). 더 이상 필요 없는 워크북은 d2b workbooks delete ID 로 삭제합니다(workbooks:delete 필요 — 기본 로그인에 포함).