Refresh CLI and configuration reference
This commit is contained in:
211
docs/cli.md
211
docs/cli.md
@@ -1,7 +1,7 @@
|
||||
# Weatherreporter CLI
|
||||
|
||||
`weatherreporter` generates Markdown weather reports, runs scheduled report
|
||||
batches, and inspects stored artifacts.
|
||||
`weatherreporter` generates weather reports, runs report batches, and inspects
|
||||
artifacts already stored in its workspace.
|
||||
|
||||
## Shortest Useful Command
|
||||
|
||||
@@ -9,14 +9,11 @@ batches, and inspects stored artifacts.
|
||||
weatherreporter generate today --out ./today.md
|
||||
```
|
||||
|
||||
This loads configuration, collects 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.
|
||||
The command uses the configured Weather API and writes an extra Markdown copy
|
||||
at `./today.md`. See the [configuration reference](config.md) to supply the
|
||||
required Weather API endpoint.
|
||||
|
||||
## Commands
|
||||
## Commands And Usage
|
||||
|
||||
```text
|
||||
weatherreporter --help
|
||||
@@ -37,57 +34,38 @@ weatherreporter inspect prior [--config PATH] RUN_ID
|
||||
weatherreporter inspect sources [--config PATH] RUN_ID
|
||||
```
|
||||
|
||||
Implemented `generate` commands emit a compact JSON summary to stdout on
|
||||
success. The summary includes command identity, report identity, RunID, status,
|
||||
valid period, and managed artifact paths. They also 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`.
|
||||
| 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`, `three-day`, `weekend` | Use their report-defined valid period and accept the common generate flags. |
|
||||
| `generate hourly` | Covers the next six hours in the effective report timezone. It does not accept `--date`, `--start`, `--end`, `--hours`, or `--duration`. |
|
||||
| `generate storm` | Requires both `--start TIME` and `--end TIME`. Each time may be `YYYY-MM-DDTHH:MM` in the effective timezone or an RFC3339 timestamp with an explicit offset. |
|
||||
| `run morning` and `run evening` | Run their defined report batches. `--out-dir` writes extra Markdown copies; `--out` is not accepted. |
|
||||
|
||||
`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 managed report paths, not the extra copies. Today and
|
||||
Tomorrow use their report default copy names, and dynamic Daily copies use
|
||||
`daily-YYYY-MM-DD.md`. When distributor and batch notification are enabled, a
|
||||
fully successful batch uploads one distributor bundle after report generation
|
||||
finishes. The JSON summary exposes that upload as a top-level `notification`
|
||||
object, and stderr includes one `batchNotification` status line. If any planned
|
||||
report fails, the batch notification is skipped for the whole batch.
|
||||
`generate` accepts all seven report command names shown above. `run` accepts
|
||||
only `morning` and `evening`. Batch membership, workspace artifacts, and
|
||||
notification sequencing are described in the [operations guide](operations.md).
|
||||
|
||||
Hourly Report, 3-Day Outlook, and Weekend Outlook are explicit only; they are
|
||||
not included in `run morning` or `run evening`.
|
||||
## Output, Errors, And Quiet Mode
|
||||
|
||||
`inspect` commands read existing workspace artifacts and emit the requested
|
||||
JSON data to stdout. They do not collect weather data or invoke `scriptorium`.
|
||||
Inspection commands do not accept `--quiet`.
|
||||
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.
|
||||
|
||||
## Output
|
||||
`--quiet` is supported by action commands only. It suppresses action summaries
|
||||
and routine batch status output; it does not suppress command errors.
|
||||
|
||||
Action commands, meaning `generate` and `run`, emit JSON summaries to stdout by
|
||||
default. Pre-run errors, such as invalid flags, missing required arguments, or
|
||||
configuration load failures, return an error without emitting partial JSON.
|
||||
`--quiet` suppresses successful action-command stdout and routine stderr. It
|
||||
does not hide returned errors. Inspection commands are data-output commands;
|
||||
they always write the requested JSON to stdout and are not quietable.
|
||||
Inspection commands always write their requested JSON value to stdout and do
|
||||
not accept `--quiet`.
|
||||
|
||||
Generate summaries have this shape:
|
||||
### Generate Summary
|
||||
|
||||
A generate summary always identifies the command, report, run, generation
|
||||
time, valid period, and status:
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -101,102 +79,60 @@ Generate summaries have this shape:
|
||||
"validPeriod": {
|
||||
"start": "2026-05-29T00:00:00-05:00",
|
||||
"end": "2026-05-30T00:00:00-05:00"
|
||||
},
|
||||
"reportPath": "workspace/reports/today/2026-05-29/report.20260529T120000.000000000Z_today.md",
|
||||
"metadataPath": "workspace/snapshots/today/2026-05-29/metadata.20260529T120000.000000000Z_today.json",
|
||||
"dataPackagePath": "workspace/data-packages/today/2026-05-29/data_package.20260529T120000.000000000Z_today.yaml",
|
||||
"preflightPath": "workspace/preflight/today/2026-05-29/render.20260529T120000.000000000Z_today.json",
|
||||
"generatedTextRawPath": "workspace/snapshots/today/2026-05-29/generated_text_raw.20260529T120000.000000000Z_today.json",
|
||||
"generatedTextResultPath": "workspace/snapshots/today/2026-05-29/generated_text_result.20260529T120000.000000000Z_today.json",
|
||||
"generatedTextPath": "workspace/snapshots/today/2026-05-29/generated_text.20260529T120000.000000000Z_today.json",
|
||||
"renderContextPath": "workspace/snapshots/today/2026-05-29/render_context.20260529T120000.000000000Z_today.json"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Markdown-path reports omit the generated-text fields. If distributor
|
||||
notification is attempted, summaries include `notificationPath`; successful
|
||||
notification also includes a compact `notification` object. If notification
|
||||
fails after report artifacts exist, the summary has `"status": "failed"` and an
|
||||
`error` string while retaining inspectable artifact paths.
|
||||
When available, the summary also includes `reportPath`, `metadataPath`,
|
||||
`dataPackagePath`, and `preflightPath`. Generated-text reports additionally
|
||||
include `generatedTextRawPath`, `generatedTextResultPath`,
|
||||
`generatedTextPath`, and `renderContextPath`. `outputPath` is included only
|
||||
when `--out` wrote an extra copy. Distributor notification, when attempted,
|
||||
adds `notificationPath` and may add a compact `notification` object.
|
||||
|
||||
Run summaries have this shape:
|
||||
### Run Summary And Stderr
|
||||
|
||||
```json
|
||||
{
|
||||
"command": "run",
|
||||
"batch": "morning",
|
||||
"status": "succeeded",
|
||||
"startedAt": "2026-05-29T12:00:00Z",
|
||||
"finishedAt": "2026-05-29T12:01:00Z",
|
||||
"total": 1,
|
||||
"succeeded": 1,
|
||||
"failed": 0,
|
||||
"reports": [
|
||||
{
|
||||
"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"
|
||||
},
|
||||
"reportPath": "workspace/reports/today/2026-05-29/report.20260529T120000.000000000Z_today.md",
|
||||
"metadataPath": "workspace/snapshots/today/2026-05-29/metadata.20260529T120000.000000000Z_today.json",
|
||||
"dataPackagePath": "workspace/data-packages/today/2026-05-29/data_package.20260529T120000.000000000Z_today.yaml",
|
||||
"preflightPath": "workspace/preflight/today/2026-05-29/render.20260529T120000.000000000Z_today.json"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
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.
|
||||
|
||||
`run` status is `failed` when any report failed or the top-level batch
|
||||
notification failed. Batch stderr uses compact status lines, for example:
|
||||
Without `--quiet`, batch status lines use this form:
|
||||
|
||||
```text
|
||||
report=today status=succeeded output="reports/today.md"
|
||||
batch=morning total=2 succeeded=2 failed=0
|
||||
```
|
||||
|
||||
## Flags
|
||||
## Flag Reference
|
||||
|
||||
- `-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`.
|
||||
- `--quiet`: suppress successful stdout and routine stderr for `generate` and `run`.
|
||||
- `--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.
|
||||
| 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. |
|
||||
| `--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. |
|
||||
| `--start TIME`, `--end TIME` | `generate storm` | Required storm-event bounds. |
|
||||
| `--limit N` | `inspect reports` | Maximum runs to list. Defaults to `20`; `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 through `notify.distributor`; there are
|
||||
no Distributor-specific CLI flags. See the [configuration reference](config.md).
|
||||
|
||||
Distributor notification is configured only through `notify.distributor`; there
|
||||
are no distributor-specific CLI flags.
|
||||
|
||||
## Common Workflows
|
||||
## Invocation Examples
|
||||
|
||||
```sh
|
||||
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 today --date 2026-05-29 --out ./today.md
|
||||
weatherreporter generate hourly --out ./hourly.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
|
||||
weatherreporter generate today --quiet
|
||||
weatherreporter run morning --quiet
|
||||
```
|
||||
|
||||
## Inspection
|
||||
## Inspection Commands
|
||||
|
||||
```sh
|
||||
weatherreporter inspect reports --limit 10
|
||||
@@ -205,12 +141,17 @@ 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.
|
||||
| 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](operations.md) for artifact lifecycle
|
||||
and recovery.
|
||||
|
||||
Reference in New Issue
Block a user