How Can a CLI Explain Its Time-Zone Assumption?
From the earlier reference collection. Read the current software blog.
Make the zone behind local-time calculations visible in help and results so the same input does not silently mean different instants.
Local time needs a named frame
A timestamp such as 2026-11-01 01:30 does not always identify one unique instant. It has no stated zone, and in regions that change clocks, a local time may occur twice or may not occur at all. A command that uses local times for filtering, schedules, or aggregation therefore needs a clear rule for interpreting them.
Do not let the machine's configured zone become an invisible part of the program's behavior. Two users running the same command can otherwise receive different results from the same text input.
Expose the selected zone
If the tool accepts a zone option, name it explicitly, such as --timezone America/Los_Angeles, and document the default. If it uses the system zone, say so in help and print the resolved zone when local times affect the output. A message like Interpreting input times in America/Los_Angeles is more useful than a vague “local time” label.
When displaying a result, include a zone or numeric offset. For example, 2026-11-01 01:30 -07:00 distinguishes one occurrence from 2026-11-01 01:30 -08:00. If the source provided no zone, be clear that the program applied an assumption.
Define edge-case behavior
Document what happens during clock transitions. A nonexistent local time might be rejected, while an ambiguous one might require an explicit offset or a policy choice. The right behavior depends on the tool's purpose, but silently selecting one interpretation can shift an event by an hour without an obvious error.
For a report that groups readings by day, also state whether the day boundary follows the chosen zone or UTC. A date label is not enough to infer that rule. Keep parsing, filtering, and display policies consistent or name each one separately.
Make reruns comparable
Include the selected zone in diagnostic output or an export's metadata, and allow a user to override it for reproducibility. A saved command such as sensor-report --timezone UTC --from ... is easier to rerun on another machine than one that depends on an undocumented host setting.
A brief explanation in both help and output prevents a large class of confusing discrepancies. It tells the operator which clock the program used, how to express a different one, and what to expect around transitions.