Tempest cli

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

1. Get a personal access token at weatherflow.com (Account → API Tokens)
2. 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 via emit(), and structured logging.