CSV_TO_PDF_REPORT/code/CLI_CONTRACT.md

CLI Render Contract

The desktop app (Story: “Launch a text-only render from the desktop app”) integrates against this contract, not against EnvelopeRenderer.Cli's internals. Treat it as the stable interface between the two; changing it is a cross-cutting decision, not a local one.

Implementation: src/EnvelopeRenderer.Cli.

Arguments

All three are required. There is no short form and no = form in this MVP — keep the surface intentionally small per the story's conversation notes.

Argument	Value	Notes
--template <path>	Local or UNC path to the XML template	Must exist and be readable.
--csv <path>	Local or UNC path to the CSV data file	Must exist and be readable.
--output <path>	Local or UNC path to write the rendered PDF to	Parent directory must already exist; the CLI does not create directories.
-h, --help	—	Prints usage to stdout and exits 0. Overrides everything else on the command line.

Unknown arguments, a flag given without a value, a flag given twice, or an empty value are all usage errors (exit 2).

stdout / stderr rules

• stdout is reserved for machine-readable output: today just --help text (human-readable by exception, since it's explicitly for a human at a terminal); starting with the “Emit machine-readable progress during render” story, line-oriented progress events land here too. The desktop app should be able to treat stdout as parseable and never need to filter noise out of it.
• stderr carries every error, one per line, each prefixed ERROR: . Multiple problems (e.g. two missing arguments) are each reported as their own line rather than stopping at the first.

Exit codes

Code	Meaning
0	Success — PDF written to --output.
1	Template, CSV, or render error: malformed/invalid template XML, a template column not present in the CSV header row, an empty CSV, a missing/unresolvable font, or a Debenu render/save failure (including a missing or invalid license key — see below). Read stderr for which.
2	Invalid usage — missing, unknown, duplicate, or empty-valued argument.
3	Input not found — --template or --csv path does not exist.
4	Output path invalid — output directory does not exist, or the output path is itself an existing directory.

Validation runs in this order and stops at the first failing stage: usage → input paths → output path → render. A caller can rely on, e.g., never seeing an output-path error (4) while an input path is still missing.

Rendering

The text-only template format (--template) is documented separately in TEMPLATE_FORMAT.md.

Debenu license key

Rendering (not argument validation) requires a Debenu Quick PDF Library 10.13 license key at runtime, read from the DEBENU_LICENSE_KEY environment variable. Without it, every render fails at the save step with exit 1 — confirmed directly against the vendor DLL: page creation, font embedding, and text drawing all succeed, but SaveToFile/SaveToString both return error code 999 regardless of content. A working key for local development is kept at the project root in key.txt (untracked — never commit it or hardcode it into source).

UNC paths

Local and UNC paths are both accepted and validated identically — System.IO.File.Exists / Directory.Exists handle UNC paths natively, so there's no special-case code. What is not yet defined is timeout/retry behavior against a slow or unreachable UNC share; that's an open impediment (logs/impediment_log.md, logged 2026-09-04) carried as an explicit risk into the Debenu render story, not solved here.

Smoke examples

Run from code/:

$ dotnet run --project src/EnvelopeRenderer.Cli -- --help
(usage text)
exit=0

$ dotnet run --project src/EnvelopeRenderer.Cli --
ERROR: Missing required argument '--template'.
ERROR: Missing required argument '--csv'.
ERROR: Missing required argument '--output'.
(usage text on stderr)
exit=2

$ dotnet run --project src/EnvelopeRenderer.Cli -- --template nope.xml --csv sample-data/wilson.csv --output out.pdf
ERROR: Template not found: 'nope.xml'.
exit=3

$ dotnet run --project src/EnvelopeRenderer.Cli -- --template envelope.xml --csv sample-data/wilson.csv --output nosuchdir/out.pdf
ERROR: Output directory does not exist: 'nosuchdir'.
exit=4

$ dotnet run --project src/EnvelopeRenderer.Cli -- --template sample-data/sample-envelope-template.xml --csv sample-data/wilson.csv --output out.pdf
ERROR: Failed to save PDF to 'out.pdf' (error code 999).
exit=1
# (DEBENU_LICENSE_KEY not set — see "Debenu license key" above)

$ DEBENU_LICENSE_KEY="$(cat ../key.txt)" dotnet run --project src/EnvelopeRenderer.Cli -- --template sample-data/sample-envelope-template.xml --csv "sample-data/87700 - 999999 - Wilson Township.csv" --output out.pdf
exit=0