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 key):

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

令牌始终只绑定一个账户(一个令牌 = 一个账户)。审批页面默认勾选你的默认账户；每额外勾选一个开发者账户就会签发一个令牌。省略 --account 时使用默认账户的令牌。

登录令牌的可达范围是 resource=account，即所绑定的整个账户 — 默认账户下是你的个人工作区加上你作为活跃成员的团队工作区；开发者账户下是该账户出资的全部工作区。d2b workbooks create --workspace-id … 可以在其中任何一个里创建，响应中的 workspace_name 说明落在了哪里。可达范围只由这个 pin 决定；scope 决定令牌能做什么（workspaces:read 是控制面读取工作区设置的权限，不改变可达范围）。在 --workspace-id 里指定一个不可达的工作区，列表和创建都会返回 403（d2b workspaces list 显示可达范围）。如果需要一个只限于单个工作区的凭据，请在控制台或通过 POST /api/v1/me/tokens 签发 resource: "workspace:<id>" 的密钥，并通过 D2B_API_KEY 使用。

在 CI、Agent 等非交互环境中可以使用环境变量(优先级: flag > env > 已保存的登录)。不要把 API key 作为命令行参数传递(不接受 --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 zh   # 有依据的问题(--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 管理 workbook。

从 Agent 使用时的注意事项

• 对 Bash 超时较短的 Agent,比起 upload --wait,“异步 upload → jobs wait”的两段式更稳妥
• 写入遇到 409(ConflictError)时: 用 d2b tables rows NAME --workbook $WB 重新读取 edit_version,重新应用改动后再执行(不自动覆盖)
• 要贴进仓库的片段见在编码 Agent 中使用

--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，默认登录已包含)。