@getpeppr/cli 0.2.1 → 0.3.0

package/README.md

@@ -1,6 +1,6 @@
 # @getpeppr/cli
 
-The first Peppol e-invoice validator on npm. Validate invoices offline against Peppol BIS 3.0 business rules, structure checks, and country-specific requirements.
+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
 
@@ -10,12 +10,27 @@ npx @getpeppr/cli validate invoice.json
 
 # Or install globally
 npm install -g @getpeppr/cli
-getpeppr validate invoice.json
+getpeppr --help
 ```
 
-## Usage
+## Commands
+
+### `getpeppr init` — Scaffold an invoice
 
-### Validate 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
@@ -39,47 +54,69 @@ Validating: invoice.json
   ✓ Invoice is valid (1 warning)
 ```
 
-### Flags
-
 | Flag | Description |
 |------|-------------|
 | `--json` | Machine-readable JSON output |
 | `--quiet` | Exit code only, no output |
-| `--version` | Show version number |
-| `--help` | Show help |
 
-### Exit codes
+### `getpeppr convert` — Convert to UBL XML
 
-| Code | Meaning |
-|------|---------|
-| `0` | Invoice is valid (may have warnings) |
-| `1` | Invoice has errors — non-compliant |
-| `2` | File not found or invalid JSON |
-
-### JSON output
+Convert a getpeppr JSON invoice to Peppol BIS 3.0 UBL 2.1 XML:
 
 ```bash
-getpeppr validate invoice.json --json
+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
 ```
 
-Returns a structured result with errors and warnings grouped by category:
+Automatically detects credit notes (`"isCreditNote": true`) and produces the correct UBL CreditNote document.
 
-```json
-{
-  "structure": { "errors": [], "warnings": [] },
-  "schematron": { "errors": [], "warnings": [] },
-  "countryRules": { "errors": [], "warnings": [] },
-  "totalErrors": 0,
-  "totalWarnings": 1,
-  "valid": true
-}
+| 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
 ```
 
-### CI/CD integration
+| 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
@@ -90,7 +127,7 @@ The CLI runs three validation engines from the [@getpeppr/sdk](https://www.npmjs
 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)
 
-All validation runs offline — no API key or network connection required.
+Validation runs offline — no API key or network connection required. Only `lookup` needs an internet connection.
 
 ## Invoice format
 
@@ -99,30 +136,47 @@ The input file must be a JSON object matching the getpeppr `InvoiceInput` type:
 ```json
 {
   "number": "INV-2026-001",
-  "date": "2026-04-07",
-  "dueDate": "2026-05-07",
+  "date": "2026-01-15",
+  "dueDate": "2026-02-15",
   "currency": "EUR",
-  "buyerReference": "PO-12345",
-  "to": {
-    "name": "Buyer Company",
+  "buyerReference": "PO-2026-042",
+  "from": {
+    "name": "Dupont & Fils SPRL",
     "peppolId": "0208:BE0123456789",
-    "street": "123 Main St",
-    "city": "Brussels",
+    "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": "Consulting services",
+      "description": "Conseil en transformation numérique",
       "quantity": 10,
-      "unitPrice": 150,
+      "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+++"
 }
 ```
 
-See the [full type reference](https://getpeppr.dev/docs/types/) for all available fields.
+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?