weatherreporter/docs/cli.md

# Weatherreporter CLI

`weatherreporter generate daily`, `weatherreporter generate tomorrow`,
`weatherreporter generate three-day`, `weatherreporter generate weekend`,
`weatherreporter run morning`, and `weatherreporter run evening` currently
write Markdown reports through `scriptorium`, after writing managed preparation
artifacts and running `scriptorium render` as a preflight check. Unsupported
report generation still resolves configuration, report definitions, and valid
periods, then returns a not-implemented error.

## Shortest Useful Command

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

The command parses flags, loads configuration, fetches weather data, builds a
Daily briefing, writes workspace artifacts, invokes
`scriptorium render --input data_package=<managed_path> --format json`, then
invokes `scriptorium run --input data_package=<managed_path> --out <managed_report>`.
When `--out` is supplied, it also writes a copy of the Markdown report to that
path.

For tomorrow planning:

```sh
weatherreporter generate tomorrow --out ./tomorrow.md
weatherreporter run evening
```

For the 3-Day Outlook:

```sh
weatherreporter generate three-day --out ./three-day.md
weatherreporter generate weekend --out ./weekend.md
```

## Command Overview

```text
weatherreporter generate daily
weatherreporter generate tomorrow
weatherreporter generate three-day
weatherreporter generate weekend
weatherreporter generate storm --start 2026-05-29T18:00 --end 2026-05-30T06:00
weatherreporter run morning
weatherreporter run evening
```

`generate daily`, `generate tomorrow`, `generate three-day`, and
`generate weekend` write a briefing snapshot, prompt input data package, render
preflight output, Markdown report, and metadata file under the configured
workspace. `run evening` generates the Tomorrow Planning Brief. `run morning`
generates Daily Today and the 3-Day Outlook, plus Weekend Outlook except on
Sunday. Run commands continue remaining reports after an independent report
failure, print a JSON aggregate summary to stdout, write compact report status
logs to stderr, and return nonzero when any report failed. Other `generate`
commands resolve one report request and stop before report generation.

## 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.
- `--tz NAME`: override configured Weather API timezone.
- `--out PATH`: optional Markdown report copy for `generate daily`, `generate tomorrow`, `generate three-day`, and `generate weekend`; reserved for later generated report output on other `generate` commands.
- `--out-dir PATH`: optional directory for extra Markdown report copies from `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`.

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