Intuit QuickBooks CLI

A command-line tool for the QuickBooks Online API. Authenticate, query data, and manage QuickBooks companies from your terminal.

With the CLI, you can:

• Authenticate via OAuth 2.0 with encrypted token storage
• Browse 15 entity types — customers, invoices, estimates, payments, bills, and more
• Create entities from inline flags or JSON files
• Query QuickBooks data using QBO query syntax
• Test webhooks locally with signature verification and event replay
• Manage multiple QuickBooks companies with named profiles
• Debug API issues with --debug for full request/response logging

Install

npm install -g intuit-cli

Or try without installing:

npx intuit-cli --help

git clone https://github.com/IntuitDeveloper/intuit-developer-cli.git
cd intuit-developer-cli
npm install
npm run build
npm link

Prerequisites

• Node.js 18+
• An Intuit Developer app with OAuth 2.0 credentials (create one here)
• Redirect URI configured in your app's settings:
  • Sandbox: http://localhost:9477/callback
  • Production: A registered HTTPS URL (e.g. https://yourapp.com/callback) — localhost is not supported

Run intuit auth configure for interactive setup, or create a .env file manually:

INTUIT_SANDBOX_CLIENT_ID=your_sandbox_client_id
INTUIT_SANDBOX_CLIENT_SECRET=your_sandbox_client_secret
INTUIT_PROD_CLIENT_ID=your_production_client_id
INTUIT_PROD_CLIENT_SECRET=your_production_client_secret

Sandbox and Production use separate Client IDs and Secrets.

Quickstart

intuit auth configure                  # interactive credential setup (or create .env manually)
intuit auth login --env sandbox        # opens browser for OAuth
intuit auth status                     # verify connection
intuit customers list                  # pull data
intuit customers list --json           # machine-readable output

Authentication

Each connection to a QuickBooks company is stored as a profile. The first login creates a default profile automatically. Access tokens expire every 60 minutes and auto-refresh using the refresh token (valid 101 days).

intuit auth login --profile prod --env production --redirect-uri https://yourapp.com/callback

See Intuit's sandbox documentation for setting up test companies.

Commands

Browse data

All list commands support --where, --order-by, --limit, --all, --json, --csv. Output renders as aligned tables by default.

intuit customers list --where "Balance > 0" --order-by "DisplayName ASC"
intuit invoices list --all --csv > invoices.csv
intuit estimates list --where "TxnStatus = 'Pending'"
intuit payments list --json
intuit purchases list --where "PaymentType = 'CreditCard'"
intuit company info

Supported entities: customers, invoices, estimates, salesreceipts, creditmemos, payments, purchases, employees, bills, billpayments, deposits, vendors, items, accounts.

Create and void

Use inline flags for simple creates or --file for full JSON payloads. Sample payloads are in the examples/ folder.

# Inline flags
intuit customers create --display-name "Acme Corp" --email "[email protected]"
intuit vendors create --display-name "Office Supplies Inc"
intuit items create --name "Consulting" --type Service
intuit invoices create --customer-ref 118 --amount 500
intuit payments create --customer-ref 118 --amount 250
intuit estimates create --customer-ref 118 --amount 1200
intuit employees create --given-name "Jane" --family-name "Doe"

# From JSON file (any entity)
intuit invoices create --file examples/invoice.json
intuit purchases create --file purchase.json
intuit deposits create --file deposit.json

# Void (accounting-correct — zeroes balance, doesn't delete)
intuit invoices void 123
intuit payments void 456

Raw query

Run any QBO query directly:

intuit query "SELECT * FROM Customer STARTPOSITION 1 MAXRESULTS 10"

Webhooks

intuit webhooks listen --verifier-token <token> --events qbo.customer.created.v1,qbo.invoice.updated.v1
intuit webhooks guide                        # full setup instructions

Multiple companies

intuit auth login --profile client-a --env sandbox
intuit profile list
intuit profile switch client-a
intuit customers list --profile client-b     # one-off override

Shell completions

eval "$(intuit completions bash)"   # add to ~/.bashrc
eval "$(intuit completions zsh)"    # add to ~/.zshrc

Debugging

--debug logs full HTTP request/response to stderr — URLs, headers (token masked), timing, and intuit_tid:

intuit customers list --debug

Command reference

| Command | Description | |---------|-------------| | Auth & Profiles | | | auth configure | Set up OAuth credentials interactively | | auth login | Authenticate with QuickBooks (--profile, --env, --redirect-uri) | | auth status | Check token status and config provenance | | auth refresh | Manually refresh access token | | auth logout | Clear tokens and remove profile | | profile list | List all configured profiles | | profile switch <name> | Switch active profile | | profile remove <name> | Remove a profile | | Entities | All list commands support --where, --order-by, --limit, --all, --json, --csv | | customers list/create | Customers (--display-name, --email, --phone, --file) | | invoices list/create/void | Invoices (--customer-ref, --amount, --item-ref, --file) | | payments list/create/void | Payments (--customer-ref, --amount, --file) | | estimates list/create | Estimates (--customer-ref, --amount, --item-ref, --file) | | salesreceipts list/create | Sales receipts (--customer-ref, --amount, --item-ref, --file) | | creditmemos list/create | Credit memos (--customer-ref, --amount, --item-ref, --file) | | purchases list/create | Purchases/expenses (--account-ref, --expense-account-ref, --amount, --payment-type, --file) | | employees list/create | Employees (--given-name, --family-name, --email, --file) | | billpayments list/create | Bill payments (--vendor-ref, --amount, --pay-type, --bank-account-ref, --cc-account-ref, --file) | | deposits list/create | Deposits (--account-ref, --line-account-ref, --amount, --file) | | bills list | Bills | | vendors list/create | Vendors (--display-name, --email, --phone, --file) | | items list/create | Items (--name, --type, --income-account-ref, --expense-account-ref, --file) | | accounts list | Chart of accounts | | company info | Company details (--json, --csv) | | Webhooks | | | webhooks guide | Show webhook setup instructions | | webhooks listen | Capture events locally (--port, --verifier-token, --events, --forward-to) | | webhooks replay | Show recent events (--last, --json) | | Other | | | query <statement> | Run a raw QBO query | | completions bash/zsh | Generate shell completions |

Global flags: --debug (verbose HTTP logging), --help, --version

Use --help on any command for details: intuit invoices create --help

Security

• Tokens are encrypted with AES-256-GCM and stored at ~/.config/intuit-cli/
• Encryption keys are kept in your OS keychain (macOS Keychain, Windows Credential Manager, or Linux Secret Service)
• Token files are created with 0600 permissions (owner read/write only)
• Access tokens auto-refresh using the refresh token — no credentials stored in plaintext

Rate limits

The QuickBooks Online API enforces per-realm limits (500 requests/min, 10 concurrent). The CLI retries 429 responses with exponential backoff automatically. See Intuit's throttling documentation.

Uninstall

intuit auth logout                                          # clear tokens
rm -rf ~/.config/intuit-cli                                 # remove all CLI data
security delete-generic-password -s intuit-cli 2>/dev/null  # macOS keychain cleanup

Development

npm run dev -- auth login
npm run dev -- customers list

License

Apache 2.0 — see LICENSE