peppol-cli

peppol-cli is a scriptable command line tool for the everyday work of running and debugging Peppol participation. One executable, peppol, answers the questions that currently need a browser and several separate web forms: is this participant registered, what can it receive, at which endpoint, with which certificate, and is that certificate still trustworthy? It covers identifier validation, the full DNS discovery chain, SML and SMP (read and write), the Peppol Directory, certificate and PKI checks, the code lists, and document validation against a configured Phorm instance. Machine-readable JSON output and distinct exit codes are core features, so the same commands work equally well in a terminal and in a CI pipeline.

Project status: planning. Nothing is implemented. This wiki captures scope, features, decisions and open questions so that they can be reviewed before the first line of code is written. Feature entries carry a status of proposed, accepted, deferred or rejected; uncertain facts are marked TODO(verify) and are awaiting review by a Peppol domain expert.

Who it is for

Audience	What they get
AP and SMP operators	Verify your own registrations, endpoints and certificate expiry; administer SMP content without the web UI.
Integrators	Find out why a document will not reach a receiver, one resolution step at a time.
Support engineers	Answer a participant question in seconds, without a development environment.
CI pipelines	Regression-check registrations, certificate expiry and endpoint health; fail the build on a change.

Pages

Page	Contents
Vision and Scope	The goal, what is in scope, what is out of scope and why.
Feature Catalogue	Every planned command, per area, with a status and the libraries involved.
Requirements	Normative requirements with stable IDs. Currently the update check only.
CLI Conventions	Command structure, global options, exit codes, the JSON output contract, completion.
Configuration	Config file format and location, network profiles, keystores, credentials, secrets handling.
Architecture	Language, build, module split, dependencies and packaging.
Testing Strategy	The six test tiers, fixture discipline and how correctness is actually verified.
Library Gaps	What the existing libraries do not provide yet, and where each gap belongs.
Specifications	The normative specs consulted, with versions, and what is still to be read.
Naming	Why peppol-cli and peppol, and which alternatives were rejected.
Decisions	The ADR log — the decisions taken so far, with consequences.
Open Questions	What is still undecided, and what each answer depends on.
Roadmap	Draft milestones, in dependency order.
Glossary	Short definitions of the Peppol and tooling terms used across this wiki.

Design principles

1. Read-only first. The useful core is lookups and diagnostics; anything that changes state is opt-in, explicit and protected by a dry run.
2. Scriptable by default. Stable JSON on stdout, diagnostics on stderr, and an exit code that says what kind of thing went wrong.
3. Reuse, do not reimplement. Identifiers, SML, SMP, code lists and validation all have maintained libraries already; this tool is the command line around them.
4. Explain the failure. When a lookup fails, say which step failed — not just that it did.
5. Do one job. No AS4, no message exchange, no mock AP. See ADR-001.

Contributing to the planning

Corrections to the TODO(verify) markers are the most valuable contribution right now. Disagreement with a decision belongs in Decisions as a new ADR that supersedes the old one, rather than as an edit to the original entry — the history of why something was chosen is worth keeping.