How Do You Make a CLI Output Reproducible?
From the earlier reference collection. Read the current software blog.
Control sorting, locale, and time-zone assumptions, and record the exact input version used to generate output.
Stabilize ordering and formatting
A command can read identical data and still produce different output if it follows filesystem order, locale-sensitive sorting, or unstable iteration over collections. Sort records by an explicit key before writing them. Choose a stable tie-breaker when keys can repeat, such as sorting by both route ID and stop sequence.
Formatting also needs a contract. Specify decimal precision, date representation, and character encoding. Locale settings can alter decimal separators or sort order; set a known locale for the command or implement locale-independent formatting. A report that changes from 1.25 to 1,25 can break a parser even when the underlying value is identical.
Make time assumptions explicit
Set or document the time zone used when converting timestamps. A program that interprets naive local times may produce different results on two machines. Prefer offset-aware input and a clearly defined output zone, often UTC for interchange. If a schedule uses a service-day convention beyond midnight, do not silently reduce a value such as 25:10:00 to an ordinary clock time; preserve the domain meaning defined by the feed.
Record the relevant software and schema versions when they can affect parsing or output. An output file alone may not reveal which interpretation rules produced it.
Identify the exact input
Record an input filename, release identifier, or checksum with the output. A URL by itself may point to changing data, so it does not identify what was processed yesterday. If the source provides a version or publication timestamp, keep that information; otherwise, a locally calculated checksum can distinguish byte-for-byte inputs.
For example, an output manifest might contain the command options, input digest, tool version, and generation time. Keep the manifest separate from the data if downstream consumers expect a strict CSV or JSON format. Avoid including credentials or private paths in provenance records.
Compare runs deliberately
To check reproducibility, run the same command twice against a fixed input and compare the output bytes. If they differ, inspect timestamps, random identifiers, ordering, line endings, and metadata fields before concluding that the data changed. A deterministic sort and fixed formatting often remove superficial differences.
Reproducibility does not mean every run must produce identical output when the input changes. It means the command’s assumptions are visible enough that the same input and options can be understood and, where intended, produce the same result. That makes debugging, review, and downstream comparisons far more dependable.