weatherreporter/docs/cli.md

Weatherreporter CLI

weatherreporter generates Markdown weather reports and runs report batches. 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 --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.

generate accepts the four report command names shown above. run accepts only morning and evening. 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. Successful summaries always report the resulting absolute outputPath values. See the configuration reference for the field's validation and path rules.

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.

Action commands (generate and run) 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.

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

Flag Reference

Flag	Accepted by	Meaning
-h, --help	top level	Show help.
--config PATH	all commands	Load PATH instead of /usr/local/etc/weatherreporter/config.yml.
--units VALUE	generate, run	Override weather_api.units for this command.
--tz NAME	generate, run	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 and run command	Write requested sensitive prompt diagnostics under this absolute path.
--out-dir PATH	run morning, run evening	Write batch reports beneath this directory instead of the configured or current-directory default.
--quiet	generate, run	Suppress action summaries and routine batch status output.
--date YYYY-MM-DD	generate daily, generate 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