BreezeDoc's REST API provides a handful of endpoints which can be used to get information about your account and bookings. It uses conventional OAuth 2.0 protocol for authentication.
Personal Access Token
Create a personal access token at https://breezedoc.com/integrations/api. Once created, it can be used to authenticate requests by passing it in the Authorization header.
Authorization: Bearer {TOKEN}
OAuth 2.0 Client
If you're building a custom integration to BreezeDoc which requires users to authenticate in order to get access tokens to make API requests on their behalf, you'll need to create an OAuth 2.0 client. This is easy to do from the "OAuth Apps" settings page found here https://breezedoc.com/integrations/api
Using the authorization_code grant type to authenticate users using OAuth 2.0 to retrieve an access token is fairly conventional, more information on that process can be found here: https://www.oauth.com/oauth2-servers/server-side-apps/authorization-code/
The API currently has a rate limit of 60 requests per minute. If you exceed this limit, you will receive a 429 error.
Learn more at Breezedoc.
Created by @cathrynlavery (Cathryn Lavery).
Quick Start
1. Install
See Install above.
2. Set Up Credentials
Get your access token from your API provider's developer portal, then store it:
breezedoc-pp-cli auth set-token YOUR_TOKEN_HERE
Or set it via environment variable:
export BREEZEDOC_API_TOKEN="your-token-here"
3. Verify Setup
breezedoc-pp-cli doctor
This checks your configuration and credentials.
4. Try Your First Command
breezedoc-pp-cli documents list
Usage
Run breezedoc-pp-cli --help for the full command reference and flag list.
Commands
documents
Manage documents
breezedoc-pp-cli documents get - Get a specific documentbreezedoc-pp-cli documents list - Get list of documentsbreezedoc-pp-cli documents store - Create a new document
invoices
Manage invoices
breezedoc-pp-cli invoices create - Creates a new invoice with line items. Optionally sends the invoice immediately by setting send: true.breezedoc-pp-cli invoices delete - Deletes a draft invoice. Cannot delete invoices that have already been sent.breezedoc-pp-cli invoices get - Get a specific invoicebreezedoc-pp-cli invoices list - Retrieves a paginated list of invoices for the authenticated user.breezedoc-pp-cli invoices patch - Same as PUT - updates an existing invoice. Cannot update invoices with status paid, uncollectible, or void.breezedoc-pp-cli invoices update - Updates an existing invoice. Cannot update invoices with status: paid, uncollectible, or void.
When updating items, the entire items array is replaced.
me
Manage me
breezedoc-pp-cli me - Get current user information
recipients
Manage recipients
breezedoc-pp-cli recipients - Get list of recipients
teams
Manage teams
templates
Manage templates
breezedoc-pp-cli templates get - Get a specific templatebreezedoc-pp-cli templates list - Get list of templates
Output Formats
# Human-readable table (default in terminal, JSON when piped)
breezedoc-pp-cli documents list
# JSON for scripting and agents
breezedoc-pp-cli documents list --json
# Filter to specific fields
breezedoc-pp-cli documents list --json --select id,name,status
# Dry run — show the request without sending
breezedoc-pp-cli documents list --dry-run
# Agent mode — JSON + compact + no prompts in one flag
breezedoc-pp-cli documents list --agent
Agent Usage
This CLI is designed for AI agent consumption:
- Non-interactive - never prompts, every input is a flag
- Pipeable -
--json output to stdout, errors to stderr
- Filterable -
--select id,name returns only fields you need
- Previewable -
--dry-run shows the request without sending
- Explicit retries - add
--idempotent to create retries and --ignore-missing to delete retries when a no-op success is acceptable
- Confirmable -
--yes for explicit confirmation of destructive actions
- Piped input - write commands can accept structured input when their help lists
--stdin
- Offline-friendly - sync/search commands can use the local SQLite store when available
- Agent-safe by default - no colors or formatting unless
--human-friendly is set
Exit codes: 0 success, 2 usage error, 3 not found, 4 auth error, 5 API error, 7 rate limited, 10 config error.
Health Check
breezedoc-pp-cli doctor
Verifies configuration, credentials, and connectivity to the API.
Configuration
Config file: ~/.config/breezedoc-pp-cli/config.toml
Static request headers can be configured under headers; per-command header overrides take precedence.
Environment variables:
| Name | Kind | Required | Description |
|---|
BREEZEDOC_API_TOKEN | per_call | No | Set to your API credential. |
BREEZEDOC_BEARER_TOKEN | per_call | No | Set to your API credential. |
BREEZEDOC_BEARER_AUTH | per_call | No | Set to your API credential. |
agentcookie (optional)
If you use agentcookie to sync secrets across machines, this CLI auto-adopts agentcookie-managed credentials with no extra setup. When the daemon writes to this CLI's config, breezedoc-pp-cli doctor reports agentcookie: detected and auth-status labels the source as agentcookie. Skip this section if you don't use agentcookie - the CLI works the same as any other.
Troubleshooting
Authentication errors (exit code 4)
- Run
breezedoc-pp-cli doctor to check credentials
- Verify the environment variable is set:
echo $BREEZEDOC_API_TOKEN
Not found errors (exit code 3)
- Check the resource ID is correct
- Run the
list command to see available items
Generated by CLI Printing Press