CLI

pip install d2b-sdk (PyPI, código en GitHub) instala también el comando d2b (en entornos con pyenv se recomienda pipx install d2b-sdk / uvx --from d2b-sdk d2b — evita accidentes con la resolución de shims). La salida es JSON (stdout), los errores llevan suggested_fix incluido por stderr y los códigos de salida son 0 / 1 (error de API, rechazo de sincronización) / 2 (uso). No hay prompts interactivos.

Autenticación

El login por navegador es el modo por defecto (no manipulas la clave de API en crudo):

d2b login   # por defecto https://d2b.dev (--base-url / $D2B_BASE_URL para otro despliegue)
# → 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 siempre está ligado a exactamente una cuenta (un token = una cuenta). La página de aprobación preselecciona tu cuenta predeterminada; cada cuenta de desarrollador que añadas recibe su propio token. Sin --account se usa el token de la cuenta predeterminada.

Un token de login alcanza resource=account: toda la cuenta a la que está ligado — en la cuenta predeterminada, tu workspace personal más los workspaces de equipo de los que eres miembro activo; en una cuenta de desarrollador, todos los workspaces que esa cuenta financia. d2b workbooks create --workspace-id … puede crear en cualquiera de ellos, y workspace_name en la respuesta dice dónde cayó. El alcance lo fija solo ese pin; los scopes dicen qué puede hacer el token (workspaces:read es el permiso del plano de control para leer la configuración de workspaces y no cambia el alcance). Indicar en --workspace-id un workspace fuera del alcance devuelve 403 tanto al listar como al crear (d2b workspaces list muestra el alcance). Si necesitas una credencial confinada a un workspace, emite una clave con resource: "workspace:<id>" en la consola o vía POST /api/v1/me/tokens y úsala mediante D2B_API_KEY.

En entornos no interactivos como CI o agentes puedes usar variables de entorno (precedencia: flags > env > login guardado). No pases la clave de API como argumento de línea de comandos (--api-key no se acepta, e incluso en los mensajes de error se ocultan las cadenas con forma de secreto).

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

Comandos 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 es   # hallazgos con evidencia (--agent: verificados, con resumen)
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

Ida y vuelta con git

d2b pull / d2b push / d2b github-workflow — Gestionar workbooks con git.

Notas para el uso desde agentes

• En agentes con timeouts de Bash cortos, el flujo en 2 pasos “upload asíncrono → jobs wait” es más seguro que upload --wait
• Si una escritura devuelve 409 (ConflictError): relee edit_version con d2b tables rows NAME --workbook $WB, reaplica el cambio y reintenta (sin sobrescritura automática)
• El snippet para pegar en el repositorio está en Uso desde agentes de programación

--wait y el async=true de la API

CLI	API	Comportamiento
d2b upload FILE --wait	POST .../sources?async=true + sondeo del job	aceptado con 202, espera a que termine (solo modo auto)
d2b upload FILE (sin --wait)	igual, sin sondeo	devuelve un job_id — espera con d2b jobs wait JOB_ID
--mode staged	sin async (siempre síncrono)	los bytes aterrizan al instante; --wait sobra (y es error de uso)

Cuando un mensaje de error dice async, se refiere al parámetro de la API — en la CLI corresponde a --wait (esos errores incluyen además suggested_fix_cli con vocabulario de CLI, que la CLI muestra).

Guía de instalación (pip / pipx / uvx)

• Como comando: pipx install d2b-sdk o uvx --from d2b-sdk d2b (evita accidentes con shims de pyenv)
• Como dependencia del proyecto: uv add d2b-sdk + uv run d2b
• Como biblioteca (import desde Python): pip install d2b-sdk

Las tablas derivadas también se crean desde la CLI: d2b transforms create NAME --workbook WB --sql-file f.sql --arg src=table (los placeholders {{ src }} + --arg mantienen el lineage). Elimina un workbook que ya no necesites con d2b workbooks delete ID (requiere workbooks:delete, que un login predeterminado incluye).