peppol CLI

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

brew tap e-invoice-be/tap
brew install e-invoice-be/tap/peppol-cli

Use Homebrew:

brew tap e-invoice-be/tap
brew install e-invoice-be/tap/peppol-cli

As an alternative, download the linux_amd64 or linux_arm64 archive from GitHub Releases, extract it, and move the peppol file to a directory in your PATH.

Download the .zip file for Windows from GitHub Releases, extract it, and add peppol.exe to your PATH.

Make sure that the installation is correct:

peppol version

Authenticate

The CLI can get the API key from two sources.

Interactive
Environment variable

peppol auth

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 authentication status
peppol auth status

# Remove the stored key of the active workspace
peppol auth logout

export PEPPOL_API_KEY="your-api-key"

Use this method in scripts and in CI. The CLI stores nothing.

Show the account of the key:

peppol me

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.

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.

Command	Function
`peppol workspace add <name>`	Asks for an API key, makes sure that it is valid, and stores it with this name
`peppol workspace list`	Shows all workspaces and the active workspace
`peppol workspace use <name>`	Makes a workspace the active workspace
`peppol workspace remove <name>`	Removes a workspace and its stored key

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

Add a workspace for each company

Paste the API key of the related company when the command asks for it.

peppol workspace add sandbox
peppol workspace add production

Make the workspace of the sandbox company the active workspace

peppol workspace use sandbox

All commands now use the sandbox company.

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.

peppol outbox list -w production

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.

Validate the JSON file

peppol validate json invoice.json

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.To read the JSON from standard input, use --file -:

cat invoice.json | peppol validate json --file -

Create the document

peppol document create json invoice.json

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.

Send the document

peppol document send <document-id>

With a sandbox company, the send does not use the Peppol network. See Test mode and sandbox companies.

Examine the result

peppol document get <document-id>
peppol document timeline <document-id>

In a script, use --json and get the document ID from the output. This sample uses jq:

DOCUMENT_ID=$(peppol document create json invoice.json --json | jq -r '.id')
peppol document send "$DOCUMENT_ID" --json

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

Peppol ID of the sender.

string

Peppol scheme of the receiver.

string

Peppol ID of the receiver.

string

Email address for the email parameter of the send call.

Other common tasks

Create a document from UBL or PDF

# From a UBL XML file
peppol document create ubl invoice.xml

# From a PDF file
peppol document create pdf invoice.pdf --vendor-tax-id BE1018265814 --customer-tax-id BE0848934496

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

Validate

# A UBL XML file
peppol validate ubl invoice.xml

# A document that is already in your account
peppol document validate <document-id>

# A Peppol ID: format and registration on the network
peppol validate peppol-id 0208:0848934496

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

Look up a participant

peppol lookup 0208:0848934496
peppol lookup search "OpenPeppol" --country BE

List documents

peppol inbox list
peppol inbox invoices
peppol inbox credit-notes
peppol outbox list
peppol drafts list

The list commands accept the flags --page, --page-size, --from, --to, --search, --type, --sort-by and --sort-order. The inbox commands also accept --sender. peppol outbox list also accepts --receiver.

Download, delete and attach

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

# Delete a draft document
peppol document delete <document-id>

# Attachments
peppol document attachment list <document-id>
peppol document attachment add <document-id> terms.pdf
peppol document attachment get <document-id> <attachment-id> -o terms.pdf

Usage statistics

peppol stats
peppol stats --from 2026-01-01 --to 2026-03-01 --aggregation MONTH

--aggregation accepts DAY, WEEK or MONTH. See Usage statistics and credits.

Back up all documents

peppol backup ./peppol-archive

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:

Flag	Short form	Function
`--json`	`-j`	Writes the output as JSON
`--quiet`	`-q`	Does not write output that is not essential
`--verbose`	`-v`	Writes more information
`--no-color`		Does not use colours in the output
`--workspace <name>`	`-w`	Uses this workspace for the command

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.

peppol document delete <document-id> --yes

Exit codes

Code	Meaning
`0`	The command was successful
`1`	General error, for example a file that does not exist or an error response from the API
`2`	Authentication error: no API key is available, or the API does not accept the key
`3`	Validation failed: `peppol validate json` or `peppol validate ubl` found that the document is not valid
`4`	Not found: the document or the attachment does not exist

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. 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:

{
  "error": "document not found",
  "code": 4
}

Sample script

#!/usr/bin/env bash
set -euo pipefail

# PEPPOL_API_KEY is set in the environment

if ! peppol validate json invoice.json --quiet; then
  echo "The invoice is not valid" >&2
  exit 1
fi

DOCUMENT_ID=$(peppol document create json invoice.json --json | jq -r '.id')
peppol document send "$DOCUMENT_ID" --json

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

Getting started

Send documents

Receive and manage

Other input formats

Integrate

SDKs and tools

Resellers

Reference

Install

Authenticate

Workspaces

Use a sandbox company and a production company together

Validate, create and send an invoice

Set the Peppol IDs for a send

Other common tasks

Create a document from UBL or PDF

Validate

Look up a participant

List documents

Download, delete and attach

Usage statistics

Back up all documents

Automation

Global flags

Confirmation prompts

Exit codes

Sample script

Shell completion

Use with AI agents

Report a problem

Next Steps

SDKs

Test mode and sandbox companies

Validation during development

Model Context Protocol (MCP)

​Install

​Authenticate

​Workspaces

​Use a sandbox company and a production company together

​Validate, create and send an invoice

​Set the Peppol IDs for a send

​Other common tasks

​Create a document from UBL or PDF

​Validate

​Look up a participant

​List documents

​Download, delete and attach

​Usage statistics

​Back up all documents

​Automation

​Global flags

​Confirmation prompts

​Exit codes

​Sample script

​Shell completion

​Use with AI agents

​Report a problem

​Next Steps

SDKs

Test mode and sandbox companies

Validation during development

Model Context Protocol (MCP)

Install

Authenticate

Workspaces

Use a sandbox company and a production company together

Validate, create and send an invoice

Set the Peppol IDs for a send

Other common tasks

Create a document from UBL or PDF

Validate

Look up a participant

List documents

Download, delete and attach

Usage statistics

Back up all documents

Automation

Global flags

Confirmation prompts

Exit codes

Sample script

Shell completion

Use with AI agents

Report a problem

Next Steps