153 lines
7.1 KiB
Markdown
153 lines
7.1 KiB
Markdown
# Weatherreporter CLI
|
|
|
|
`weatherreporter` generates weather reports, runs report batches, and inspects
|
|
artifacts already stored in its workspace.
|
|
|
|
## Shortest Useful Command
|
|
|
|
```sh
|
|
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](config.md) to supply the
|
|
required Weather API endpoint.
|
|
|
|
## Commands And Usage
|
|
|
|
```text
|
|
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] [--llm-debug-dir PATH] [--quiet]
|
|
weatherreporter run evening [--config PATH] [--units VALUE] [--tz NAME] [--out-dir PATH] [--llm-debug-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](operations.md).
|
|
|
|
## 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:
|
|
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
```text
|
|
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` and `run` 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](config.md).
|
|
|
|
## Invocation Examples
|
|
|
|
```sh
|
|
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 --llm-debug-dir /var/tmp/weatherreporter-debug
|
|
```
|
|
|
|
## Inspection Commands
|
|
|
|
```sh
|
|
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 Promptkit.
|
|
See the [operations guide](operations.md) for artifact lifecycle
|
|
and recovery.
|