---
type: Project Guide
title: ceciliobooks/qbcli
description: "qbcli entry point: commands, rules for every task, where each topic lives."
resource: https://github.com/ceciliobooks/qbcli
tags: [agents, workflow]
---
# ceciliobooks/qbcli
LLM-operable CLI `qb`: migrates a QBD Company file into QBO through the Intuit SDK and APIs. Built for the Cecilio Books QBD → QBO migration service. Scope decided: every Intuit API, in phases ([ADR-0001](https://github.com/ceciliobooks/qbcli/blob/HEAD/docs/adr/0001-qb-covers-every-intuit-api-in-phases.md)).
## Commands
Stack (owner preference, as in our `gapi` CLI): TypeScript 7 (strict) · Node 24 (`.nvmrc`) · Biome 2 · pnpm 12 (pinned via `packageManager`). pnpm, not npm. Node runs TypeScript directly: no build step (npm package: JavaScript emitted at `pnpm pack`, [CLI surface › Package](https://github.com/ceciliobooks/qbcli/blob/HEAD/docs/cli.md#package)). Run the CLI as `node bin/qb.ts <args>` ([CLI surface](https://github.com/ceciliobooks/qbcli/blob/HEAD/docs/cli.md)).
- **Gate before every PR:** `pnpm lint` (0 warnings) · `pnpm typecheck` · `pnpm test`. All green ([CONTRIBUTING.md](https://github.com/ceciliobooks/qbcli/blob/HEAD/CONTRIBUTING.md)).
## Rules for every task
- **Domain words** from [CONTEXT.md](https://github.com/ceciliobooks/qbcli/blob/HEAD/CONTEXT.md), verbatim, in code, issues, PRs.
- **Client data never enters git**: Backup, Snapshot, Decisions file, Plan ([data handling](https://github.com/ceciliobooks/qbcli/blob/HEAD/docs/data-handling.md)).
- **No third-party runtime dependency**: Node built-ins only; libraries are guides ([ADR-0009](https://github.com/ceciliobooks/qbcli/blob/HEAD/docs/adr/0009-agent-technical-choices.md)).
- **Intuit names, verbatim**: a command is the Intuit call it makes ([ADR-0009](https://github.com/ceciliobooks/qbcli/blob/HEAD/docs/adr/0009-agent-technical-choices.md)).
- **QBD side read-only today**: QuickBooks grants read-only access; Bridge forwards only `*QueryRq`; qbXML version negotiated per session ([Architecture › Bridge](https://github.com/ceciliobooks/qbcli/blob/HEAD/docs/architecture.md#bridge)). Read + write decided ([ADR-0005](https://github.com/ceciliobooks/qbcli/blob/HEAD/docs/adr/0005-qbd-box-and-web-connector-operator-picks.md)), to build.
- **One key path**: every Intuit call goes through crm; no `qb oauth`, no local token store (#306).
- **QBO writes**: migration only through Apply with a confirmed Plan hash, one crm Plan per run, one e-mailed code in production ([CLI behaviour](https://github.com/ceciliobooks/qbcli/blob/HEAD/docs/cli-behaviour.md#behaviour)); per-entity writes through crm behind the Confirmation matrix ([ADR-0002](https://github.com/ceciliobooks/qbcli/blob/HEAD/docs/adr/0002-maximum-access-human-confirmation-separate.md), [ADR-0003](https://github.com/ceciliobooks/qbcli/blob/HEAD/docs/adr/0003-approval-by-email-code-outside-agent-reach.md)): list entities built (`qb qbo create`, `update`, `qb crm approve`, #302); sales entities built (+ `void`, `delete`, `send`, `pdf`, #303); purchase and entry entities + `qb qbo batch`, `upload` built (#304). **Agent proof** writes: Sandbox; production test Client "test" (Realm `9341458537342180`) = production, a write waits for Confirmation ([ADR-0002](https://github.com/ceciliobooks/qbcli/blob/HEAD/docs/adr/0002-maximum-access-human-confirmation-separate.md)). Intuit migration tool: one migration recipe; into a Client Realm only behind Confirmation, which warns that it overwrites the whole company ([ADR-0006](https://github.com/ceciliobooks/qbcli/blob/HEAD/docs/adr/0006-pieces-and-ready-made-recipes.md)).
- **API wins**: a probe result beats an Intuit page; code follows what the API does (owner, 2026-10-19).
- **Decision authority** ([ADR-0007](https://github.com/ceciliobooks/qbcli/blob/HEAD/docs/adr/0007-who-decides-what.md)): agent settles facts it proves (probe, code read) and technical choices that change nothing the owner sees or pays, by the gold standard, and records each; change to the owner's request, to what the Client sees, or to cost → owner first; never work around a request. A closed map or owner decision stays closed.
- **Software licensing out of scope**: Windows, QBD, any vendor; never raise, research, or gate on it (owner, 2026-10-21: "licensiamento de software NAO ENTRA mais nessa spec").
- **Unverified Intuit fact** (⚠ + owner issue in [QBD capabilities](https://github.com/ceciliobooks/qbcli/blob/HEAD/docs/capabilities.md) or [QBO capabilities](https://github.com/ceciliobooks/qbcli/blob/HEAD/docs/capabilities-qbo.md)) → its owner ticket proves it before code depends on it.
- **Ticket ready** only per the [Definition of Ready](https://github.com/ceciliobooks/qbcli/blob/HEAD/docs/agents/issue-tracker.md#definition-of-ready).
- **Follow [CONTRIBUTING.md](https://github.com/ceciliobooks/qbcli/blob/HEAD/CONTRIBUTING.md)** for every change.
## Read on demand
| When you… | Read |
|---|---|
| need what QBD allows | [docs/capabilities.md](https://github.com/ceciliobooks/qbcli/blob/HEAD/docs/capabilities.md) |
| need what QBO allows, Preferences | [docs/capabilities-qbo.md](https://github.com/ceciliobooks/qbcli/blob/HEAD/docs/capabilities-qbo.md) |
| need what each QBO Subscription allows | [docs/capabilities-qbo-subscriptions.md](https://github.com/ceciliobooks/qbcli/blob/HEAD/docs/capabilities-qbo-subscriptions.md) |
| touch a module, the pipeline, Bridge, Snapshot | [docs/architecture.md](https://github.com/ceciliobooks/qbcli/blob/HEAD/docs/architecture.md) |
| touch a mapper, a transaction type owner | [docs/mapping.md](https://github.com/ceciliobooks/qbcli/blob/HEAD/docs/mapping.md) |
| touch Verify, a Baseline report, a Tie-out check | [docs/tieout.md](https://github.com/ceciliobooks/qbcli/blob/HEAD/docs/tieout.md) |
| touch the QBO client, crm client, qbXML module | [docs/intuit-clients.md](https://github.com/ceciliobooks/qbcli/blob/HEAD/docs/intuit-clients.md) |
| need a wire or Snapshot format (Bridge messages, request log, Snapshot) | [docs/formats.md](https://github.com/ceciliobooks/qbcli/blob/HEAD/docs/formats.md) |
| need a pipeline file format (Decisions file, Plan file, Name clash list, Assessment, Tie-out result) | [docs/pipeline-formats.md](https://github.com/ceciliobooks/qbcli/blob/HEAD/docs/pipeline-formats.md) |
| need an Apply file format (Apply result, Batch settlement file) | [docs/apply-formats.md](https://github.com/ceciliobooks/qbcli/blob/HEAD/docs/apply-formats.md) |
| run, add, or name a `qb` command, flag, exit code | [docs/cli.md](https://github.com/ceciliobooks/qbcli/blob/HEAD/docs/cli.md) |
| need what a `qb` command does, its gates, its output | [docs/cli-behaviour.md](https://github.com/ceciliobooks/qbcli/blob/HEAD/docs/cli-behaviour.md) |
| do a QuickBooks or Intuit task, migration included (Extract to Verify, human stop points); run `qb` with no qbcli checkout | [skills/quickbooks-epic/SKILL.md](https://github.com/ceciliobooks/qbcli/blob/HEAD/skills/quickbooks-epic/SKILL.md) |
| create, drive, or reset the Box | [docs/box.md](https://github.com/ceciliobooks/qbcli/blob/HEAD/docs/box.md) |
| need Intuit developer access, keys, OAuth, metering | [docs/intuit-developer.md](https://github.com/ceciliobooks/qbcli/blob/HEAD/docs/intuit-developer.md) |
| handle a Backup, Snapshot, secret | [docs/data-handling.md](https://github.com/ceciliobooks/qbcli/blob/HEAD/docs/data-handling.md) |
| scope a lead before a quote | [docs/presale/](https://github.com/ceciliobooks/qbcli/blob/HEAD/docs/presale/index.md) |
| need a decision's *why* | [docs/adr/](https://github.com/ceciliobooks/qbcli/blob/HEAD/docs/adr/index.md) |
| need the dated research and its sources | [docs/research/](https://github.com/ceciliobooks/qbcli/blob/HEAD/docs/research/index.md) |
| add or edit a doc | [docs/agents/writing-docs.md](https://github.com/ceciliobooks/qbcli/blob/HEAD/docs/agents/writing-docs.md) |
## Agent skills
- **Issue tracker:** GitHub Issues via `gh` → [docs/agents/issue-tracker.md](https://github.com/ceciliobooks/qbcli/blob/HEAD/docs/agents/issue-tracker.md).
- **Triage labels:** five canonical roles → [docs/agents/triage-labels.md](https://github.com/ceciliobooks/qbcli/blob/HEAD/docs/agents/triage-labels.md).
- **Domain docs:** single-context; ADR convention → [docs/agents/domain.md](https://github.com/ceciliobooks/qbcli/blob/HEAD/docs/agents/domain.md).
`AGENTS.md` + `CLAUDE.md` = symlinks to this file.
---
Footnotes for research:
- **Intuit behaviour reference**: the official [Intuit CLI](https://github.com/intuit/intuit-cli-for-quickbooks) and [QuickBooks Online MCP server](https://github.com/intuit/quickbooks-online-mcp-server) show how Intuit structured its code: study them to improve `qb`; never a runtime tool or dependency ([ADR-0001](https://github.com/ceciliobooks/qbcli/blob/HEAD/docs/adr/0001-qb-covers-every-intuit-api-in-phases.md), [ADR-0009](https://github.com/ceciliobooks/qbcli/blob/HEAD/docs/adr/0009-agent-technical-choices.md)). Build our code from Intuit docs and Sandbox proofs. The CLI POST retry sends no `requestid` ([#56](https://github.com/ceciliobooks/qbcli/issues/56)).
