peppol is the command-line tool for the e-invoice.be API. Use it to send a test invoice without code, to examine received documents, or to automate tasks in a shell script. The source is in the repository e-invoice-be/peppol-cli.
The CLI calls the single API host https://api.e-invoice.be. The API key selects the mode: a key of a sandbox company runs the commands in test mode.
Install
- macOS
- Linux
- Windows
Authenticate
The CLI can get the API key from two sources.- Interactive
- Environment variable
GET /api/me/ to make sure that the key is valid, and then stores the key in a workspace.Workspaces
A workspace is a name for one stored API key. Each company has its own API key, thus you use one workspace for each company. The CLI stores workspaces in~/.config/peppol-cli, or in $XDG_CONFIG_HOME/peppol-cli if that variable is set.
peppol auth also makes a workspace. Its name comes from the company name, or from the --workspace flag if you give it.
Use a sandbox company and a production company together
1
Add a workspace for each company
Paste the API key of the related company when the command asks for it.
2
Make the workspace of the sandbox company the active workspace
3
Use the production company for one command
The global flag
--workspace (short form -w) applies to one command only. The active workspace does not change.Validate, create and send an invoice
This procedure uses a fileinvoice.json with the invoice JSON. The Quickstart shows how to make this file.
Validation is not a separate mandatory call.
POST /api/documents/ rejects a payload that does not pass the same rules. Use POST /api/validate/json while you develop, because it returns all rule failures and the generated UBL.1
Validate the JSON file
Validation: PASSED, or Validation: FAILED with the number of errors and warnings and a table with the columns SEVERITY, RULE ID, MESSAGE and LOCATION. If the document is not valid, the exit code is 3.A total or a VAT rule that is not correct gives a different result. The API returns 406 with no issues array, and the CLI shows the error and stops with exit code 1. Example: "subtotal": 900.00 in a file with line amounts of 1000.00 gives exit code 1.To read the JSON from standard input, use --file -:2
Create the document
DRAFT state and shows its details. Record the document ID. Add --construct-pdf to let the API make a PDF from the document.3
Send the document
4
Examine the result
timeline shows the processing events (GET /api/documents/{document_id}/timeline). lifecycle shows the Peppol responses about the document, for example a rejection by the buyer (GET /api/documents/{document_id}/lifecycle). See Document lifecycle and delivery tracking.--json and get the document ID from the output. This sample uses jq:
Set the Peppol IDs for a send
peppol document send accepts flags that give the sender and the receiver explicitly:
Email address for the
email query parameter of the send call. This parameter is deprecated. Do not use it.Other common tasks
Create a document from UBL or PDF
--vendor-tax-id and --customer-tax-id are optional. See Send UBL documents and Create documents from PDF.
Validate
Look up a participant
List documents
--page (default 1), --page-size (default 20, maximum 100), --sort-by and --sort-order (asc or desc). --sort-by accepts created_at, invoice_date, due_date, invoice_total, customer_name, vendor_name and invoice_id.
All list commands also accept the filter flags --from, --to, --search and --type. The inbox commands also accept --sender. peppol outbox list and peppol outbox drafts also accept --receiver. peppol drafts list also accepts --state.
The CLI sends each filter flag to the API, but not each endpoint has the related query parameter. The API ignores a parameter that the endpoint does not have, and returns no error. This table shows the filter flags that have an effect:
Example:
peppol inbox invoices --from 2026-10-01 also shows the invoices from before 1 October 2026. To filter received invoices on the date, use peppol inbox list --type INVOICE --from 2026-10-01.
The CLI sends the values of --type and --state to the API without a change. Use a value of the API field document_type or state. Example: peppol outbox list --type CREDIT_NOTE --from 2026-10-01 or peppol drafts list --state FAILED. Write the dates as yyyy-mm-dd.
Download, delete and attach
Mailbox
--status accepts pending, success or failed. reprocess tries again to process a failed email. See Send invoices by email (Mailbox).
Usage statistics
--aggregation accepts DAY, WEEK or MONTH. See Usage statistics and credits.
Back up all documents
Automation
Global flags
These flags are available on all commands:Confirmation prompts
peppol document delete and peppol document attachment delete ask for a confirmation. In a script, add --yes to these two commands. --yes is not a global flag.
Exit codes
When a command fails and
--json is set, the CLI writes the error as JSON to standard error:
Sample script
Shell completion
peppol completion bash, peppol completion zsh, peppol completion fish and peppol completion powershell write a completion script for your shell.
Use with AI agents
An AI agent that can run shell commands can use the CLI with--json, --yes and the exit codes. To connect an AI assistant directly to your account without the CLI, use the MCP server. See Model Context Protocol (MCP).
Report a problem
Report a problem with the CLI in the issues of the repository.Next Steps
SDKs
Call the API with a typed client in your language
Test mode and sandbox companies
Learn how a sandbox company runs in test mode
Validation during development
Understand the validation result
Model Context Protocol (MCP)
Connect an AI assistant to your account