qb-cli

QuickBooks Online CLI tool. Manage customers, invoices, payments, bills, vendors, accounts, items, expenses, journal entries, deposits, transfers, estimates, purchase orders, and run financial reports directly via the Intuit API. 164 commands across 29 command groups. All commands return JSON by default for agent consumption.

# qb-cli — QuickBooks Online CLI

Manage QuickBooks Online from the command line. Designed for both human and AI agent use. Talks directly to Intuit's QuickBooks API — no third-party proxy. 164 commands across 29 groups covering AR, AP, chart of accounts, banking, reporting, imports, reconciliation, and month-end workflows.

## Setup

The tool runs in a Docker container at `~/skills/qb-cli/`.

### Prerequisites

1. Create a QuickBooks developer account at https://developer.intuit.com
2. Create an app (Keys & OAuth section)
3. Note your Client ID and Client Secret
4. Add `http://localhost:8844/callback` as a Redirect URI

### Configuration

```bash
cp ~/skills/qb-cli/.env.example ~/skills/qb-cli/.env
# Edit .env with your Client ID and Client Secret
```

### Build (first time)

```bash
docker compose -f ~/skills/qb-cli/docker-compose.yml build
```

### Authenticate (SSH / headless)

```bash
# Step 1: Get the auth URL
~/skills/qb-cli/run.sh auth login --print-url

# Step 2: Open the URL in any browser, authorize QuickBooks
# Step 3: Copy the full redirect URL from browser address bar
# Step 4: Paste it back
~/skills/qb-cli/run.sh auth login --callback-url "http://localhost:8844/callback?code=...&realmId=..."
```

---

## CRITICAL AGENT RULES — READ BEFORE DOING ANYTHING

### Rule 1: ALWAYS Search Before Creating

**Never create a customer, vendor, or item without first searching for duplicates.**

```bash
~/skills/qb-cli/run.sh customer search "Meridian"
~/skills/qb-cli/run.sh vendor search "Acme"
```

If the search returns results, confirm with the user which one they mean. Do NOT assume.

### Rule 2: NEVER Create a Customer Without Complete Information

**You MUST have ALL of the following before creating a customer record:**
- **Display name** — Full legal name or business name
- **Company name** — The legal business entity name (if applicable)
- **Billing email address** — Required for sending invoices electronically
- **Phone number** — Primary contact phone
- **Billing address** — Full street address, city, state, and zip code

If the user says something vague like "send an invoice to Mike" or "bill Acme $500":
1. **STOP.** Do not create anything.
2. Search for the customer: `customer search "Mike"` or `customer search "Acme"`
3. If no results, ask the user for: full name, company name, billing email, phone, and billing address.
4. Only proceed once you have all fields.

### Rule 3: Confirm Before Sending Invoices/POs

- **Never send an invoice or PO by email unless the user explicitly says to send it.**
- Creating and sending are separate actions.
- Always confirm the amount, customer/vendor, and line items before creating.

### Rule 4: Verify Payments Before Applying

- Always confirm the customer, open invoices, and amounts before creating a payment.
- Include the payment reference (check #, ACH trace, wire ref) when available.
- Verify the payment total equals the sum of the per-invoice amounts.

### Rule 5: Never Delete a Bill with Applied Payments

- Before deleting a bill, check if bill-payments have been applied to it.
- Delete or void the bill-payment first, then delete the bill.

### Rule 6: Journal Entries Must Balance

- Debits must equal credits. The CLI validates this before sending.
- Always specify a memo/description for audit trail.

### Rule 7: Never Void Deposited Payments

- If a payment has been grouped into a deposit, void/delete the deposit first.
- Then void/delete the individual payment.

### Rule 8: Reconciliation Is Read-Only

- The reconcile commands are **helpers only** — they cannot mark transactions as reconciled in QB.
- Use them to identify matches, flag discrepancies, and generate reports.
- The actual reconciliation click must happen in the QuickBooks UI.

---

## Usage

All commands: `~/skills/qb-cli/run.sh [resource] [action] [options]`

Default output is JSON. Use `-o table` for human-readable or `-o csv` for export.

---

### Auth & Config

```bash
~/skills/qb-cli/run.sh auth login --print-url          # Get OAuth URL
~/skills/qb-cli/run.sh auth login --callback-url "..."  # Complete OAuth
~/skills/qb-cli/run.sh auth status                       # Check auth status
~/skills/qb-cli/run.sh auth refresh                      # Force token refresh
~/skills/qb-cli/run.sh auth logout                       # Remove tokens
~/skills/qb-cli/run.sh config init                       # Initialize config
~/skills/qb-cli/run.sh config show                       # Show config
~/skills/qb-cli/run.sh company info                      # Company details
```

---

### Customers (AR)

```bash
# Search (ALWAYS do this first!)
~/skills/qb-cli/run.sh customer search "Acme"
~/skills/qb-cli/run.sh customer search "jane@example.com"
~/skills/qb-cli/run.sh customer search "555-0199"

# List
~/skills/qb-cli/run.sh customer list
~/skills/qb-cli/run.sh customer list -o table
~/skills/qb-cli/run.sh customer list --no-active-only

# CRUD
~/skills/qb-cli/run.sh customer get 123
~/skills/qb-cli/run.sh customer create --name "Jane Smith" --company "Smith LLC" --email "jane@smith.com" --phone "555-0199"
~/skills/qb-cli/run.sh customer update 123 --name "Jane Smith-Jones" --email "new@email.com"
~/skills/qb-cli/run.sh customer delete 123   # soft-delete (Active=false)

# Query
~/skills/qb-cli/run.sh customer query "Balance > '0'"
```

### Invoices

```bash
~/skills/qb-cli/run.sh invoice list
~/skills/qb-cli/run.sh invoice get 456
~/skills/qb-cli/run.sh invoice create --customer-id 123 --amount 500 --due-date 2026-04-01
~/skills/qb-cli/run.sh invoice create --customer-id 123 --line-json '[{"Amount":500,"DetailType":"SalesItemLineDetail","SalesItemLineDetail":{"ItemRef":{"value":"1"},"Qty":2,"UnitPrice":250}}]'
~/skills/qb-cli/run.sh invoice update 456 --json '{"DueDate": "2026-05-01"}'
~/skills/qb-cli/run.sh invoice send 456                  # email to customer
~/skills/qb-cli/run.sh invoice send 456 --email "override@email.com"
~/skills/qb-cli/run.sh invoice void 456                  # zeros amounts, keeps record
~/skills/qb-cli/run.sh invoice delete 456
~/skills/qb-cli/run.sh invoice query "CustomerRef = '123' AND Balance > '0'"
```

### Payments

```bash
~/skills/qb-cli/run.sh payment list
~/skills/qb-cli/run.sh payment get 182
~/skills/qb-cli/run.sh payment create --customer-id 63 --amount 5000 --invoice-ids "148,149" --invoice-amounts "3000,2000" --ref "ACH-12345" --date "2026-02-15"
~/skills/qb-cli/run.sh payment void 182
~/skills/qb-cli/run.sh payment delete 182
~/skills/qb-cli/run.sh payment query "TxnDate > '2026-01-01'"
```

### Estimates (Quotes/Proposals)

```bash
~/skills/qb-cli/run.sh estimate list
~/skills/qb-cli/run.sh estimate get 789
~/skills/qb-cli/run.sh estimate create --customer-id 123 --amount 1500 --expiration-date 2026-04-30
~/skills/qb-cli/run.sh estimate update 789 --json '{"ExpirationDate": "2026-05-31"}'
~/skills/qb-cli/run.sh estimate send 789
~/skills/qb-cli/run.sh estimate to-invoice 789   # convert estimate to invoice
~/skills/qb-cli/run.sh estimate delete 789
~/skills/qb-cli/run.sh estimate query "TxnStatus = 'Pending'"
```

### Credit Memos

```bash
~/skills/qb-cli/run.sh credit-memo list
~/skills/qb-cli/run.sh credit-memo create --customer-id 123 --amount 200
~/skills/qb-cli/run.sh credit-memo send 456
~/skills/qb-cli/run.sh credit-memo void 456
~/skills/qb-cli/run.sh credit-memo delete 456
~/skills/qb-cli/run.sh credit-memo query "TotalAmt > '100'"
```

### Sales Receipts (Cash Sales)

```bash
~/skills/qb-cli/run.sh sales-receipt list
~/skills/qb-cli/run.sh sales-receipt create --customer-id 123 --amount 750 --deposit-to 35 --payment-method "Cash"
~/skills/qb-cli/run.sh sales-receipt send 456
~/skills/qb-cli/run.sh sales-receipt void 456
~/skills/qb-cli/run.sh sales-receipt delete 456
```

### Refund Receipts

```bash
~/skills/qb-cli/run.sh refund-receipt list
~/skills/qb-cli/run.sh refund-receipt create --customer-id 123 --amount 200 --deposit-from 35
~/skills/qb-cli/run.sh refund-receipt void 456
~/skills/qb