theheavenlyd3mon tempest-cli — Hyper-Local Weather from Your Tempest Station
Query live weather data from a WeatherFlow Tempest station. Supports REST API access to current conditions, forecasts, and history via the cloud, plus local UDP broadcast reception from your hub on the same LAN.
Setup
- Get a personal access token at weatherflow.com (Account → API Tokens)
- Set it in your environment:
export TEMPEST_TOKEN="your-token-here"
The CLI reads TEMPEST_TOKEN from the environment. It also falls back to reading ~/.tempest.env if the env var is not set (for agent subprocesses that don't inherit env vars). --help and --dry-run work without a token.
Essential Commands
current — Current conditions
tempest-cli current # human-readable
tempest-cli current --station-id 12345 --device-id 67890 # specific hardware
tempest-cli current --json # machine-readable
If you have one station, it auto-selects it and picks the best sensor (ST > SKY > AIR, skips the HB hub). Pass --station-id or --device-id to override.
forecast — Multi-day forecast (+ current conditions + hourly)
tempest-cli forecast # current + 5-day daily + 12-hour hourly
tempest-cli forecast --days 3 # fewer days
tempest-cli forecast --station-id 12345 # specific station
tempest-cli forecast --json # machine-readable
stations — List your stations and devices
tempest-cli stations # shows station names, IDs, device types, serials
tempest-cli stations --json # full device inventory
Use this first if you don't know your station ID or want to see what sensors are online.
obs — Historical observations
tempest-cli obs --device-id 67890 --days 1 # last 24 hours
tempest-cli obs --device-id 67890 --days 7 # last week
tempest-cli obs --device-id 67890 --json # machine-readable
udp listen — Real-time broadcasts from the hub
tempest-cli udp listen # listen indefinitely (Ctrl-C to stop)
tempest-cli udp listen --timeout 30 # auto-stop after 30s
tempest-cli udp listen --show-all # include hub_status messages
Requires being on the same LAN as the hub (port 50222 UDP broadcast). Receives observations, rapid wind updates, lightning strike events, and precipitation start events in real time.
Data Reference
obs_st field layout (Tempest all-in-one)
Observations from the Tempest sensor arrive as positional arrays. The CLI decodes them, but if you're reading raw JSON output, this map tells you what each index means:
| Index | Field | Units | Notes |
|---|---|---|---|
| 0 | epoch | seconds UTC | |
| 1 | wind_lull | m/s | Minimum 3-second sample |
| 2 | wind_avg | m/s | Average over report interval |
| 3 | wind_gust | m/s | Maximum 3-second sample |
| 4 | wind_direction | degrees | 0=N |
| 5 | wind_sample_interval | seconds | |
| 6 | station_pressure | MB | |
| 7 | air_temperature | C | CLI converts to °F |
| 8 | relative_humidity | % | |
| 9 | illuminance | lux | |
| 10 | uv | index | |
| 11 | solar_radiation | W/m² | |
| 12 | rain_accumulation | mm | Over last interval |
| 13 | precipitation_type | enum | 0=none 1=rain 2=hail |
| 14 | avg_strike_distance | km | Lightning |
| 15 | strike_count | count | Lightning |
| 16 | battery | volts | ~2.6V normal, ~2.5V low |
| 17 | report_interval | minutes | |
| 18 | local_day_rain_accumulation | mm |
See references/tempest-api-field-layouts.md for the full obs_air and obs_sky field layouts.
Unit conversions the CLI applies
| Input | Output | Conversion |
|---|---|---|
| °C | °F | c * 9/5 + 32 |
| m/s | mph | mps * 2.237 |
| MB | inHg | mb * 0.02953 |
| mm | in | mm / 25.4 |
| degrees | cardinal | N, NNE, NE, ..., NNW |
Known Gotchas
The API is metric-native
All raw observation data comes in metric (Celsius, m/s, MB, mm). The CLI converts for human display. If you're parsing raw --json output, expect metric values. The better_forecast endpoint returns unit-converted values based on station preferences — check the units key in the response — but temperatures are always in Celsius regardless.
Timestamps are epoch integers, not strings
The API returns Unix epoch timestamps, not ISO 8601 strings. The daily[].day_start_local field is an int, not "2026-05-10T00:00:00". Hourly objects have local_hour (int 0-23) and local_day (int) — there is no local_time or time_string field. The CLI handles this, but raw JSON consumers need to convert with datetime.fromtimestamp(ts).
Nested forecast response
The better_forecast endpoint nests daily and hourly arrays under a forecast wrapper key, not at the top level:
# Correct path:
fc = data.get("forecast", {})
days = fc.get("daily", [])
hours = fc.get("hourly", [])
The top-level keys are: current_conditions (dict), forecast (dict with daily + hourly), station (metadata), units, status, timezone.
Device type filtering
A station returns all devices including the hub (device_type HB). The hub cannot serve observations. The CLI auto-filters HB devices and prefers ST > SKY > AIR. If you're bypassing the CLI and calling the API directly, always filter out device_type HB before querying observation endpoints.
Global flags in any position
--json, --dry-run, --quiet, and --verbose work anywhere in the command:
tempest-cli --json current --device-id 67890 # flag before subcommand
tempest-cli current --device-id 67890 --json # flag after subcommand
References
- references/tempest-api-field-layouts.md — Full field index maps for obs_st, obs_air, and obs_sky observation arrays. Read when decoding raw JSON output or building on top of the Tempest API.
- scripts/tempest-cli — The CLI binary itself. Designed following the cli-builder patterns: non-interactive,
--json,--dry-run,--quiet,--verbose, idempotent, dual-output viaemit(), and structured logging.