Status: proposed. The format question is an open decision — see Open Questions #2 — but the resolution mechanism below is a concrete plan built on ph-config, which has been checked against its source.

1. Zero configuration for read-only use: peppol smp lookup must work on a fresh install with nothing but --network.
2. Named profiles, so an operator can keep test and production, or several customers, side by side.
3. A documented precedence chain, with a way to ask the tool which value won and where it came from.
4. Secrets separable from the rest, so the non-secret part can be committed to a repository.
5. Environment variable overrides for every setting, for CI use.

Mostly yes — it is the right base and should be reused rather than replaced. The following is verified against ph-commons/ph-config.

What ph-config already provides:

What ph-config does not provide, and the CLI must add:

Implementation gotcha worth recording now: ConfigFactory holds its default instance in a private static final field initialised at class load, and it reads config.file from system properties at that moment. So --config has to be translated into the system property before anything touches ConfigFactory, or the CLI has to build its own MultiConfigurationValueProvider instead of using the default one. The second option is cleaner for a CLI and is the recommendation.

Highest priority first, mapping onto ph-config priorities:

peppol config show prints every effective key, its value and its source, with secrets masked.

Discovery order per platform, first existing file wins (and peppol config init creates the first entry):

Cache directory: $XDG_CACHE_HOME/peppol-cli or ~/.cache/peppol-cli on Linux, ~/Library/Caches/peppol-cli on macOS, %LOCALAPPDATA%\peppol-cli\cache on Windows — overridable with peppol.cli.cache.dir.

The cache directory also holds the optional Mozilla NSS trust list override, in <cache-dir>/nss/. Each list is named mozilla-nss-root-certs-<version>-<yyyy-mm-dd>.p12 — the version and date in the name are what the CLI reads — accompanied by <same name>.p12.sha256. The directory is scanned, the highest version wins, and a list is used only when its version is strictly newer than the one bundled in ph-nss; see the TLS rows in the Feature Catalogue. The CLI never downloads or builds such a list — it is provisioned out of band. Note this is the one cache entry that is a trust input rather than a convenience copy, which is why it is version-gated, hash-checked, and why a hash mismatch stops the command instead of falling back.

> TODO(decide): macOS convention. Apple's own location is ~/Library/Application Support, but developer tools on macOS overwhelmingly use ~/.config. The table proposes ~/.config for consistency with Linux; confirm.

Two candidates, both already supported by ph-config, so neither adds a new dependency of its own:

TOML and YAML are not supported by ph-config and would mean writing a new IConfigurationSourceResourceTypeRegistrarSPI plus taking on a parser dependency. That cost is not justified by the benefit here.

Proposal: .properties, with dotted keys. Recorded as Open Questions #2 until confirmed.

Profiles are key prefixes, read through ConfigSubset. peppol.cli.profile selects the active one, --profile overrides it, and the two built-in profiles test and prod come from the shipped reference.properties so that the common case needs no user configuration at all.

Notes grounded in verified source:

• The Phorm keys mirror the existing precedent in phoss-ap, which uses verification.phorm.url and verification.phorm.token for the same two values — worth staying consistent with in spirit.

• Phorm authenticates with a shared secret sent in the X-Token HTTP header, so peppol.cli.phorm.token is a plain secret and belongs in the credentials file.

• The built-in network profiles should not be hard-coded here at all. peppol-commons already models them: EPeppolNetwork.TEST and EPeppolNetwork.PRODUCTION each pair a Directory URL with an ESML entry, and ESML carries the DNS zone, the management service URL and a "requires client certificate" flag. --network test|prod should map straight onto EPeppolNetwork, so the values track the library rather than this wiki. The values below are quoted from ESML and EPeppolNetwork in peppol-commons for review only:

  Network	SML DNS zone	SML management URL	Directory URL
  test	participant.sml.test.tech.peppol.org.	https://api.sml.test.tech.peppol.org/edelivery-sml	https://test-directory.peppol.eu
  prod	participant.sml.prod.tech.peppol.org.	https://api.sml.prod.tech.peppol.org/edelivery-sml	https://directory.peppol.eu

  > TODO(verify): the ESML source comments mark both entries as "valid from March 19th, 2026". Confirm these are the currently correct values and that no transition period or legacy zone still needs to be supported. > TODO(verify): ESML also has a DEVELOPMENT_LOCAL entry (zone smj.peppolcentral.org., http://localhost:8080). Should the CLI expose a third built-in profile for it, or is a user-defined profile the right way?

• The user-defined profile keys stay in place for private test environments, since ESML's companion SMLInfo is builder-based and supports custom SMLs.

• Note a real collision — three libraries bring their own ph-config configuration:

  Library	Its own configuration	Keys
  smp-client-base	SMPClientConfiguration — reads application.properties with an smp-client.properties fallback	trust store type/path/password
  peppol-directory-client 1.0.0	PDClientConfiguration	pdclient.keystore.path / .type / .password / .key.alias / .key.password, plus HTTP timeouts and proxy
  phorm (server side)	its own properties	phorm.api.requiredtoken etc. — not the CLI's concern, but the token must match

  Since all of them sit on ph-config, they will happily read the same application.properties the CLI might use, which means a key set in one place could silently configure something else. The CLI should configure each client programmatically from its own peppol.cli.* keys rather than letting these mechanisms discover files on their own — one visible configuration surface, one peppol config show. > TODO(decide): confirm the programmatic approach, and check whether each client actually allows full programmatic configuration or falls back to its own config in places. Note peppol-directory-client 1.0.0 ships an example-config/application.properties, which is the reference for the keys it reads.

• > TODO(decide): which authentication schemes the SMP write commands must support. Different SMP implementations differ here, and it drives the .auth.type key.

Rules, all of them deliberate:

1. Two files. Non-secret settings in config.properties, secrets in credentials.properties. The first can be committed or shared; the second must not be.
2. Environment variables override everything, and are the recommended way to supply secrets in CI — nothing needs to be written to disk. PEPPOL_CLI_PHORM_TOKEN and PEPPOL_CLI_KEYSTORE_PASSWORD come for free from ph-config's env var mapping.
3. Permission check. On a POSIX platform, if the secrets file is group- or world-readable, the tool prints a warning naming the file and the chmod 600 fix. peppol config init creates it with 0600. > TODO(decide): warn only, or refuse to read a world-readable secrets file?
4. No plaintext secrets in any example, ever. Documentation uses either an environment variable reference or an obvious placeholder. No example in this wiki contains a usable password.
5. Redaction. --verbose, --debug and config show mask every value whose key matches a password/token/secret pattern, and --debug must not print the X-Token or Authorization headers.
6. No keyring integration in the first version. > TODO(decide): is macOS Keychain / libsecret / Windows Credential Manager support wanted later?
7. Passwords are never accepted as command line arguments — they are visible in the process list. Environment variable, config file, or an interactive prompt on a TTY.

~/.config/peppol-cli/config.properties — non-secret, safe to commit:

# ---------------------------------------------------------------------------
# peppol-cli configuration
# Every key below can be overridden by an environment variable: upper-case the
# key and replace every non-alphanumeric character with an underscore, e.g.
#   peppol.cli.network  ->  PEPPOL_CLI_NETWORK
# Precedence (highest first): command line option, system property,
# environment variable, --config file, credentials file, this file,
# shipped defaults.
# ---------------------------------------------------------------------------

# Which network to use when --network is not given: test or prod.
# The built-in default is prod; set this to test to flip it for this machine.
peppol.cli.network = prod

# Default output format for every command: text or json
peppol.cli.output.format = text

# --- Update check -----------------------------------------------------------
# Checks at most once per 24h, runs concurrently with the command, 2s timeout,
# fails silently, and writes only to stderr when stderr is a TTY. The request
# carries nothing but the User-Agent - no identifiers of any kind.
# Also disabled by PEPPOL_NO_UPDATE_CHECK=1 or DO_NOT_TRACK=1.
updatecheck.enabled = true
# updatecheck.url = https://<host>/peppol-cli/latest.json

# --- Own key material -------------------------------------------------------
# Required only for SML/SMP write operations and TLS client authentication.
# The password belongs in credentials.properties, NOT here.
peppol.cli.keystore.path = /home/me/peppol/ap-keystore.p12
peppol.cli.keystore.type = PKCS12
peppol.cli.keystore.key.alias = my-ap-key

# --- SMP management ---------------------------------------------------------
# The SMP that the "peppol phoss-smp ..." administration commands target.
# Note: SMP write is not standardised, so this is the phoss-SMP write API.
peppol.cli.smp.url = https://smp.example.org
peppol.cli.smp.auth.type = basic
peppol.cli.smp.username = smp-admin
# password -> credentials.properties

# --- Phorm validation service ----------------------------------------------
# Documents sent here leave your machine. Point this at an instance you trust.
# Authentication is a shared secret sent in the X-Token header.
peppol.cli.phorm.url = https://phorm.example.org
# token -> credentials.properties

# --- Caching ----------------------------------------------------------------
peppol.cli.cache.enabled = true
# peppol.cli.cache.dir = /home/me/.cache/peppol-cli

# --- HTTP -------------------------------------------------------------------
# Time to establish a connection - a host that is down should fail fast
peppol.cli.http.connect.timeout = 10s
# Time to wait for a response once connected - generous, because a large
# document validation or a slow SMP can legitimately take a while
peppol.cli.http.read.timeout = 2m

# --- DNS ---------------------------------------------------------------------
# Overall budget for a DNS lookup. Note this is divided across the resolvers
# that are tried, so each single resolver gets roughly half of it.
peppol.cli.dns.timeout = 5s
# DNSSEC validation of the discovery chain. ON by default: the Peppol SML
# zones are signed, so this works - but your resolver must forward DNSSEC
# records, otherwise every lookup fails. Set to false, or pass --no-dnssec,
# if your resolver cannot do it.
peppol.cli.dns.dnssec.enabled = true
# Override the system resolvers, e.g. to query an authoritative server directly
# peppol.cli.dns.servers = 8.8.8.8,1.1.1.1
peppol.cli.http.retries = 2

# --- Bulk concurrency ------------------------------------------------------
# Concurrent requests PER resolved SMP, not in total. Values above 4 are
# accepted but produce a warning - an SMP operator cannot tell aggressive
# tooling from a small attack.
peppol.cli.bulk.parallel.per.smp = 2

# --- Proxy ------------------------------------------------------------------
# peppol.cli.proxy.host = proxy.example.org
# peppol.cli.proxy.port = 3128
# peppol.cli.proxy.nonproxyhosts = localhost,127.0.0.1,*.internal.example.org

# --- Network profile overrides ---------------------------------------------
# The built-in "test" and "prod" profiles come from peppol-commons
# (EPeppolNetwork + ESML) and need no configuration. Override these keys only
# for a private test environment.
# peppol.cli.network.mine.sml.zone            = participant.sml.example.org.
# peppol.cli.network.mine.sml.management.url  = https://sml.example.org/edelivery-sml
# peppol.cli.network.mine.directory.url       = https://directory.example.org

~/.config/peppol-cli/credentials.properties — secrets only, mode 0600:

# ---------------------------------------------------------------------------
# Secrets. chmod 600 this file. Do not commit it.
# In CI, set the equivalent environment variables instead and do not ship this
# file at all:
#   PEPPOL_CLI_KEYSTORE_PASSWORD, PEPPOL_CLI_SMP_PASSWORD, PEPPOL_CLI_PHORM_TOKEN
# ---------------------------------------------------------------------------

peppol.cli.keystore.password = <your keystore password>
peppol.cli.keystore.key.password = <your key password>
peppol.cli.smp.password = <your SMP API password>
peppol.cli.phorm.token = <your Phorm X-Token value>