{
  "markdown": "<p align=\"center\">\n  <img src=\".github/banner.svg\" alt=\"qbo cli\" width=\"700\" />\n</p>\n\n<p align=\"center\">\n  <a href=\"https://github.com/voska/qbo-cli/actions/workflows/ci.yml\"><img src=\"https://github.com/voska/qbo-cli/actions/workflows/ci.yml/badge.svg\" alt=\"CI\" /></a>\n  <a href=\"https://github.com/voska/qbo-cli/releases\"><img src=\"https://img.shields.io/github/v/release/voska/qbo-cli\" alt=\"Release\" /></a>\n  <a href=\"https://go.dev/\"><img src=\"https://img.shields.io/github/go-mod/go-version/voska/qbo-cli\" alt=\"Go\" /></a>\n  <a href=\"LICENSE\"><img src=\"https://img.shields.io/badge/License-MIT-blue.svg\" alt=\"License: MIT\" /></a>\n</p>\n\nCLI for [QuickBooks Online](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/most-commonly-used/account) — CRUD, reports, queries, and batch ops from the terminal.\n\n### Highlights\n\n- **Direct API access** — thin wrapper over the QBO REST API, no scraping or browser automation\n- **Agent-friendly** — `--json` on every command, structured exit codes, stderr-only progress\n- **Full CRUD** — list, get, create, update, delete any QBO entity plus raw queries\n- **Financial reports** — profit & loss, balance sheet, and more with date range filters\n- **Single binary** — install via Homebrew, Scoop, or `go install`\n\n```bash\n$ qbo list invoices --where \"Balance > '0'\" --sandbox --json\n[\n  {\"Id\": \"130\", \"DocNumber\": \"1038\", \"CustomerRef\": {\"name\": \"Amy's Bird Sanctuary\"}, \"Balance\": 629.10},\n  {\"Id\": \"131\", \"DocNumber\": \"1039\", \"CustomerRef\": {\"name\": \"Bill's Windsurf Shop\"}, \"Balance\": 239.00}\n]\n\n$ qbo report profit-and-loss --start-date 2025-01-01 --sandbox\nProfit and Loss (2025-01-01 — 2025-12-31)\n──────────────────────────────────────────\n  Income                          $12,450.00\n  Cost of Goods Sold               $4,200.00\n  ─────────────────────────────────\n  Gross Profit                     $8,250.00\n  Expenses                         $3,100.00\n  ─────────────────────────────────\n  Net Income                       $5,150.00\n```\n\n## Install\n\n**Homebrew** (macOS / Linux):\n\n```bash\nbrew install voska/tap/qbo\n```\n\n**Scoop** (Windows):\n\n```powershell\nscoop bucket add voska https://github.com/voska/scoop-bucket\nscoop install qbo\n```\n\n<details>\n<summary>Other install methods</summary>\n\n**Go**:\n\n```bash\ngo install github.com/voska/qbo-cli/cmd/qbo@latest\n```\n\n**Binary**: download from [Releases](https://github.com/voska/qbo-cli/releases).\n\n**Linux (deb)** — also available for arm64:\n\n```bash\ncurl -LO https://github.com/voska/qbo-cli/releases/latest/download/qbo_linux_amd64.deb\nsudo dpkg -i qbo_linux_amd64.deb\n```\n\n</details>\n\n## Quick Start\n\n```bash\n# Store app-level OAuth client credentials in the system keychain (one time).\n# Env vars (QBO_CLIENT_ID/QBO_CLIENT_SECRET) still work and override this.\nqbo auth set-client --client-id your_client_id --client-secret your_client_secret\n\n# Authenticate (sandbox)\nqbo auth login --sandbox\n\n# Verify connection\nqbo auth status\nqbo company info --sandbox --json\n\n# List invoices\nqbo list invoices --sandbox\n\n# Get a specific customer\nqbo get customer 123 --sandbox\n\n# Query with filters\nqbo list invoices --where \"Balance > '0'\" --sandbox --json\n\n# Run a report\nqbo report profit-and-loss --start-date 2025-01-01 --end-date 2025-12-31 --sandbox\n```\n\n## Agent Skill\n\nInstall as a [Claude Code skill](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/skills) for AI-assisted QuickBooks workflows:\n\n```bash\nnpx skills add -g voska/qbo-cli\n```\n\nThe skill includes setup guidance, usage patterns, troubleshooting, and a full command reference.\n\n## Getting Credentials\n\nYou need an Intuit Developer account to get OAuth credentials.\n\n1. Sign up at [developer.intuit.com](https://developer.intuit.com) and create an app.\n2. Select **QuickBooks Online and Payments** as the platform.\n3. Under **Keys & credentials**, grab your **Client ID** and **Client Secret**.\n4. Add a **Redirect URI** — `http://localhost:8844/callback` for sandbox, or a public URI for production.\n\nSee [Intuit's OAuth 2.0 guide](https://developer.intuit.com/app/developer/qbo/docs/develop/authentication-and-authorization/oauth-2.0) for the full walkthrough.\n\n> **Sandbox vs Production:** Development keys only work with sandbox companies. For production, complete Intuit's app assessment and use `--redirect-uri` (or `QBO_REDIRECT_URI`) with a public URI.\n\n## API\n\nUses the [QuickBooks Online Accounting API](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/most-commonly-used/account) via REST. Requires OAuth 2.0 credentials from an Intuit Developer app. Sandbox access is free with no rate limits.\n\n## Commands\n\n| Command | Description |\n|---------|-------------|\n| `auth login\\|logout\\|status\\|refresh` | OAuth 2.0 authentication |\n| `list <entity>` | List entities with optional `--where` filter |\n| `get <entity> <id>` | Read a single entity by ID |\n| `create <entity> --data <json>` | Create an entity from JSON |\n| `update <entity> --data <json>` | Update an entity |\n| `delete <entity> <id>` | Delete an entity by ID |\n| `query \"<sql>\"` | Raw QBO query |\n| `report <type>` | Financial reports (profit-and-loss, balance-sheet, etc.) |\n| `batch --file <path>` | Batch operations from file |\n| `cdc --entities --since` | Change data capture polling |\n| `company info\\|list\\|switch` | Company management |\n| `schema` | CLI command tree as JSON (agent introspection) |\n| `exit-codes` | Print exit code reference |\n\nAll commands support `--dry-run`, `--no-input`, and `--sandbox`.\n\n## Output Modes\n\n| Flag | Description |\n|------|-------------|\n| _(default)_ | Colored tables, summaries on stderr |\n| `--json` / `-j` | Structured JSON to stdout |\n| `--plain` / `-p` | Tab-separated values, no color |\n| `--results-only` | Strip pagination metadata |\n| `--select f1,f2` | Project output to specific fields |\n\nAuto-JSON: when stdout is not a TTY and `QBO_AUTO_JSON=1`, defaults to JSON output.\n\n## Exit Codes\n\n| Code | Name | Description |\n|------|------|-------------|\n| 0 | `success` | Operation completed successfully |\n| 1 | `error` | General error |\n| 2 | `usage` | Invalid usage or arguments |\n| 3 | `empty` | No results found |\n| 4 | `auth_required` | Authentication required or token expired |\n| 5 | `not_found` | Resource not found |\n| 6 | `forbidden` | Permission denied |\n| 7 | `rate_limited` | API rate limit exceeded |\n| 8 | `retryable` | Transient error, safe to retry |\n| 10 | `config_error` | Configuration error |\n\n## Development\n\n```bash\nmake build    # Build to bin/qbo\nmake test     # Run tests with race detector\nmake lint     # golangci-lint\nmake vet      # go vet\nmake fmt      # gofmt\nmake ci       # fmt + lint + vet + test + build\n```\n\n## License\n\nMIT\n",
  "bytes": 6701,
  "sha": "eb05a3eafc8863fbec30774f020178a1d563f18e520baeaf7104b602ab499356",
  "repo_slug": "voska/qbo-cli",
  "fonte": "repo",
  "truncated": false,
  "api": "https://api.agentalog.com/api/listings/skl_voska_qbo_cli_qbo_071b2e97/readme"
}