qbcli

README

qbcli - QuickBooks Online CLI

A command-line interface and Go SDK for managing QuickBooks Online accounts.

Overview

This project provides two main components:

1. Go SDK (pkg/qbo) - A complete Go library for the QuickBooks Online API
2. CLI Tool (qbcli) - A command-line interface built on the SDK

Features

• OAuth2 authentication with automatic token refresh
• Full CRUD operations for QuickBooks entities
• Type-safe query builder
• Multiple output formats (table, JSON, YAML, CSV)
• Shell completion (bash, zsh, fish, powershell)
• Batch operations support
• Report generation

Requirements

• Go 1.21 or later
• QuickBooks Online developer account
• OAuth2 credentials (Client ID and Client Secret)

Installation

From Source

git clone https://github.com/obay/qbcli.git
cd qbcli
make build

Go Install

go install github.com/obay/qbcli/cmd/qbcli@latest

Quick Start

1. Configure Credentials

qbcli config init
qbcli config set client_id YOUR_CLIENT_ID
qbcli config set client_secret YOUR_CLIENT_SECRET

2. Authenticate

qbcli auth login

3. Use the CLI

# List customers
qbcli customer list

# Get a specific invoice
qbcli invoice get 123

# Create a customer from JSON
qbcli customer create --from-file customer.json

# Generate a report
qbcli report profit-loss --start-date 2024-01-01 --end-date 2024-12-31

SDK Usage

package main

import (
    "context"
    "log"

    "github.com/obay/qbcli/pkg/qbo"
)

func main() {
    client, err := qbo.NewClient(qbo.Config{
        ClientID:     "your-client-id",
        ClientSecret: "your-client-secret",
        RealmID:      "your-realm-id",
        Environment:  qbo.Sandbox,
    })
    if err != nil {
        log.Fatal(err)
    }

    ctx := context.Background()

    // Query customers
    customers, err := client.Customer.Query(ctx, "SELECT * FROM Customer WHERE Active = true")
    if err != nil {
        log.Fatal(err)
    }

    for _, c := range customers {
        log.Printf("Customer: %s\n", c.DisplayName)
    }
}

Project Structure

qbcli/
├── cmd/qbcli/          # CLI entry point and commands
├── pkg/qbo/            # Public SDK package
│   ├── auth/           # OAuth2 authentication
│   ├── client/         # HTTP client and request handling
│   ├── entities/       # QuickBooks entity types
│   ├── services/       # Entity CRUD services
│   ├── query/          # Query builder
│   └── batch/          # Batch operations
├── internal/           # Private packages
├── docs/               # Documentation
└── examples/           # Usage examples

Development

Prerequisites

make setup  # Install development tools

Build

make build  # Build binary to bin/
make test   # Run tests
make lint   # Run linters
make fmt    # Format code

Running Tests

make test           # Run all tests
make test-coverage  # Generate coverage report

Documentation

• Project Brief
• PRD
• Architecture
• Execution Plan

Supported Entities

Entity	Create	Read	Update	Delete	Query
Account	✓	✓	✓	-	✓
Customer	✓	✓	✓	-	✓
Vendor	✓	✓	✓	-	✓
Item	✓	✓	✓	-	✓
Invoice	✓	✓	✓	✓	✓
Bill	✓	✓	✓	✓	✓
Payment	✓	✓	✓	✓	✓
Estimate	✓	✓	✓	✓	✓

Contributing

See CONTRIBUTING.md for guidelines.

License

MIT License - see LICENSE for details.