CLI

pip install d2b-sdk (PyPI, código no GitHub) também instala o comando d2b (em ambientes com pyenv, recomendamos pipx install d2b-sdk / uvx --from d2b-sdk d2b — evita acidentes de resolução de shims). A saída é JSON (stdout), os erros vão para o stderr com suggested_fix, e os exit codes são 0 / 1 (erro de API, recusa de sync) / 2 (uso incorreto). Não há prompts interativos.

Autenticação

O login pelo navegador é o padrão (você nunca manuseia a API key crua):

d2b login   # padrão: https://d2b.dev (--base-url / $D2B_BASE_URL para outro ambiente)
# → 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

Um token está sempre vinculado a exatamente uma conta (um token = uma conta). A página de aprovação pré-seleciona sua conta padrão; cada conta de desenvolvedor adicionada recebe seu próprio token. Sem --account, é usado o token da conta padrão.

Um token de login alcança resource=account: toda a conta à qual está vinculado — na conta padrão, seu workspace pessoal mais os workspaces de equipe dos quais você é membro ativo; numa conta de desenvolvedor, todos os workspaces que essa conta financia. d2b workbooks create --workspace-id … pode criar em qualquer um deles, e workspace_name na resposta diz onde caiu. O alcance é definido só por esse pin; os scopes dizem o que o token pode fazer (workspaces:read é a permissão do plano de controle para ler configurações de workspaces e não muda o alcance). Indicar em --workspace-id um workspace fora do alcance devolve 403 tanto ao listar quanto ao criar (d2b workspaces list mostra o alcance). Se precisar de uma credencial confinada a um workspace, emita uma chave com resource: "workspace:<id>" no console ou via POST /api/v1/me/tokens e use-a por D2B_API_KEY.

Em ambientes não interativos, como CI e agentes, use variáveis de ambiente (precedência: flags > env > login salvo). Não passe a API key como argumento de linha de comando (--api-key não é aceito, e strings com formato de segredo são ocultadas até nas mensagens de erro).

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

Principais comandos

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 pt   # apontamentos com evidência (--agent: verificados, com resumo)
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 e volta com git

d2b pull / d2b push / d2b github-workflow — Gerenciar workbooks com git.

Observações ao usar a partir de agentes

Para agentes com timeout de Bash curto, o fluxo em 2 etapas “upload assíncrono → jobs wait” é mais seguro do que upload --wait
Se uma escrita retornar 409 (ConflictError): releia o edit_version com d2b tables rows NAME --workbook $WB, reaplique as mudanças e execute de novo (sem sobrescrever automaticamente)
O snippet para colar no repositório está em Usar a partir de agentes de codificação

`--wait` e o `async=true` da API

CLI	API	Comportamento
`d2b upload FILE --wait`	`POST .../sources?async=true` + polling do job	aceito com 202, aguarda a conclusão (apenas modo auto)
`d2b upload FILE` (sem `--wait`)	idem, sem polling	devolve um `job_id` — aguarde com `d2b jobs wait JOB_ID`
`--mode staged`	sem `async` (sempre síncrono)	os bytes aterrissam na hora; `--wait` é desnecessário (e erro de uso)

Quando uma mensagem de erro cita async, trata-se do parâmetro da API — na CLI o correspondente é --wait (esses erros também trazem suggested_fix_cli no vocabulário da CLI, que a CLI exibe).

Guia de instalação (pip / pipx / uvx)

Como comando: pipx install d2b-sdk ou uvx --from d2b-sdk d2b (evita acidentes com shims do pyenv)
Como dependência do projeto: uv add d2b-sdk + uv run d2b
Como biblioteca (import em Python): pip install d2b-sdk

Tabelas derivadas também podem ser criadas pela CLI: d2b transforms create NAME --workbook WB --sql-file f.sql --arg src=table (placeholders {{ src }} + vínculos --arg mantêm o lineage rastreável). Remova um workbook desnecessário com d2b workbooks delete ID (requer workbooks:delete, que um login padrão inclui).

CLI