CLI

pip install d2b-sdk (PyPI, Quellcode auf GitHub) installiert auch den Befehl d2b (in pyenv-Umgebungen empfiehlt sich pipx install d2b-sdk / uvx --from d2b-sdk d2b — das vermeidet Unfälle bei der Shim-Auflösung). Ausgabe ist JSON (stdout), Fehler gehen inklusive suggested_fix nach stderr, Exit-Codes sind 0 / 1 (API-Fehler, abgelehnter Sync) / 2 (Usage). Interaktive Prompts gibt es nicht.

Authentifizierung

Standard ist der Browser-Login (rohe API-Keys nie von Hand anfassen):

d2b login   # Standardziel: https://d2b.dev (--base-url / $D2B_BASE_URL für eine andere Umgebung)
# → 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

Ein Token ist immer an genau ein Konto gebunden (ein Token = ein Konto). Die Freigabeseite hat das Standardkonto vorausgewählt; jedes zusätzlich angehakte Entwicklerkonto erhält ein eigenes Token. Ohne --account wird das Token des Standardkontos verwendet.

Ein Login-Token erreicht resource=account: das ganze Konto, an das es gebunden ist — beim Standardkonto Ihren persönlichen Workspace plus die Team-Workspaces, in denen Sie aktives Mitglied sind; bei einem Entwicklerkonto jeden Workspace, den dieses Konto finanziert. d2b workbooks create --workspace-id … kann in jedem davon anlegen; workspace_name in der Antwort nennt das Ziel. Die Reichweite bestimmt allein dieser Pin; Scopes legen fest, was das Token darf (workspaces:read ist die Control-Plane-Berechtigung zum Lesen von Workspace-Einstellungen und ändert die Reichweite nicht). Ein Workspace außerhalb der Reichweite in --workspace-id ergibt 403 — beim Auflisten wie beim Anlegen (d2b workspaces list zeigt die Reichweite). Brauchen Sie ein auf einen Workspace begrenztes Credential, stellen Sie in der Konsole oder über POST /api/v1/me/tokens einen Key mit resource: "workspace:<id>" aus und nutzen ihn per D2B_API_KEY.

In nicht-interaktiven Umgebungen wie CI oder Agenten lassen sich Umgebungsvariablen verwenden (Vorrang: Flag > env > gespeicherter Login). API-Keys niemals als Kommandozeilenargument übergeben (--api-key wird nicht akzeptiert, und Strings in Secret-Form werden auch in Fehlermeldungen geschwärzt).

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

Die wichtigsten Befehle

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 de   # belegte Befunde (--agent: geprüft, mit Zusammenfassung)
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

Roundtrip mit git

d2b pull / d2b push / d2b github-workflow — Workbooks mit git verwalten.

Hinweise für den Einsatz aus Agenten

• Bei Agenten mit kurzen Bash-Timeouts ist der zweistufige Weg „asynchroner upload → jobs wait“ sicherer als upload --wait
• Liefert ein Schreibvorgang 409 (ConflictError): mit d2b tables rows NAME --workbook $WB die edit_version neu lesen, die Änderung erneut anwenden und noch einmal ausführen (kein automatisches Überschreiben)
• Das Snippet zum Einfügen ins Repository steht in Aus Coding-Agenten nutzen

--wait und das async=true der API

CLI	API	Verhalten
d2b upload FILE --wait	POST .../sources?async=true + Job-Polling	mit 202 angenommen, wartet auf Abschluss (nur auto-Modus)
d2b upload FILE (ohne --wait)	dito, ohne Polling	liefert eine job_id — warten mit d2b jobs wait JOB_ID
--mode staged	kein async (immer synchron)	Bytes landen sofort; --wait ist unnötig (und ein Bedienfehler)

Wenn eine Fehlermeldung async nennt, ist der API-Parameter gemeint — in der CLI entspricht das --wait (solche Fehler tragen zusätzlich suggested_fix_cli im CLI-Vokabular, das die CLI anzeigt).

Installations-Leitfaden (pip / pipx / uvx)

• Als Kommando: pipx install d2b-sdk oder uvx --from d2b-sdk d2b (vermeidet pyenv-Shim-Unfälle)
• Als Projektabhängigkeit: uv add d2b-sdk + uv run d2b
• Als Bibliothek (Python-Import): pip install d2b-sdk

Abgeleitete Tabellen lassen sich auch direkt per CLI anlegen: d2b transforms create NAME --workbook WB --sql-file f.sql --arg src=table ({{ src }}-Platzhalter + --arg-Bindungen halten die Lineage nachvollziehbar). Nicht mehr benötigte Workbooks entfernt d2b workbooks delete ID (erfordert workbooks:delete, das ein Standard-Login enthält).