weatherreporter/docs/cli.md

Weatherreporter CLI

weatherreporter generates Markdown weather reports, runs report batches, and compares explicitly selected Promptkit profiles against one prepared report. It has no command for inspecting prior runs or application-owned state.

Shortest Useful Command

weatherreporter generate today

The command uses the configured Weather API and atomically writes today.md. With no configured output directory, it writes in the current directory. See the configuration reference to supply the required Weather API endpoint and choose an ordinary output directory.

Commands And Usage

weatherreporter --help
weatherreporter --version
weatherreporter generate daily --date YYYY-MM-DD [--config PATH] [--units VALUE] [--tz NAME] [--out PATH] [--llm-debug-dir PATH] [--quiet]
weatherreporter generate today [--config PATH] [--units VALUE] [--tz NAME] [--out PATH] [--date YYYY-MM-DD] [--llm-debug-dir PATH] [--quiet]
weatherreporter generate tomorrow [--config PATH] [--units VALUE] [--tz NAME] [--out PATH] [--llm-debug-dir PATH] [--quiet]
weatherreporter generate hourly [--config PATH] [--units VALUE] [--tz NAME] [--out PATH] [--llm-debug-dir PATH] [--quiet]
weatherreporter run morning [--config PATH] [--units VALUE] [--tz NAME] [--out-dir PATH] [--llm-debug-dir PATH] [--quiet]
weatherreporter run evening [--config PATH] [--units VALUE] [--tz NAME] [--out-dir PATH] [--llm-debug-dir PATH] [--quiet]
weatherreporter compare REPORT --profile PROFILE --profile PROFILE [--config PATH] [--units VALUE] [--tz NAME] [--date YYYY-MM-DD] [--out-dir PATH] [--replace] [--llm-debug-dir PATH] [--quiet]

weatherreporter --version prints the version embedded in the executable. Tagged release binaries report their semantic version tag; ordinary local builds report development.

Command	Contract
generate daily	Requires --date YYYY-MM-DD; the date is interpreted in the effective report timezone. Its default filename is daily-YYYY-MM-DD.md.
generate today	Accepts an optional --date YYYY-MM-DD; without it, the current local date in the effective report timezone is used. Its default filename is today.md.
generate tomorrow	Uses the next local civil day and writes tomorrow.md by default.
generate hourly	Covers the next six hours in the effective report timezone and writes hourly.md by default. It does not accept --date, --hours, or --duration.
run morning and run evening	Run their defined report batches beneath the configured output directory, or the current directory when none is configured. --out-dir selects another directory. --out is not accepted.
compare REPORT	Accepts daily, today, tomorrow, or hourly. It requires at least two distinct, nonblank --profile values in their supplied order. Daily requires --date; Today accepts it optionally; Tomorrow and Hourly do not accept it.

generate accepts the four report command names shown above. run accepts only morning and evening. compare always requires explicit profile selection: promptkit.profile is not used as a comparison default. Batch membership and notification ordering are described in the operations guide.

Output, Errors, And Quiet Mode

For generate, the report's default filename is placed beneath output.directory when configured, otherwise the current directory. --out PATH selects one complete output file instead. A relative path is resolved from the current directory; an absolute path is used as given. For a batch, the configured directory has the same role and --out-dir PATH selects its output directory instead. For compare, --out-dir PATH selects one exact bundle directory; otherwise the report-derived comparison directory is placed beneath the configured directory or current directory. --replace is required to replace an existing nonempty recognized comparison bundle. See the configuration reference for the field's validation and path rules and the comparison bundle contract for the bundle format.

Outputs are written atomically. A generation, rendering, write, or cancellation failure before publication leaves an existing destination unchanged. A notification failure occurs after publication, so the newly written output remains available.

SIGINT and SIGTERM cancel an active action. Weatherreporter lets that cancellation reach the action before exiting; when the action has a result, it emits the usual failed summary and exits nonzero. A canceled batch retains any reports that were already published, marks interrupted and unstarted reports as canceled, skips batch notification, and identifies cancellation separately from report failures.

Action commands (generate, run, and compare) write a JSON summary to stdout unless --quiet is set. run also writes compact per-report and batch status lines to stderr. A pre-run error, such as an invalid flag, missing required argument, or configuration-load failure, produces no partial JSON summary. When an action fails after it has produced a result, its summary has "status": "failed" and an error field.

--quiet is supported by action commands only. It suppresses action summaries and routine batch status output; it does not suppress command errors.

Generate Summary

A generate summary identifies the command, report, run, generation time, valid period, prompt version, timezone, and status. Successful output has an absolute outputPath:

{
  "command": "generate",
  "reportId": "today",
  "promptId": "weather.today_generated_text",
  "promptVersion": "2.0.0",
  "runId": "20260529T120000.000000000Z_today",
  "status": "succeeded",
  "timezone": "America/Chicago",
  "outputPath": "/srv/weather/today.md"
}

When available, the summary also includes the effective profileId, backendId, modelName, sourceWarnings, validationStatus, requested llmDebugPath, and compact Distributor notification result. It does not include historical or transient artifact paths such as metadata, prompt input, raw generated text, render context, or notification receipts.

Run Summary And Stderr

A run summary contains command, batch, status, startedAt, finishedAt, total, succeeded, failed, and a reports array. Each report item includes its identity, status, effective profile and model details when available, source warnings, validation status, and absolute outputPath after publication. The top-level summary may also contain a batch notification object and error. Batch status is failed if any report or the batch notification fails. The total, succeeded, and failed counters describe report items only, so a failed batch notification can leave failed at 0 while the top-level notification and action status are failed.

When cancellation stops a batch, the summary also includes a nonzero canceled count. Canceled reports have "status": "canceled"; they are not included in failed, and the action still has failed status and exits nonzero.

Without --quiet, batch status lines use this form:

report=today status=succeeded output="/srv/weather/reports/today.md"
batch=morning total=2 succeeded=2 failed=0 canceled=0

Compare Summary

A comparison summary contains these fields in this order: command, comparisonId, reportId, reportName, promptId, promptVersion, promptHash, status, startedAt, finishedAt, timezone, validPeriod, outputDirectory, manifestPath, dataPackagePath, total, succeeded, failed, results, and optional error. Published artifact paths and each successful results[].reportPath are absolute. results preserves the supplied profile order and each item contains position, profileId, optional backendId, modelName, status, optional validationStatus, optional reportPath, optional llmDebugPath, and optional safe error.

The comparison status is succeeded only when every selected profile succeeds and the bundle is published. Individual profile failures still publish a complete partial bundle and return a failed command result. Cancellation or a failure before publication omits the artifact paths and returns a safe top-level error; the resolved outputDirectory and finalized timestamp remain when available. The safe error includes only a category and message: aggregate and unclassified application failures use application; cancellation uses canceled; deadlines use deadline_exceeded; prompt execution uses its published Promptkit category; destination failures use destination_<kind>; and committed cleanup failures use publication_cleanup with a message that states whether a complete prior bundle, partial remnants, or no prior bundle remains, or that recovery state could not be inspected. It does not expose provider diagnostics, filesystem causes, or recovery paths. See the comparison bundle contract for durable artifact fields and failure invariants.

If the bundle is published but cleanup of its replaced prior bundle fails, the summary still includes the published artifact paths and has status failed. Its JSON error is publication_cleanup; the returned command error identifies a recovery path only when cleanup left a sibling behind. Only a reported complete prior bundle is a rollback artifact.

Flag Reference

Flag	Accepted by	Meaning
-h, --help	top level, compare	Show help without loading configuration or contacting a provider.
--config PATH	all commands	Load PATH instead of /usr/local/etc/weatherreporter/config.yml.
--units VALUE	generate, run, compare	Override weather_api.units for this command.
--tz NAME	generate, run, compare	Override weather_api.timezone for this command.
--out PATH	every generate command	Write the report to this complete file destination instead of the configured or current-directory default.
--llm-debug-dir PATH	every generate, run, and compare command	On Unix hosts, write requested sensitive prompt diagnostics under this absolute path. Other hosts fail closed when the flag is requested.
--profile PROFILE	compare	Select one explicit profile. Repeat at least twice with distinct, nonblank IDs.
--out-dir PATH	run morning, run evening, compare	Write batch reports beneath this directory, or select the exact comparison directory.
--replace	compare	Authorize replacement of a recognized nonempty comparison bundle.
--quiet	generate, run, compare	Suppress all action summaries and routine batch status output.
--date YYYY-MM-DD	generate daily, generate today, compare daily, compare today	Required for Daily; optional for Today.

Distributor notification is configured through notify.distributor; there are no Distributor-specific CLI flags. See the configuration reference.

Invocation Examples

weatherreporter generate daily --date 2026-05-29
weatherreporter generate today --out ./reports/today.md
weatherreporter generate hourly --out /srv/weather/hourly.md
weatherreporter generate today --llm-debug-dir /var/tmp/weatherreporter-debug
weatherreporter run morning --out-dir ./reports --llm-debug-dir /var/tmp/weatherreporter-debug
weatherreporter compare daily --date 2026-05-29 --profile weather-light --profile weather-balanced --out-dir ./comparison-daily-2026-05-29