CLI

Validate, scaffold, and convert offline — or send to Peppol with one command.

Installation

Install @getpeppr/cli globally or run it directly with npx.

Install globally

Terminal 
npm install -g @getpeppr/cli

Or use npx (no install)

Terminal 
npx @getpeppr/cli validate invoice.json

Scaffold an Invoice

Generate a starter JSON file with all required fields pre-filled — a Belgian seller, a German buyer, two invoice lines. Ready to edit, validate, and send.

Terminal 
# Default — creates invoice.json
getpeppr init

# Custom filename
getpeppr init my-invoice.json

# Credit note template
getpeppr init --credit-note

# Overwrite an existing file
getpeppr init --force
Flag Description
[filename] Output filename (default invoice.json)
--credit-note Generate a credit note template instead of an invoice
--force Overwrite an existing file

Validate an Invoice

Pass a JSON file to getpeppr validate to check it against three validation engines:

  • Structure — required fields, types, and format checks
  • Business Rules — Peppol BIS 3.0 / EN 16931 compliance
  • Country Rules — Belgium, France, Italy, Netherlands, Germany
Terminal 
getpeppr validate invoice.json

Example output

Output 
Validating: invoice.json

── Structure ──────────────────────────────
  ✓ No errors
  ⚠ to.vatNumber — Buyer VAT number not provided. May be required for B2B.

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

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

── Summary ──────────────────────────────────
  ✓ Invoice is valid (2 warnings)
Validation runs offline — no API key, no network connection, no account required. The CLI uses the same validation engine as the SDK (validateInvoice, validateSchematron, validateCountryRules). Sending invoices to Peppol does require an API key — see Send to Peppol below.

Validate Flags

Flag Description
--json Machine-readable JSON output
--quiet Exit code only, no output
--version Show version number
--help Show help

Convert to UBL XML

Convert a getpeppr JSON invoice to Peppol BIS 3.0 UBL 2.1 XML. Credit notes ("isCreditNote": true) are detected automatically and produce the correct UBL CreditNote document.

Terminal 
# Print UBL XML to stdout
getpeppr convert invoice.json

# Write to file
getpeppr convert invoice.json -o invoice.xml

# Validate before converting (errors block conversion)
getpeppr convert invoice.json --validate -o invoice.xml
Flag Description
-o, --output <file> Write XML to file instead of stdout
--validate Validate before converting — errors block conversion

Lookup the Peppol Directory

Search the public Peppol Directory to verify any participant on the network — by Peppol ID or company name.

Terminal 
# 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 for tooling
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)

Exit Codes

Code Meaning
0 Invoice is valid (may have warnings)
1 Invoice has errors — non-compliant
2 File not found or invalid JSON

JSON Output

Use --json for machine-readable output, ideal for CI pipelines and tooling.

Terminal 
getpeppr validate invoice.json --json
Result 
{
  "structure": { "errors": [], "warnings": [...] },
  "schematron": { "errors": [], "warnings": [] },
  "countryRules": { "errors": [], "warnings": [...] },
  "totalErrors": 0,
  "totalWarnings": 2,
  "valid": true
}

CI/CD Integration

Use --quiet in CI pipelines to gate deployments on invoice compliance.

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

# Or validate multiple files
for file in invoices/*.json; do
  getpeppr validate "$file" --quiet || exit 1
done

# Send via API key in env (no login state needed)
GETPEPPR_API_KEY=$SANDBOX_KEY getpeppr send invoice.json --json
The --quiet flag suppresses all output and relies only on exit codes. Combine with --json in CI to capture structured results for reporting.

Invoice Format

The input file must be a JSON object matching the InvoiceInput type. See the Type Definitions for all available fields.

invoice.json 
{
  "number": "INV-2026-001",
  "date": "2026-04-07",
  "dueDate": "2026-05-07",
  "currency": "EUR",
  "buyerReference": "PO-12345",
  "to": {
    "name": "Wayne Enterprises",
    "peppolId": "0208:BE0123456789",
    "street": "Avenue Louise 54",
    "city": "Brussels",
    "postalCode": "1050",
    "country": "BE"
  },
  "lines": [
    {
      "description": "Consulting services",
      "quantity": 10,
      "unitPrice": 150,
      "vatRate": 21
    }
  ]
}

Send to Peppol

Once your invoice validates, send it through the getpeppr API to the Peppol network — straight from the terminal. Sandbox is the default; pass --prod for production.

getpeppr login — Save your API key

Stores a getpeppr API key in ~/.config/getpeppr/credentials.json (mode 0600). Sandbox and live keys can coexist — the CLI picks the right one based on the target environment.

Terminal 
# Interactive (recommended) — masked input
getpeppr login

# Explicit (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
Resolution order: --key flag → GETPEPPR_API_KEY env var → stored credentials. In CI, prefer the env var pattern over login --key to avoid leaking the key into shell history.

getpeppr send — Send an invoice

Sends an invoice through the getpeppr API to the Peppol network. Pass either a JSON file or the synth flags (--to, --amount, --desc) — they're mutually exclusive.

Terminal 
# Send a JSON file (sandbox by default)
getpeppr send invoice.json

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

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

# Quick test — synthesize from flags
getpeppr send --to 0208:BE0314595348 --amount 100 --desc "Test invoice"
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 credentials

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

Terminal 
getpeppr logout

Next Steps

Need a programmatic API instead of the terminal? Use the SDK. Sign up at getpeppr.dev to get your API key.

Error Handling
Type Definitions