qb - QuickBooks CLI

CRUD operations for QuickBooks Online: invoices, payments, customers, and products.

Installation

``bash
pnpm install
pnpm build
npm link # optional: makes 'qb' available globally
`

Setup

1. Create an app at developer.intuit.com
2. Set environment variables:

`bash
export QB_CLIENT_ID="your-client-id"
export QB_CLIENT_SECRET="your-client-secret"
export QB_SANDBOX=1 # optional: default when unset
`

3. Authenticate:

`bash
qb auth login
`

Usage

`
qb [global flags] [args]
`

Global Flags

| Flag | Env Var | Description |
|------|---------|-------------|
| -h, --help | | Show help |
| --version | | Print version |
| -q, --quiet | QB_QUIET=1 | Suppress non-essential output |
| -v, --verbose | QB_VERBOSE=1 | Show debug information |
| --format | QB_OUTPUT=table\|json\|plain | Output format |
| --json | QB_OUTPUT=json | Alias for --format json |
| --plain | QB_OUTPUT=plain | Alias for --format plain |
| --no-color | NO_COLOR=1 | Disable color output |
| --no-input | QB_NO_INPUT=1 | Fail instead of prompting |
| --company | QB_COMPANY_ID | Override default company |
| --sandbox | QB_SANDBOX=1 | Use sandbox environment |
| --update | | Update qb to the latest version |

Commands

$3

Manage QuickBooks authentication.

`bash
qb auth login # OAuth browser flow
qb auth logout # Revoke and delete tokens
qb auth status # Show current auth state
qb auth switch # Switch between companies
`

$3

Update qb to the latest version.

`bash
qb update
qb --update
`

$3

Manage invoices.

`bash


List invoices

qb invoice list
qb invoice list --status unpaid --format json
qb invoice list --limit 50 --all
qb invoice list --since 2025-01-01 --order-by "TxnDate DESC"

Get invoice details

qb invoice get 1234

Create invoice from file

qb invoice create -f invoice.json

Create from stdin

cat invoice.json | qb invoice create --stdin

Update invoice

qb invoice update 1234 -f updates.json
qb invoice update 1234 --input updates.json

Delete (with confirmation)

qb invoice delete 1234
qb invoice delete 1234 --force # skip confirmation

Send invoice via email

qb invoice send 1234
`

$3

Manage customers.

`bash


List customers

qb customer list
qb customer list --query "Acme"
qb customer list --all --json
qb customer list --since 2025-01-01 --order-by "DisplayName ASC"

Get customer details

qb customer get 5

Create customer

qb customer create -f customer.json
qb customer create --input customer.json

Update customer

qb customer update 5 -f updates.json
qb customer update 5 --input updates.json

Deactivate customer (soft delete)

qb customer delete 5
qb customer delete 5 --force
`

$3

Manage payments.

`bash


List payments

qb payment list
qb payment list --since 2025-01-01
qb payment list --since 2025-01-01 --order-by "TxnDate DESC" --all

Get payment details

qb payment get 789

Create payment

qb payment create -f payment.json
qb payment create --input payment.json

Update payment

qb payment update 789 -f updates.json
qb payment update 789 --input updates.json

Delete payment

qb payment delete 789 --force

Void payment

qb payment void 789
qb payment void 789 --force --reason "Customer dispute"
`

$3

Manage products/items.

`bash


List products

qb product list
qb product list --type Service
qb product list --type Inventory --json
qb product list --since 2025-01-01 --order-by "Name ASC" --all

Get product details

qb product get 42

Create product

qb product create -f product.json
qb product create --input product.json

Update product

qb product update 42 -f updates.json
qb product update 42 --input updates.json

Deactivate product (soft delete)

qb product delete 42
qb product delete 42 --force
`

$3

Generate shell completion scripts.

`bash
qb completion bash
qb completion zsh
qb completion fish
`

Data Format

All create/update operations accept JSON files. Example invoice:

`json
{
"CustomerRef": {
"value": "5"
},
"Line": [
{
"Amount": 500.00,
"DetailType": "SalesItemLineDetail",
"SalesItemLineDetail": {
"ItemRef": {
"value": "1"
}
}
}
],
"DueDate": "2025-02-15"
}
`

Example customer:

`json
{
"DisplayName": "Acme Corporation",
"CompanyName": "Acme Corp",
"PrimaryEmailAddr": {
"Address": "billing@acme.com"
},
"PrimaryPhone": {
"FreeFormNumber": "(555) 123-4567"
}
}
`

Exit Codes

| Code | Meaning |
|------|---------|
| 0 | Success |
| 1 | General error (API failure, network) |
| 2 | Invalid usage (bad args, missing required) |
| 3 | Authentication error (not logged in, expired) |
| 4 | Not found (resource doesn't exist) |
| 5 | Conflict (duplicate, version mismatch) |
| 130 | Interrupted (Ctrl-C) |

Config

Token storage: ~/.config/qb/tokens.json

Config file: ~/.config/qb/config.json

`json
{
"companyId": "1234567890",
"output": "json",
"sandbox": true,
"aliases": {}
}
`

Sandbox default: When QB_SANDBOX is unset and config has no sandbox value, the CLI defaults to sandbox. To force production, set QB_SANDBOX=0 or "sandbox": false in config.

Precedence: CLI flags > env vars > project config > user config > defaults

Scripting Examples

`bash


Get all unpaid invoices over 30 days as JSON

qb invoice list --status unpaid --json | jq '.[] | select(.days_overdue > 30)'

Export all customers

qb customer list --all --json > customers.json

Bulk create from JSONL

cat customers.jsonl | while read line; do
echo "$line" | qb customer create --stdin
done

Check if authenticated before running

if qb auth status > /dev/null 2>&1; then
qb invoice list
else
echo "Not authenticated"
exit 1
fi
`

Development

`bash
pnpm install # Install dependencies
pnpm dev # Run in dev mode
pnpm build # Build for production
pnpm typecheck # Type check
pnpm lint # Lint code
pnpm test # Run tests
``

License

MIT