Peppol CLI

A CLI to manage e-invoices on the Peppol network through the e-invoice.be Access Point API.

More information: https://e-invoice.be/peppol-cli

Installation

If peppol is not on PATH, install it:

# macOS / Linux (Homebrew)
brew install e-invoice-be/tap/peppol-cli

# Any platform with Go
go install github.com/e-invoice-be/peppol-cli/cmd/peppol@latest

Binaries for Linux (amd64, arm64) and Windows are on GitHub Releases. Extract the archive and put peppol (or peppol.exe) on PATH.

Prerequisites

The peppol command must be available on PATH:

peppol version

Check authentication status:

peppol auth status

If not authenticated, either:

• Run peppol auth (interactive -- opens browser to get API key)
• Set PEPPOL_API_KEY environment variable (non-interactive, preferred for automation)

Best Practices for AI Agents

• Always use --json (-j) for machine-readable output. Every command supports it. Parse JSON instead of formatted tables.
• Always use --yes (-y) on destructive commands (document delete, attachment delete). Without it, the CLI prompts for confirmation on stdin which will hang in non-interactive contexts.
• Validate before sending -- run peppol document validate <id> --json and check the is_valid field before calling peppol document send.
• Use --full for line items -- peppol document get <id> --json omits line items by default. Add --full to include them.
• Check exit codes -- 0 = success, 1 = general error, 2 = auth error, 3 = validation failed, 4 = not found.
• Respect rate limits -- a rate-limited request fails with API error 429: ... (retry after 30s). Wait for the stated time before the next attempt.
• Paginate through results -- default page size is 20. Use --page and --page-size to iterate. The JSON response includes total, page, and page_size fields.
• Use -w <workspace> to target a specific tenant without switching global state. Good for multi-tenant automation.
• Prefer document create json -- JSON creation is the most reliable format. PDF creation uses OCR and may need manual review (check the success field). UBL is for pre-built XML.
• Use --construct-pdf when creating from JSON to auto-generate a PDF representation of the invoice.
• Peppol ID format -- always scheme:identifier, e.g. 0208:0123456789 (Belgian KBO/BCE number). Use peppol validate peppol-id to verify format and registration.

Available Commands

peppol auth                                    # Authenticate (interactive)
peppol auth status                             # Show auth status
peppol auth logout                             # Remove credentials

peppol me                                      # Show account info

peppol workspace list                          # List workspaces (alias: ws)
peppol workspace add <name>                    # Add workspace
peppol workspace use <name>                    # Switch active workspace
peppol workspace remove <name>                 # Remove workspace

peppol stats                                   # Usage statistics

peppol document get <id>                       # Show document (alias: doc)
peppol document get <id> --full                # Include line items
peppol document timeline <id>                  # Processing events
peppol document create json <file>             # Create from JSON
peppol document create ubl <file>              # Create from UBL/XML
peppol document create pdf <file>              # Create from PDF (OCR)
peppol document send <id>                      # Send via Peppol
peppol document validate <id>                  # Validate (BIS Billing 3.0)
peppol document delete <id> --yes              # Delete draft
peppol document ubl <id>                       # Download UBL XML

peppol document attachment list <doc-id>       # List attachments (alias: att)
peppol document attachment get <id> <att-id>   # Show attachment details
peppol document attachment get <id> <att> -o f # Download attachment
peppol document attachment add <id> <file>     # Upload attachment
peppol document attachment delete <id> <att>   # Delete attachment

peppol inbox list                              # All received documents
peppol inbox invoices                          # Received invoices
peppol inbox credit-notes                      # Received credit notes

peppol outbox list                             # All sent documents
peppol outbox drafts                           # Sent drafts

peppol drafts list                             # All drafts

peppol mailbox list                            # Inbound emails
peppol mailbox list --status failed            # Filter: pending|success|failed
peppol mailbox get <email-id>                  # Show inbound email
peppol mailbox attachment <id> <file> -o f     # Download email attachment (alias: att)
peppol mailbox reprocess <email-id>            # Retry a failed email

peppol backup <dir>                            # Archive all documents to <dir>
peppol backup <dir> --layout=tree              # Per-document directories
peppol backup <dir> --concurrency=16           # Parallel workers (default 8)

peppol lookup <peppol-id>                      # Look up participant
peppol lookup search <query>                   # Search participants by name

peppol validate peppol-id <id>                 # Validate Peppol ID
peppol validate json <file>                    # Validate JSON document
peppol validate ubl <file>                     # Validate UBL/XML document

peppol version                                 # Show version
peppol completion bash|zsh|fish|powershell     # Shell completions

Common Workflows

Send an invoice from JSON:

# 1. Create the document (returns document ID)
peppol document create json invoice.json --construct-pdf --json

# 2. Validate against Peppol BIS Billing 3.0
peppol document validate <document-id> --json

# 3. Send via the Peppol network
peppol document send <document-id> --json

Process incoming invoices:

# 1. List recent inbox items
peppol inbox invoices --json --page-size 50

# 2. Get full document details with line items
peppol document get <document-id> --full --json

# 3. Download the UBL XML
peppol document ubl <document-id> -o invoice.xml

Check a trading partner:

# Search by company name
peppol lookup search "Company Name" --country BE --json

# Or validate a known Peppol ID
peppol validate peppol-id 0208:0123456789 --json

Back up the tenant archive:

# First run: full backup of every document, attachment, UBL, and timeline.
peppol backup ./peppol-archive --json

# Re-running is safe and idempotent:
#  - if the previous run was killed mid-flight, it resumes
#  - if it completed, it tops up new documents and refreshes DRAFT/TRANSIT only
peppol backup ./peppol-archive --json

manifest.json at the root of the directory records the tenant, layout, and run history. The directory state decides what re-running does — there are no --resume or --since flags. See Backup for layout details and the refresh policy.

Create invoice from PDF (OCR):

# Create with tax ID hints for better OCR accuracy
peppol document create pdf invoice.pdf --vendor-tax-id BE0123456789 --customer-tax-id BE9876543210 --json

# Check if OCR succeeded (inspect "success" field; when false,
# "error_type" and "error_message" give the reason)
# Then validate and send as usual
peppol document validate <document-id> --json
peppol document send <document-id> --json

Reference Documentation

• Authentication & Workspaces -- auth flows, workspace management, credentials
• Documents -- create, get, send, validate, delete, download UBL
• Attachments -- list, get, add, delete attachments
• Inbox & Outbox -- browse received/sent documents, filtering, pagination
• Mailbox -- inbound emails, attachment download, reprocess failed emails
• Lookup & Validate -- Peppol ID lookup, search, format validation
• Account -- tenant info, usage statistics
• Backup -- archive every document, resume, top-up, layouts

Discovering Options

Use --help on any command to see all available flags:

peppol --help
peppol document --help
peppol document create --help
peppol inbox list --help

Notable command aliases for brevity:

• doc for document
• att for attachment
• ws for workspace