weatherreporter/docs/cli.md

Weatherreporter CLI

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

Shortest Useful Command

weatherreporter generate today --out ./today.md

This loads configuration, fetches weather data, writes managed workspace artifacts, runs scriptorium render as a preflight check, runs structured scriptorium run, validates generated text, renders the embedded Today template, and writes an extra Markdown copy to ./today.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 --date YYYY-MM-DD [--config PATH] [--units VALUE] [--tz NAME] [--out PATH]
weatherreporter generate today [--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 daily, generate today, generate tomorrow, and generate hourly write managed generated-text artifacts, validate structured text from Scriptorium, and render the managed Markdown report from embedded templates. generate daily requires --date YYYY-MM-DD for the selected local civil day; omitting --date is a command error and stops before weather data is collected. generate hourly covers the next six hours in the effective report timezone and does not accept date or event window flags. generate storm requires explicit event-window bounds with --start and --end.

run morning generates Today Report, Tomorrow Report, and a dated Daily Report for each later future local civil day with complete hourly forecast coverage. run evening generates Tomorrow Report and the same eligible future Daily reports. Future Daily expansion starts with the day after tomorrow and skips days that do not have every hourly forecast period for the local civil day. Batch commands collect weather data once before planning; a collection failure stops the batch before any report is generated. Batch runs continue independent reports after a later report 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. Today and Tomorrow use their report default copy names, and dynamic Daily copies use daily-YYYY-MM-DD.md. 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, 3-Day Outlook, and Weekend Outlook are explicit only; they are 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: required date for generate daily; optional date for generate today, defaulting 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 today --out ./today.md
weatherreporter generate daily --date 2026-05-29 --out ./daily.md
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_today
weatherreporter inspect modules 20260529T100000.000000000Z_today
weatherreporter inspect data-package 20260529T100000.000000000Z_today
weatherreporter inspect prior 20260529T100000.000000000Z_today
weatherreporter inspect sources 20260529T100000.000000000Z_today
weatherreporter inspect metadata 20260529T100000.000000000Z_daily

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.