Align baseline user documentation
This commit is contained in:
119
docs/cli.md
119
docs/cli.md
@@ -1,11 +1,7 @@
|
||||
# Weatherreporter CLI
|
||||
|
||||
`weatherreporter generate daily`, `weatherreporter generate tomorrow`,
|
||||
`weatherreporter generate three-day`, `weatherreporter generate weekend`,
|
||||
`weatherreporter generate storm`,
|
||||
`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.
|
||||
`weatherreporter` generates Markdown weather reports, runs scheduled report
|
||||
batches, and inspects previously generated artifacts.
|
||||
|
||||
## Shortest Useful Command
|
||||
|
||||
@@ -13,82 +9,69 @@ artifacts and running `scriptorium render` as a preflight check.
|
||||
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.
|
||||
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`.
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
For a focused manual Storm Report:
|
||||
|
||||
```sh
|
||||
weatherreporter generate storm --start 2026-05-29T18:00 --end 2026-05-30T06:00 --out ./storm.md
|
||||
```
|
||||
|
||||
## Command Overview
|
||||
## Commands
|
||||
|
||||
```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
|
||||
weatherreporter inspect reports
|
||||
weatherreporter inspect metadata RUN_ID
|
||||
weatherreporter inspect briefing RUN_ID
|
||||
weatherreporter inspect data-package RUN_ID
|
||||
weatherreporter inspect prior RUN_ID
|
||||
weatherreporter inspect sources RUN_ID
|
||||
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 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 briefing [--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
|
||||
```
|
||||
|
||||
`generate daily`, `generate tomorrow`, `generate three-day`,
|
||||
`generate weekend`, and `generate storm` write a briefing snapshot, prompt
|
||||
input data package, render preflight output, Markdown report, and metadata file
|
||||
under the configured workspace. `generate storm` requires explicit `--start`
|
||||
and `--end` bounds for the event window. `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
|
||||
`generate` commands write briefing, data package, preflight, report, and
|
||||
metadata artifacts under the configured workspace. `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 Planning Brief. 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.
|
||||
|
||||
`inspect` commands read the configured workspace and emit JSON to stdout. They
|
||||
do not fetch weather data or invoke `scriptorium`.
|
||||
`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.
|
||||
- `--tz NAME`: override configured Weather API timezone.
|
||||
- `--out PATH`: optional Markdown report copy for `generate daily`, `generate tomorrow`, `generate three-day`, `generate weekend`, and `generate storm`.
|
||||
- `--out-dir PATH`: optional directory for extra Markdown report copies from `run morning` and `run evening`.
|
||||
- `--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 for `generate` commands.
|
||||
- `--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 report records for `inspect reports`; defaults to 20,
|
||||
and `0` means no limit.
|
||||
- `--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.
|
||||
|
||||
## Common Workflows
|
||||
|
||||
```sh
|
||||
weatherreporter generate tomorrow --out ./tomorrow.md
|
||||
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
|
||||
|
||||
```sh
|
||||
@@ -100,8 +83,8 @@ weatherreporter inspect prior 20260529T100000.000000000Z_daily_today
|
||||
weatherreporter inspect sources 20260529T100000.000000000Z_daily_today
|
||||
```
|
||||
|
||||
`inspect reports` lists recent generated runs with artifact paths and warning
|
||||
counts. The other commands require a RunID. `inspect prior` returns the prior
|
||||
comparable snapshot metadata selected from stored metadata, or `null` when no
|
||||
prior comparable snapshot exists. `inspect sources` shows source provenance and
|
||||
source warnings without dumping full weather payloads.
|
||||
`inspect reports` lists recent generated runs with artifact paths and source
|
||||
warning counts. The other inspect commands require a RunID. `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.
|
||||
|
||||
Reference in New Issue
Block a user