CLI

pip install d2b-sdk (PyPI, sources sur GitHub) installe aussi la commande d2b (sous pyenv, préférez pipx install d2b-sdk / uvx --from d2b-sdk d2b — vous éviterez les accidents de résolution de shims). La sortie est du JSON (stdout), les erreurs sortent sur stderr avec suggested_fix, et les codes de sortie sont 0 / 1 (erreur API, refus de synchronisation) / 2 (mauvais usage). Aucun prompt interactif.

Authentification

La connexion par navigateur est le défaut (aucune clé API en clair à manipuler) :

d2b login   # cible par défaut : https://d2b.dev (--base-url / $D2B_BASE_URL pour un autre déploiement)
# → 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

Un token est toujours lié à exactement un compte (un token = un compte). La page d’approbation présélectionne votre compte par défaut ; chaque compte développeur ajouté reçoit son propre token. Sans --account, le token du compte par défaut est utilisé.

Un jeton de connexion atteint resource=account : tout le compte auquel il est lié — pour le compte par défaut, votre workspace personnel plus les workspaces d’équipe dont vous êtes membre actif ; pour un compte développeur, tous les workspaces financés par ce compte. d2b workbooks create --workspace-id … peut créer dans n’importe lequel, et workspace_name dans la réponse dit où il a atterri. Seul ce pin fixe la portée ; les scopes disent ce que le jeton peut faire (workspaces:read est la permission du plan de contrôle pour lire les paramètres des workspaces et ne change pas la portée). Nommer dans --workspace-id un workspace hors de portée renvoie 403, à la liste comme à la création (d2b workspaces list montre la portée). S’il vous faut un identifiant confiné à un workspace, émettez une clé avec resource: "workspace:<id>" dans la console ou via POST /api/v1/me/tokens et utilisez-la via D2B_API_KEY.

Dans les environnements non interactifs (CI, agents…), les variables d’environnement fonctionnent (priorité : flags > env > login enregistré). Ne passez pas de clé API en argument de ligne de commande (--api-key n’est pas accepté, et les chaînes ayant la forme d’un secret sont caviardées des messages d’erreur).

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

Commandes principales

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 fr   # constats étayés (--agent : vérifiés, avec un résumé)
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

L’aller-retour avec git

d2b pull / d2b push / d2b github-workflow — Gérer les workbooks avec git.

Remarques pour l’usage depuis un agent

Pour les agents au timeout Bash court, le duo « upload asynchrone → jobs wait » est plus sûr qu’upload --wait
Si une écriture renvoie 409 (ConflictError) : relisez l’edit_version avec d2b tables rows NAME --workbook $WB, réappliquez vos changements et réexécutez (pas d’écrasement automatique)
Le snippet à coller dans un dépôt : Utiliser D2B depuis un agent de codage

`--wait` et le `async=true` de l’API

CLI	API	Comportement
`d2b upload FILE --wait`	`POST .../sources?async=true` + sondage du job	accepté en 202, attend la fin (mode auto uniquement)
`d2b upload FILE` (sans `--wait`)	idem, sans sondage	renvoie un `job_id` — attendez avec `d2b jobs wait JOB_ID`
`--mode staged`	pas d’`async` (toujours synchrone)	les octets atterrissent immédiatement ; `--wait` est inutile (et une erreur d’usage)

Quand un message d’erreur mentionne async, il s’agit du paramètre de l’API — côté CLI c’est --wait (ces erreurs incluent aussi suggested_fix_cli en vocabulaire CLI, que la CLI affiche).

Guide d’installation (pip / pipx / uvx)

Comme commande : pipx install d2b-sdk ou uvx --from d2b-sdk d2b (évite les accidents de shims pyenv)
Comme dépendance du projet : uv add d2b-sdk + uv run d2b
Comme bibliothèque (import Python) : pip install d2b-sdk

Les tables dérivées se créent aussi depuis la CLI : d2b transforms create NAME --workbook WB --sql-file f.sql --arg src=table (les placeholders {{ src }} + --arg gardent le lineage traçable). Supprimez un workbook devenu inutile avec d2b workbooks delete ID (nécessite workbooks:delete, inclus dans une connexion par défaut).

CLI