@getpeppr/cli

Developer toolkit for Peppol e-invoicing. Scaffold invoices, validate against Peppol BIS 3.0, convert to UBL XML, look up participants in the Peppol Directory, and send invoices to the Peppol network — all from the command line.

Installation

# Run directly (no install)
npx @getpeppr/cli validate invoice.json

# Or install globally
npm install -g @getpeppr/cli
getpeppr --help

Commands

getpeppr init — Scaffold an invoice

Generate a starter JSON file with all required fields pre-filled:

getpeppr init                        # creates invoice.json
getpeppr init my-invoice.json        # custom filename
getpeppr init --credit-note          # credit note template
getpeppr init --force                # overwrite existing file

The generated template includes a Belgian seller, a German buyer, and two invoice lines — ready to edit and validate.

getpeppr validate — Validate an invoice

Run offline validation against Peppol BIS 3.0 business rules:

getpeppr validate invoice.json

Output:

Validating: invoice.json

── Structure ──────────────────────────────
  ✓ No errors

── Business Rules (Peppol BIS 3.0) ───────
  ✓ All rules passed

── Country Rules ────────────────────────────
  ⚠ No structured communication reference (BE-02)

── Summary ──────────────────────────────────
  ✓ Invoice is valid (1 warning)

| Flag | Description | |------|-------------| | --json | Machine-readable JSON output | | --quiet | Exit code only, no output |

getpeppr convert — Convert to UBL XML

Convert a getpeppr JSON invoice to Peppol BIS 3.0 UBL 2.1 XML:

getpeppr convert invoice.json                     # XML to stdout
getpeppr convert invoice.json -o invoice.xml      # write to file
getpeppr convert invoice.json --validate           # validate first, convert only if valid

Automatically detects credit notes ("isCreditNote": true) and produces the correct UBL CreditNote document.

| Flag | Description | |------|-------------| | -o, --output <file> | Write XML to file instead of stdout | | --validate | Validate before converting (errors block conversion) |

getpeppr lookup — Peppol Directory search

Look up any participant registered on the Peppol network:

# Direct lookup by Peppol ID
getpeppr lookup 0208:BE0685660237

# Search by company name
getpeppr lookup --name "Dupont"

# Filter by country
getpeppr lookup --name "GmbH" --country DE

# JSON output
getpeppr lookup 0208:BE0685660237 --json

| Flag | Description | |------|-------------| | --name <name> | Search by company name (min 3 characters) | | --country <code> | Filter by ISO 2-letter country code | | --json | Output results as JSON | | --limit <n> | Max results for search (default: 10) |

getpeppr login — Save your API key

Store a getpeppr API key in ~/.config/getpeppr/credentials.json (mode 0600). Sandbox and live keys can coexist.

# Interactive (recommended) — prompts for the key with masked input
getpeppr login

# Explicit env (required in CI / non-TTY)
getpeppr login --key sk_sandbox_... --sandbox
getpeppr login --key sk_live_...    --live

| Flag | Description | |------|-------------| | --key <key> | API key. CI use only — visible in ps/shell history. Prefer the prompt or GETPEPPR_API_KEY. | | --sandbox | Store as sandbox key (default) | | --live | Store as live (production) key |

API key resolution order: --key flag → GETPEPPR_API_KEY env var → stored credentials.

getpeppr send — Send an invoice to Peppol

Send an invoice through the getpeppr API to the Peppol network. Targets sandbox by default; pass --prod for production.

# Send a JSON file
getpeppr send invoice.json

# Quick test — synthesize an invoice from flags (no file needed)
getpeppr send --to 0208:BE0314595348 --amount 100 --desc "Test invoice"

# Watch delivery status until terminal (60s timeout)
getpeppr send invoice.json --watch

# Production send — requires confirmation (skip with -y)
getpeppr send invoice.json --prod

| Flag | Description | |------|-------------| | [file] | Path to invoice JSON (mutex with --to/--amount/...) | | --prod | Target production (uses live key + confirmation prompt) | | --local | Target http://localhost:3001 (dev server) | | --key <key> | Override stored API key | | --to <peppol-id> | Recipient Peppol ID (when no file) | | --amount <number> | Line amount in major currency units | | --currency <iso> | ISO 4217 code (default EUR) | | --desc <text> | Line description | | --attachment | Attach the bundled test PDF | | --watch | Poll status until terminal (60s timeout) | | -y, --yes | Skip the --prod confirmation prompt | | --no-validate | Skip local pre-validation | | --json | Machine-readable JSON output | | --quiet | Exit code only, no output |

getpeppr logout — Remove stored credentials

getpeppr logout

Removes ~/.config/getpeppr/credentials.json. No-op if the file doesn't exist.

Exit codes

| Code | Meaning | |------|---------| | 0 | Success (valid invoice, participant found, conversion OK) | | 1 | Failure (invalid invoice, participant not found) | | 2 | Input error (file not found, invalid JSON, bad arguments) |

CI/CD integration

# Fail pipeline if invoice is invalid
getpeppr validate invoice.json --quiet || exit 1

# Validate + convert in one step
getpeppr convert invoice.json --validate -o output.xml

# Send via API key in env (no login state needed)
GETPEPPR_API_KEY=$SANDBOX_KEY getpeppr send invoice.json --json

What it validates

The CLI runs three validation engines from the @getpeppr/sdk:

1. Structure — Required fields, type checks, format validation
2. Business Rules — Peppol BIS 3.0 / EN 16931 compliance (BR-xx, BR-CO-xx, PEPPOL-xx rules)
3. Country Rules — Belgium (BE), France (FR), Italy (IT), Netherlands (NL), Germany (DE)

Scaffolding (init), validation, and conversion run fully offline — no API key or network connection required. Only lookup and send need a network connection.

Invoice format

The input file must be a JSON object matching the getpeppr InvoiceInput type:

{
  "number": "INV-2026-001",
  "date": "2026-01-15",
  "dueDate": "2026-02-15",
  "currency": "EUR",
  "buyerReference": "PO-2026-042",
  "from": {
    "name": "Dupont & Fils SPRL",
    "peppolId": "0208:BE0123456789",
    "street": "Avenue Louise 54",
    "city": "Bruxelles",
    "postalCode": "1050",
    "country": "BE"
  },
  "to": {
    "name": "Müller & Partner GmbH",
    "peppolId": "0204:DE987654321",
    "street": "Friedrichstraße 123",
    "city": "Berlin",
    "postalCode": "10117",
    "country": "DE"
  },
  "lines": [
    {
      "description": "Conseil en transformation numérique",
      "quantity": 10,
      "unitPrice": 950,
      "vatRate": 21
    },
    {
      "description": "Software license — annual subscription",
      "quantity": 1,
      "unitPrice": 2400,
      "vatRate": 0,
      "vatCategory": "AE"
    }
  ],
  "paymentTerms": "Net 30 days",
  "paymentReference": "+++000/0000/00097+++"
}

This is the exact template generated by getpeppr init. See the full type reference for all available fields.

Ready to send?

Once your invoice validates, send it to the Peppol network — straight from the CLI:

getpeppr login                       # store your sandbox key once
getpeppr send invoice.json --watch   # send + poll delivery status

Or, for programmatic use inside an app, install the SDK:

npm install @getpeppr/sdk

import { Peppol } from "@getpeppr/sdk";

const peppol = new Peppol({ apiKey: "your-api-key" });
const result = await peppol.invoices.send(invoice);

Sign up at getpeppr.dev to get your API key.

License

MIT