weatherreporter/docs/cli.md

Weatherreporter CLI

weatherreporter generates weather reports, runs report batches, and inspects artifacts already stored in its workspace.

Shortest Useful Command

weatherreporter generate today --out ./today.md

The command uses the configured Weather API and writes an extra Markdown copy at ./today.md. See the configuration reference to supply the required Weather API endpoint.

Commands And Usage

weatherreporter --help
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] [--quiet]
weatherreporter run evening [--config PATH] [--units VALUE] [--tz NAME] [--out-dir PATH] [--quiet]
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

Command	Contract
generate daily	Requires --date YYYY-MM-DD; the date is interpreted in the effective report timezone.
generate today	Accepts an optional --date YYYY-MM-DD; without it, the current local date in the effective report timezone is used.
generate tomorrow	Uses the next local civil day and accepts the common generate flags.
generate hourly	Covers the next six hours in the effective report timezone. It does not accept --date, --hours, or --duration.
run morning and run evening	Run their defined report batches. --out-dir writes extra Markdown copies; --out is not accepted.

generate accepts the four report command names shown above. run accepts only morning and evening. Batch membership, workspace artifacts, and notification sequencing are described in the operations guide.

Output, Errors, And Quiet Mode

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.

Inspection commands always write their requested JSON value to stdout and do not accept --quiet.

Generate Summary

A generate summary always identifies the command, report, run, generation time, valid period, and status:

{
  "command": "generate",
  "reportId": "today",
  "reportName": "Today Report",
  "promptId": "weather.today_generated_text",
  "runId": "20260529T120000.000000000Z_today",
  "status": "succeeded",
  "generatedAt": "2026-05-29T12:00:00Z",
  "validPeriod": {
    "start": "2026-05-29T00:00:00-05:00",
    "end": "2026-05-30T00:00:00-05:00"
  }
}

When available, the summary also includes reportPath, metadataPath, dataPackagePath, preparationPath, executionPath, generatedTextRawPath, generatedTextPath, renderContextPath, and llmDebugPath. outputPath is included only when --out wrote an extra copy. Distributor notification, when attempted, adds notificationPath and may add a compact notification object.

Run Summary And Stderr

A run summary contains command, batch, status, startedAt, finishedAt, total, succeeded, failed, and a reports array. It may also contain a top-level 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="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 an extra Markdown report copy.
--llm-debug-dir PATH	every generate command	Write requested sensitive prompt diagnostics outside the managed workspace. The path must be absolute.
--out-dir PATH	run morning, run evening	Write extra Markdown report copies in PATH.
--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.
--limit N	inspect reports	Maximum runs to list. Defaults to 20; 0 means no limit.

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 --out ./daily.md
weatherreporter generate today --date 2026-05-29 --out ./today.md
weatherreporter generate hourly --out ./hourly.md
weatherreporter generate today --llm-debug-dir /var/tmp/weatherreporter-debug
weatherreporter run morning --out-dir ./reports

Inspection Commands

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

Command	JSON returned
inspect reports	Recent generated runs, including artifact paths and source-warning counts.
inspect metadata RUN_ID	Persisted metadata for the run.
inspect modules RUN_ID	The run's persisted ordered module snapshot.
inspect data-package RUN_ID	The run's persisted prompt data package.
inspect prior RUN_ID	Prior comparable snapshot metadata, or null when none exists.
inspect sources RUN_ID	Source provenance and source warnings without full weather payloads.

Inspection is read-only: it does not collect weather data or invoke scriptorium. See the operations guide for artifact lifecycle and recovery.