CLI

pip install d2b-sdk(PyPI、ソースは GitHub)で d2b コマンドも入ります(pyenv 環境では pipx install d2b-sdk / uvx --from d2b-sdk d2b 推奨 — シム解決の事故を避けられます)。出力は JSON(stdout)、エラーは suggested_fix 込みで stderr、終了コードは 0 / 1(API エラー・同期拒否)/ 2(使い方)。対話プロンプトはありません。

認証

ブラウザログインが既定です(生の API キーを手で扱わない):

d2b login   # 既定の接続先は https://d2b.dev(別の環境は --base-url / $D2B_BASE_URL)
# → 確認コードと URL が表示され、ブラウザが開く。画面のコードが
#   ターミナルと一致することを確認し、この CLI に許可するアカウントを
#   選んで「承認」。トークンはアカウントごとに 1 本発行され、
#   ~/.config/d2b/credentials.json (0600) に保存される。
#   CLI トークンの有効期限は 90 日 — 切れたら `d2b login` し直すだけ。
d2b login --scopes workbooks:read,workbooks:write
#   既定は workbooks の read + write + delete(CLI で作った workbook を CLI で消せる)。
#   読み取り専用など狭いトークンにしたいときだけ --scopes で絞る。
d2b whoami                  # account_id / account_name / workspace_name まで返る
d2b workspaces list         # この資格情報が届くワークスペースを名前付きで(is_default = 作成先)
d2b --account acc-… whoami  # 複数アカウントを許可した場合の切り替え($D2B_ACCOUNT_ID でも可)
d2b logout   # 保存を消し、サーバ側のトークンも全て失効

トークンは必ず 1 つのアカウントに固定されます(1 トークン = 1 アカウント)。承認画面では既定アカウントが選択済みで、開発者アカウントを追加で許可するとその数だけトークンが発行されます。--account を省略すると既定アカウントのトークンが使われます。

ログインのトークンの到達範囲は resource=account、つまり固定されたアカウント全体です — 既定アカウントなら個人ワークスペースと自分がアクティブメンバーの team ワークスペース、開発者アカウントならそのアカウントが資金元のワークスペース全部。d2b workbooks create --workspace-id … はそのどれにでも作成でき、応答の workspace_name が着地先です。到達範囲を決めるのはこのピンだけで、スコープは「何ができるか」を決めます(workspaces:read はコントロールプレーンのワークスペース設定を読む権限で、範囲を変えません)。届かないワークスペースを --workspace-id に指定すると一覧も作成も 403 になります(届く範囲は d2b workspaces list)。1 つのワークスペースに閉じた資格情報が要るときは、コンソールか 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    # 非同期 ingest + job 待機
d2b tables list --workbook WB
d2b tables schema 売上明細 --workbook WB --json-schema
d2b tables rows 売上明細 --workbook WB --limit 50
d2b tables a1 売上明細 A1:D10 --workbook WB    # Excel 座標で読む
d2b tables write-a1 売上明細 B2:C3 '[[10],[20]]' --workbook WB --expected-version 12
d2b tables add-column 売上明細 税込 --type DOUBLE --workbook WB
d2b tables set-formula 設備内訳 稼働率 "{稼働台数} / {総数}" --workbook WB
d2b query 'SELECT count(*) FROM "売上明細"' --workbook WB
d2b review --workbook WB --table 売上明細 --lang ja   # 根拠付きの指摘(--agent で検証済みの指摘と要約)
d2b export --workbook WB --format xlsx -o out.xlsx
d2b sources render report.xlsx --workbook WB -o monthly.xlsx   # 元の書式で出力
d2b sources revise 設備.xlsx --workbook WB --transform-name 統合 --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 poll	202 で受けて完了まで待つ(auto のみ)
d2b upload FILE(--wait なし)	同上(poll なし)	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 のシム事故を避けられます)
• プロジェクト依存として: 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 — 既定のログインは保持)。