Status: proposed, except where an ADR is referenced.

Build note, verified: several peppol-commons modules generate sources with JAXB/wsimport into target/generated-sources/xjc and need mvn generate-sources before IDE use. Worth stating in CONTRIBUTING so a first checkout does not look broken.

The tool is deliberately a thin command line layer over existing libraries. Verified against the local sources:

Only add a dependency outside this set when nothing in it does the job. In particular: no second HTTP client, no second JSON library, no second collections library.

> TODO(verify): the full transitive dependency set and its licences once the module list is fixed — the SOAP/JAX-WS stack behind peppol-sml-client and the dnsjava dependency are the ones most likely to surprise on size or on Java 25.

Four modules, mirroring the -core / -cli split already used by kaltblut and norma:

The point of the split is that the interesting logic is testable without a command line, and that the JSON contract lives in one module rather than being spread across command classes.

> TODO(decide): is four modules over-engineered for a tool this size? A single module with clean internal packages would build faster and is easier to navigate. The counter-argument is that peppol-cli-core is potentially reusable, and that the boundary is what stops output formatting leaking into logic.

Main class following the ecosystem's convention (com.helger.kaltblut.cli.KaltblutMain): com.helger.peppol.cli.PeppolCliMain. > TODO(verify): confirm the intended base package and groupId (see [Naming](Naming)).

• Command results are objects, not print statements. Every core operation returns a typed result; rendering happens once, in the output module. This is what makes the text and JSON outputs consistent by construction.
• One exception-to-exit-code mapping, in the commands module. Core throws typed exceptions; nothing else decides an exit code.
• --config before ConfigFactory. As noted in Configuration, ConfigFactory reads config.file during static initialisation, so the CLI builds its own MultiConfigurationValueProvider rather than relying on that timing.
• Network profile values come from the libraries, via EPeppolNetwork and ESML — not from constants in this project.
• Startup cost is a feature requirement. Avoid eager classloading of the JAXB and SOAP stacks for commands that do not need them; a peppol pid validate should not pay for peppol-sml-client.

Ordered by effort. The pattern in every case is: one signed, versioned release archive plus its SHA-256, and each channel points at it.

A container is a first-class channel here, not an afterthought: a CI agent can use the tool with no Java runtime installed, which removes the Java 25 prerequisite entirely for the audience most likely to script against it.

Image: phelger/peppol-cli on Docker Hub, following the existing phelger/phoss-ap convention. > TODO(decide): also publish to GHCR (ghcr.io/phax/peppol-cli)? It costs one more push step and some users prefer it.

Build, matching the ecosystem's existing Dockerfiles (phorm, phase4-peppol-standalone): multi-stage, with the Apache 2.0 licence header comment at the top. The runtime stage needs only a JRE — phorm already builds on a JRE 25 base image, so current bases are available. A JRE-only or jlink-trimmed runtime stage keeps the image small; > TODO(decide): eclipse-temurin:25-alpine, a jlink-produced runtime, or a distroless base?

Container-specific design points, which differ from the server images in this ecosystem because this is a short-lived CLI:

• ENTRYPOINT is the executable, CMD is --help. That makes docker run --rm phelger/peppol-cli smp lookup … read as the command it is, and a bare docker run self-documents.
• Run as a non-root user. The tool writes nothing except its cache, and that only when asked.
• Configuration by environment variable is the natural container idiom, and it is free: ph-config already maps peppol.cli.network to PEPPOL_CLI_NETWORK, so docker run -e PEPPOL_CLI_NETWORK=prod … works with no extra code. Mounting a config directory read-only (-v ~/.config/peppol-cli:/config:ro) is the alternative for people with many settings.
• Never bake key material into the image. Keystores are mounted read-only at run time. This must be stated explicitly in the documentation, because it is exactly the mistake people make.
• Do not allocate a TTY when piping. docker run -t corrupts a piped stream, so --output json | jq requires docker run --rm without -t. Colour and progress already switch off automatically when stdout is not a TTY, so the default behaviour is correct — but the footgun is common enough to document with a worked example.
• Exit codes pass through docker run unchanged, which is what makes the container usable in CI. Our range (0–7, see CLI Conventions) stays clear of Docker's own reserved 125–127, so a pipeline can always tell a tool verdict from a container failure.
• Multi-arch linux/amd64 and linux/arm64 via buildx. A pure-JVM image is architecture-agnostic in content, so this is only about the base image.
• Tags: X.Y.Z, X.Y and latest. Documentation should recommend pinning an exact version in CI and treat latest as a convenience for interactive use only.
• Document a shell alias, so people are not typing a long docker run line repeatedly:

  alias peppol='docker run --rm -e PEPPOL_CLI_NETWORK -v "$HOME/.config/peppol-cli:/config:ro" phelger/peppol-cli'

• Image size is where a native image would pay off most — a native binary in a minimal base would be a fraction of a JVM image. That is a genuine argument for Open Questions #1, and a reason to keep the Dockerfile's runtime stage easy to swap.

A packaging test should run the built image and assert a known command's output and exit code, exactly as for the fat JAR — see Testing Strategy.

Two distinct paths, and they should not be confused.

Step 1 — own tap (recommended starting point). A repository named homebrew-tap under the same GitHub account makes the tool installable as:

brew tap phax/tap
brew install peppol-cli
# or in one step
brew install phax/tap/peppol-cli

A tap has no notability requirements, no review queue and no gatekeeper, and it can be published the same day as the first release. What it takes:

1. A public repository homebrew-tap (the homebrew- prefix is what makes brew tap phax/tap work).
2. A formula Formula/peppol-cli.rb with: desc, homepage, url pointing at the release archive, its sha256, license "Apache-2.0", a depends_on "openjdk", an install block that puts the JAR under libexec and creates a wrapper in bin, a test do block, and a livecheck block so brew livecheck can spot new versions.
3. A release step that computes the SHA-256, updates url and sha256 in the formula and commits it — trivially automatable from the release workflow.

Java-specific formula points to get right:

• The JAR must not be put directly in bin. The convention is to install it into libexec and generate a small wrapper script that invokes java -jar, so openjdk is found via Homebrew rather than the user's PATH. Homebrew provides a helper for exactly this — > TODO(verify): the current helper name and signature (bin.write_jar_script, as used by existing Java formulae) against the Homebrew Formula Cookbook, rather than relying on memory.
• The Java 25 requirement is the main open risk. depends_on "openjdk" tracks Homebrew's current default JDK, which is a moving target, and versioned formulae (openjdk@21, openjdk@17) only exist for some versions. > TODO(verify): whether Homebrew's openjdk formula is currently at 25 or later, and whether an openjdk@25 exists. If neither, the choice is to relax the baseline for the Homebrew build, ship a jlink image as a cask, or wait.
• Completion scripts install via bash_completion.install / zsh_completion.install / fish_completion.install, which is why peppol completion <shell> should be able to write them at build time.
• Both arm64 and x86_64 macOS must work. A pure-Java formula is architecture-independent, which is one real advantage of not going native first.

Step 2 — homebrew-core (later, optional). Getting into homebrew-core means brew install peppol-cli with no tap, but the bar is much higher:

• Notability. homebrew-core declines formulae for projects without a track record; the documented guideline is a threshold of GitHub stars, forks and watchers. > TODO(verify): the current thresholds in Homebrew's "Acceptable Formulae" document — they have changed over time and should not be quoted from memory.
• A stable, versioned release (not a snapshot, not a git HEAD build), with a stable archive URL.
• An open source licence Homebrew accepts — Apache 2.0 qualifies.
• No duplication of an existing formula, and it must not be trivially replaceable by a one-line script.
• It must pass brew audit --strict --online --new and the CI build (brew test-bot), which includes a meaningful test do block. A good test here: run peppol pid validate on a known-good identifier and assert the output, since that needs no network.
• Maintenance obligation. Once in core, every release should be followed by a brew bump-formula-pr. That is an ongoing commitment, which is the real reason to start with a tap.

Practical sequence: ship releases → publish the tap → let usage accumulate → only then consider core.

The full plan — six test tiers from hermetic unit tests to manually-approved live write tests, fixture discipline, and the golden-file tests that make the JSON contract enforceable — is in Testing Strategy. It is planned as part of development from M1, not added afterwards.

Two architectural consequences worth stating here, because they constrain the module split above:

• peppol-cli-core must be usable without a command line and without the network, or T1 and T2 are impossible. That is the main justification for keeping it separate from peppol-cli-commands.
• The stubs (SMP, DNS resolver, Phorm) belong in a shared test-support module, so every tier can reuse them.

Several features in the Feature Catalogue need capabilities the libraries do not currently have — a GLN check-digit validator, a Directory search client, a reusable Phorm client, runtime code list access for diffing, and per-user config discovery. They are catalogued with their verified evidence and their proper home in Library Gaps. Most belong upstream rather than in this project.