npm package: @getpeppr/cli
Description: CLI tool for Peppol e-invoice validation and development
Author: getpeppr
Latest version: 0.2.2

# @getpeppr/cli

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

## Installation

```bash
# 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:

```bash
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:

```bash
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:

```bash
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:

```bash
# 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) |

## 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

```bash
# 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
```

## What it validates

The CLI runs three validation engines from the [@getpeppr/sdk](https://www.npmjs.com/package/@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)

Validation runs offline — no API key or network connection required. Only `lookup` needs an internet connection.

## Invoice format

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

```json
{
  "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](https://getpeppr.dev/docs/types/) for all available fields.

## Ready to send?

Once your invoice validates, send it to the Peppol network with the getpeppr SDK:

```bash
npm install @getpeppr/sdk
```

```typescript
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](https://getpeppr.dev) to get your API key.

## License

MIT