174 lines
9.6 KiB
Markdown
174 lines
9.6 KiB
Markdown
# Weatherreporter CLI
|
|
|
|
`weatherreporter` generates Markdown weather reports, runs report batches, and
|
|
compares explicitly selected Promptkit profiles against one prepared report. It
|
|
has no command for inspecting prior runs or application-owned state.
|
|
|
|
## Shortest Useful Command
|
|
|
|
```sh
|
|
weatherreporter generate today
|
|
```
|
|
|
|
The command uses the configured Weather API and atomically writes `today.md`.
|
|
With no configured output directory, it writes in the current directory. See
|
|
the [configuration reference](config.md) to supply the required Weather API
|
|
endpoint and choose an ordinary output directory.
|
|
|
|
## Commands And Usage
|
|
|
|
```text
|
|
weatherreporter --help
|
|
weatherreporter --version
|
|
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 compare REPORT --profile PROFILE --profile PROFILE [--config PATH] [--units VALUE] [--tz NAME] [--date YYYY-MM-DD] [--out-dir PATH] [--replace] [--llm-debug-dir PATH] [--quiet]
|
|
```
|
|
|
|
`weatherreporter --version` prints the version embedded in the executable.
|
|
Tagged release binaries report their semantic version tag; ordinary local
|
|
builds report `development`.
|
|
|
|
| Command | Contract |
|
|
| --- | --- |
|
|
| `generate daily` | Requires `--date YYYY-MM-DD`; the date is interpreted in the effective report timezone. Its default filename is `daily-YYYY-MM-DD.md`. |
|
|
| `generate today` | Accepts an optional `--date YYYY-MM-DD`; without it, the current local date in the effective report timezone is used. Its default filename is `today.md`. |
|
|
| `generate tomorrow` | Uses the next local civil day and writes `tomorrow.md` by default. |
|
|
| `generate hourly` | Covers the next six hours in the effective report timezone and writes `hourly.md` by default. It does not accept `--date`, `--hours`, or `--duration`. |
|
|
| `run morning` and `run evening` | Run their defined report batches beneath the configured output directory, or the current directory when none is configured. `--out-dir` selects another directory. `--out` is not accepted. |
|
|
| `compare REPORT` | Accepts `daily`, `today`, `tomorrow`, or `hourly`. It requires at least two distinct, nonblank `--profile` values in their supplied order. Daily requires `--date`; Today accepts it optionally; Tomorrow and Hourly do not accept it. |
|
|
|
|
`generate` accepts the four report command names shown above. `run` accepts
|
|
only `morning` and `evening`. `compare` always requires explicit profile
|
|
selection: `promptkit.profile` is not used as a comparison default. Batch
|
|
membership and notification ordering are described in the
|
|
[operations guide](operations.md).
|
|
|
|
## Output, Errors, And Quiet Mode
|
|
|
|
For `generate`, the report's default filename is placed beneath
|
|
`output.directory` when configured, otherwise the current directory. `--out
|
|
PATH` selects one complete output file instead. A relative path is resolved
|
|
from the current directory; an absolute path is used as given. For a batch,
|
|
the configured directory has the same role and `--out-dir PATH` selects its
|
|
output directory instead. For `compare`, `--out-dir PATH` selects one exact
|
|
bundle directory; otherwise the report-derived comparison directory is placed
|
|
beneath the configured directory or current directory. `--replace` is required
|
|
to replace an existing nonempty recognized comparison bundle. See the
|
|
[configuration reference](config.md) for the field's validation and path rules
|
|
and the [comparison bundle contract](integrations/comparison-bundle.md) for the
|
|
bundle format.
|
|
|
|
Outputs are written atomically. A generation, rendering, write, or cancellation
|
|
failure before publication leaves an existing destination unchanged. A
|
|
notification failure occurs after publication, so the newly written output
|
|
remains available.
|
|
|
|
Action commands (`generate`, `run`, and `compare`) 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.
|
|
|
|
### Generate Summary
|
|
|
|
A generate summary identifies the command, report, run, generation time, valid
|
|
period, prompt version, timezone, and status. Successful output has an absolute
|
|
`outputPath`:
|
|
|
|
```json
|
|
{
|
|
"command": "generate",
|
|
"reportId": "today",
|
|
"promptId": "weather.today_generated_text",
|
|
"promptVersion": "2.0.0",
|
|
"runId": "20260529T120000.000000000Z_today",
|
|
"status": "succeeded",
|
|
"timezone": "America/Chicago",
|
|
"outputPath": "/srv/weather/today.md"
|
|
}
|
|
```
|
|
|
|
When available, the summary also includes the effective `profileId`,
|
|
`backendId`, `modelName`, `sourceWarnings`, `validationStatus`, requested
|
|
`llmDebugPath`, and compact Distributor `notification` result. It does not
|
|
include historical or transient artifact paths such as metadata, prompt input,
|
|
raw generated text, render context, or notification receipts.
|
|
|
|
### Run Summary And Stderr
|
|
|
|
A run summary contains `command`, `batch`, `status`, `startedAt`, `finishedAt`,
|
|
`total`, `succeeded`, `failed`, and a `reports` array. Each report item includes
|
|
its identity, status, effective profile and model details when available,
|
|
source warnings, validation status, and absolute `outputPath` after publication.
|
|
The top-level summary may also contain a batch `notification` object and
|
|
`error`. Batch status is `failed` if any report or the batch notification fails.
|
|
The `total`, `succeeded`, and `failed` counters describe report items only, so
|
|
a failed batch notification can leave `failed` at `0` while the top-level
|
|
notification and action status are `failed`.
|
|
|
|
Without `--quiet`, batch status lines use this form:
|
|
|
|
```text
|
|
report=today status=succeeded output="/srv/weather/reports/today.md"
|
|
batch=morning total=2 succeeded=2 failed=0
|
|
```
|
|
|
|
### Compare Summary
|
|
|
|
A comparison summary contains these fields in this order: `command`,
|
|
`comparisonId`, `reportId`, `reportName`, `promptId`, `promptVersion`,
|
|
`promptHash`, `status`, `startedAt`, `finishedAt`, `timezone`, `validPeriod`,
|
|
`outputDirectory`, `manifestPath`, `dataPackagePath`, `total`, `succeeded`,
|
|
`failed`, `results`, and optional `error`. Published artifact paths and each
|
|
successful `results[].reportPath` are absolute. `results` preserves the
|
|
supplied profile order and each item contains `position`, `profileId`, optional
|
|
`backendId`, `modelName`, `status`, optional `validationStatus`, optional
|
|
`reportPath`, optional `llmDebugPath`, and optional safe `error`.
|
|
|
|
The comparison status is `succeeded` only when every selected profile succeeds
|
|
and the bundle is published. Individual profile failures still publish a
|
|
complete partial bundle and return a failed command result. Cancellation or a
|
|
failure before publication omits the artifact paths and returns a safe
|
|
top-level error; it does not expose provider diagnostics. See the
|
|
[comparison bundle contract](integrations/comparison-bundle.md) for durable
|
|
artifact fields and failure invariants.
|
|
|
|
## 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`, `compare` | Override `weather_api.units` for this command. |
|
|
| `--tz NAME` | `generate`, `run`, `compare` | Override `weather_api.timezone` for this command. |
|
|
| `--out PATH` | every `generate` command | Write the report to this complete file destination instead of the configured or current-directory default. |
|
|
| `--llm-debug-dir PATH` | every `generate`, `run`, and `compare` command | Write requested sensitive prompt diagnostics under this absolute path. |
|
|
| `--profile PROFILE` | `compare` | Select one explicit profile. Repeat at least twice with distinct, nonblank IDs. |
|
|
| `--out-dir PATH` | `run morning`, `run evening`, `compare` | Write batch reports beneath this directory, or select the exact comparison directory. |
|
|
| `--replace` | `compare` | Authorize replacement of a recognized nonempty comparison bundle. |
|
|
| `--quiet` | `generate`, `run`, `compare` | Suppress successful action output and routine batch status output. |
|
|
| `--date YYYY-MM-DD` | `generate daily`, `generate today`, `compare daily`, `compare today` | Required for Daily; optional for Today. |
|
|
|
|
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
|
|
weatherreporter generate today --out ./reports/today.md
|
|
weatherreporter generate hourly --out /srv/weather/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
|
|
weatherreporter compare daily --date 2026-05-29 --profile weather-light --profile weather-balanced --out-dir ./comparison-daily-2026-05-29
|
|
```
|