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 writes an atomically replaced today.md in the current directory. See the configuration reference to supply the required Weather API endpoint.

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 and write each selected report beneath the current directory unless --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 default output is the report's filename in the current directory. --out PATH selects one output file instead. A relative path is resolved from the current directory; an absolute path is used as given. For a batch, the equivalent default is the current directory and --out-dir PATH selects its output directory. Successful summaries always report the resulting absolute outputPath values.

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.

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 file instead of its 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 current directory.
--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