Skip to main content
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

Make sure that the installation is correct:

Authenticate

The CLI can get the API key from two sources.
The command opens the API settings page of the app in your browser and asks you to paste the API key. It calls GET /api/me/ to make sure that the key is valid, and then stores the key in a workspace.
Show the account of the key:
PEPPOL_API_KEY has priority over all stored keys. While the variable is set, the --workspace flag and the active workspace do not change the key that the CLI uses.Example: PEPPOL_API_KEY contains the key of a sandbox company. Then peppol outbox list -w production shows the outbox of the sandbox company. To use the stored key of a workspace, remove the variable with unset PEPPOL_API_KEY.

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

All commands now use the sandbox company.
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.
Keep the workspace of the sandbox company as the active workspace. Then a command without -w cannot send a document on the Peppol network.

Validate, create and send an invoice

This procedure uses a file invoice.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

The command shows 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

The command creates a document in the 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

With a sandbox company, the send does not use the Peppol network. See Test mode and sandbox companies.
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.
In a script, use --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:
string
Peppol scheme of the sender, for example 0208.
string
Identifier of the sender, without the scheme. Example: 1018265814.
string
Peppol scheme of the receiver, for example 0208.
string
Identifier of the receiver, without the scheme. Example: 0848934496.
string
deprecated
Email address for the email query parameter of the send call. This parameter is deprecated. Do not use it.
Example:

Other common tasks

Create a document from UBL or PDF

The flags --vendor-tax-id and --customer-tax-id are optional. See Send UBL documents and Create documents from PDF.

Validate

For the Peppol ID check, see Look up Peppol participants.

Look up a participant

List documents

All list commands accept --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

The command writes each document, its attachments, its UBL XML and its timeline to the directory.

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

With --json, peppol validate json and peppol validate ubl write the validation result and stop with exit code 0, also when the document is not valid. In a script that uses --json, read the field is_valid from the output. A 406 response of the API (for example a total that is not correct) still gives exit code 1. peppol document validate does not use exit code 3 in any mode.
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