qb - QuickBooks CLI

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

Installation

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

Setup

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

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

3. Authenticate:

qb auth login

Usage

qb [global flags] <command> <subcommand> [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 <table\|json\|plain> | 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 <id> | QB_COMPANY_ID | Override default company | | --sandbox | QB_SANDBOX=1 | Use sandbox environment | | --update | | Update qb to the latest version |

Commands

auth

Manage QuickBooks authentication.

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

update

Update qb to the latest version.

qb update
qb --update

invoice

Manage invoices.

# 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

customer

Manage customers.

# 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

payment

Manage payments.

# 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"

product

Manage products/items.

# 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

completion

Generate shell completion scripts.

qb completion bash
qb completion zsh
qb completion fish

Data Format

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

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

Example customer:

{
  "DisplayName": "Acme Corporation",
  "CompanyName": "Acme Corp",
  "PrimaryEmailAddr": {
    "Address": "[email protected]"
  },
  "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

{
  "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

# 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

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