qb-cli

What this skill does

# 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 "[email protected]"
~/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 "[email protected]" --phone "555-0199"
~/skills/qb-cli/run.sh customer update 123 --name "Jane Smith-Jones" --email "[email protected]"
~/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 "[email protected]"
~/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/q