weatherreporter/docs/cli.md

Weatherreporter CLI

weatherreporter generates Markdown weather reports, runs scheduled report batches, and inspects stored artifacts.

Shortest Useful Command

weatherreporter generate daily --date 2026-05-29 --out ./daily.md

This loads configuration, fetches weather data, writes managed workspace artifacts, runs scriptorium render as a preflight check, runs scriptorium run, and writes an extra Markdown copy to ./daily.md. If distributor notification is enabled in configuration, the command also uploads the managed Markdown report after final metadata is saved.

Commands

weatherreporter --help
weatherreporter generate daily [--config PATH] [--units VALUE] [--tz NAME] [--out PATH] [--date YYYY-MM-DD]
weatherreporter generate tomorrow [--config PATH] [--units VALUE] [--tz NAME] [--out PATH]
weatherreporter generate hourly [--config PATH] [--units VALUE] [--tz NAME] [--out PATH]
weatherreporter generate three-day [--config PATH] [--units VALUE] [--tz NAME] [--out PATH]
weatherreporter generate weekend [--config PATH] [--units VALUE] [--tz NAME] [--out PATH]
weatherreporter generate storm [--config PATH] [--units VALUE] [--tz NAME] [--out PATH] --start TIME --end TIME
weatherreporter run morning [--config PATH] [--units VALUE] [--tz NAME] [--out-dir PATH]
weatherreporter run evening [--config PATH] [--units VALUE] [--tz NAME] [--out-dir PATH]
weatherreporter inspect reports [--config PATH] [--limit N]
weatherreporter inspect metadata [--config PATH] RUN_ID
weatherreporter inspect modules [--config PATH] RUN_ID
weatherreporter inspect data-package [--config PATH] RUN_ID
weatherreporter inspect prior [--config PATH] RUN_ID
weatherreporter inspect sources [--config PATH] RUN_ID

Implemented generate commands write a JSON module snapshot, YAML data package, preflight artifact, managed Markdown report, and metadata under the configured workspace. --out writes an extra Markdown copy for the operator; distributor notification uses the managed report path, not the extra copy. generate hourly covers the next six hours in the effective report timezone, does not accept date or event window flags, writes managed generated-text artifacts, validates the structured text, and renders the managed Markdown report from the embedded hourly template. generate storm requires explicit event-window bounds with --start and --end.

run morning generates Daily Today and the 3-Day Outlook, plus Weekend Outlook except on Sunday. run evening generates the Tomorrow Report. Batch runs continue independent reports after a failure, print a JSON summary to stdout, write compact status lines to stderr, and return nonzero when any report failed. --out-dir writes extra Markdown copies for the operator; distributor notification uses each managed report path, not the extra copies. When notification is enabled, batch summaries and status lines include notification status, accepted distributor run ID, or notification error fields for each attempted report.

Hourly Report is explicit only; it is not included in run morning or run evening.

inspect commands read existing workspace artifacts and emit JSON to stdout. They do not fetch weather data or invoke scriptorium.

Flags

• -h, --help: show help.
• --config PATH: load configuration from PATH instead of /usr/local/etc/weatherreporter/config.yml.
• --units VALUE: override configured Weather API units for generate and run.
• --tz NAME: override configured Weather API timezone for generate and run.
• --out PATH: write an extra Markdown report copy where supported by the generate command.
• --out-dir PATH: write extra Markdown report copies for run morning and run evening.
• --date YYYY-MM-DD: optional date for generate daily; defaults to the current local date in the configured timezone.
• --start TIME: required start time for generate storm.
• --end TIME: required end time for generate storm.
• --limit N: maximum records for inspect reports; defaults to 20, and 0 means no limit.

Storm times accept YYYY-MM-DDTHH:MM in the configured timezone or RFC3339 timestamps with explicit offsets.

Distributor notification is configured only through notify.distributor; there are no distributor-specific CLI flags.

Common Workflows

weatherreporter generate tomorrow --out ./tomorrow.md
weatherreporter generate hourly
weatherreporter generate three-day --out ./three-day.md
weatherreporter generate weekend --out ./weekend.md
weatherreporter generate storm --start 2026-05-29T18:00 --end 2026-05-30T06:00 --out ./storm.md
weatherreporter run morning --out-dir ./reports
weatherreporter run evening --out-dir ./reports

Inspection

weatherreporter inspect reports --limit 10
weatherreporter inspect metadata 20260529T100000.000000000Z_daily_today
weatherreporter inspect modules 20260529T100000.000000000Z_daily_today
weatherreporter inspect data-package 20260529T100000.000000000Z_daily_today
weatherreporter inspect prior 20260529T100000.000000000Z_daily_today
weatherreporter inspect sources 20260529T100000.000000000Z_daily_today

inspect reports lists recent generated runs with artifact paths and source warning counts. The other inspect commands require a RunID. inspect modules returns the persisted ordered module snapshot for a run. inspect prior returns the prior comparable snapshot metadata selected from stored metadata, or null when none exists. inspect sources shows source provenance and source warnings without dumping full weather payloads.