quickbooks-cli

Minimal JavaScript CLI for authenticating with QuickBooks Online and doing a few useful account operations from the terminal.

This first pass is intentionally narrow:

• OAuth 2.0 login against an Intuit app you control
• local token storage and automatic access-token refresh
• company info lookup
• customer listing and customer creation
• vendor listing and vendor creation
• account listing
• item listing
• invoice listing and invoice creation
• bill listing and bill creation
• reports
• raw query and raw request escape hatches

It targets QuickBooks Online Accounting only.

Official docs used

• QuickBooks Online get started
• QuickBooks OAuth 2.0
• QuickBooks Online API overview

Setup

1. Create an app in the Intuit developer dashboard.
2. Enable QuickBooks Online Accounting for the app.
3. Add a redirect URI such as:

http://127.0.0.1:4545/callback

4. Copy the app's client ID and client secret.

Install

cd ~/Projects/quickbooks-cli
chmod +x ./bin/quickbooks.js
npm run check
npm link

Authenticate

Sandbox is the default:

export QBO_CLIENT_ID=...
export QBO_CLIENT_SECRET=...
export QBO_ENVIRONMENT=sandbox
export QBO_REDIRECT_URI=http://127.0.0.1:4545/callback

quickbooks auth login

The CLI prints the Intuit authorization URL. Open it in your browser, authorize the app, and the CLI will catch the callback locally.

Config is stored at:

~/.config/quickbooks-cli/config.json

You can also provide credentials with env vars:

export QBO_CLIENT_ID=...
export QBO_CLIENT_SECRET=...
export QBO_ENVIRONMENT=sandbox
export QBO_REDIRECT_URI=http://127.0.0.1:4545/callback

You can still override any of those with flags on quickbooks auth login.

Commands

quickbooks help
quickbooks auth login --client-id <id> --client-secret <secret>
quickbooks auth status
quickbooks auth refresh
quickbooks auth logout
quickbooks company info
quickbooks customers list --limit 20
quickbooks customers get --id 123
quickbooks customers create --display-name "Acme LLC" --email ops@acme.com
quickbooks vendors list --limit 20
quickbooks vendors get --id 456
quickbooks vendors create --display-name "Acme Supplies" --email billing@acme.com
quickbooks accounts list --limit 20
quickbooks items list --limit 20
quickbooks invoices list --limit 20
quickbooks invoices create --customer-id 123 --lines-json '[{"itemId":"1","amount":125}]'
quickbooks bills list --limit 20
quickbooks bills create --vendor-id 456 --lines-json '[{"accountId":"7","amount":89.5}]'
quickbooks reports profit-and-loss --date-macro ThisMonth
quickbooks reports balance-sheet --date-macro ThisMonth
quickbooks reports run TrialBalance --date-macro ThisFiscalYear
quickbooks query "select * from Customer maxresults 10"
quickbooks request GET /companyinfo/1

Examples

Get basic company info:

quickbooks company info

List customers:

quickbooks customers list --limit 10

List vendors:

quickbooks vendors list --limit 10

List items before creating invoices:

quickbooks items list --limit 20

Create a customer:

quickbooks customers create \
  --display-name "Acme LLC" \
  --company-name "Acme LLC" \
  --email ops@acme.com \
  --phone 5551234567

Create a vendor:

quickbooks vendors create \
  --display-name "Acme Supplies" \
  --company-name "Acme Supplies" \
  --email billing@acme.com \
  --phone 5551234567

Create an invoice:

quickbooks invoices create \
  --customer-id 123 \
  --lines-json "$(cat ./examples/invoice-lines.json)" \
  --txn-date 2026-03-21 \
  --due-date 2026-04-01 \
  --memo "Thanks for your business"

Create a bill:

quickbooks bills create \
  --vendor-id 456 \
  --lines-json "$(cat ./examples/bill-lines.json)" \
  --txn-date 2026-03-21 \
  --due-date 2026-04-01 \
  --memo "March hosting"

Run reports:

quickbooks reports profit-and-loss --date-macro ThisMonth
quickbooks reports balance-sheet --date-macro ThisMonth
quickbooks reports run TrialBalance --date-macro ThisFiscalYear

Run a raw query:

quickbooks query "select * from Invoice startposition 1 maxresults 5"

Hit a raw API path:

quickbooks request GET /customer/123

Notes

• Access tokens expire quickly, so the CLI refreshes them automatically when needed.
• Refresh tokens are still long-lived but not permanent, so you may eventually need to re-run quickbooks auth login.
• request expects a relative path under /v3/company/<realmId>.
• Invoice creation expects SalesItemLineDetail lines with an itemId.
• Bill creation expects AccountBasedExpenseLineDetail lines with an accountId.
• This version still does not support payments, attachments, or invoice updates.