heinzel-weather

Weather where you are, keyless by default from Open-Meteo: now, the next hours and days, and a heads-up when it changes. Bring an OpenWeather key instead if you prefer it. A plugin for Heinzelmännchen.

Install it with:

hz system plugin add weather --confirm
hz setup weather    # your places and the units (and the provider; Open-Meteo needs no key); the app: Settings > Weather
# With no place set, the city of your time zone is used until you set one.

Open-Meteo needs no account and no key. Its data is licensed CC BY 4.0 and free for non-commercial use, so it is credited wherever the weather shows: in the status item's detail, on the Today list and graphic, in CLI output and structured results, and in notices. It has no severe weather alerts. Location queries are redacted from request logs; an Open-Meteo response is stopped after 2 MB instead of downloading an unbounded body.

With weather.provider = "openweather" the API key is a credential, kept in your keychain (hz system credential set weather.api-key) or read from HZ_CREDENTIAL_WEATHER_API_KEY, else OPENWEATHER_API_KEY; never from a config file. It needs OpenWeather's One Call API 3.0, free up to 1,000 calls a day once you subscribe to it at openweathermap.org; it also brings severe weather alerts.

In the web app

Contributed as data (ADR 0056), nothing to install on the app's side:

• A status item in the footer and the sidebar: the temperature and sky, with the place, feels-like, what the Heinzelmännchen wears and the attribution on hover; "Change place" opens Settings > Weather; nothing is typed into a terminal.
• Today: a graphic with the temperature beside the Heinzelmännchen dressed for the weather (an umbrella in or near rain, sunglasses in clear daylight, a scarf in the cold), and a list of the next days with the attribution.
• Notices (the daemon's weather.watch job) when rain starts within the hour, the temperature swings or, with OpenWeather, an alert is issued.

Until a place is set, the status item says "Set a location".

Use

Every command takes --json. A place is a city and country ("Lisbon, PT") or coordinates ("38.72,-9.14").

In hz ui, Weather adds a condition and temperature status item to the footer and sidebar, a detailed Today card, and a Weather entry under Settings. The status and card share one plugin observation, refreshed every 15 minutes; if a refresh fails, they keep the last observation and mark it stale. The Settings/sidebar entry opens the full forecast command.

Settings

Notices are de-duplicated: each change once, and rain at most once in three hours per place.

Try OpenWeather offline: the fake OpenWeather

python -m heinzel_weather.fake --port 8787 &
HZ_WEATHER__PROVIDER=openweather HZ_WEATHER__BASE_URL=http://127.0.0.1:8787 HZ_WEATHER__LOCATIONS='["Berlin, DE"]' OPENWEATHER_API_KEY=fake hz weather show

Fixed weather relative to the current hour: 21.5 °C and clear now, rain from the next hour, a thunderstorm warning. The tests and the docs' recordings use the same fake (heinzel_weather.fake).

Development and release commands: repository guide.

Observations and trend advice

hz weather observe --json is a read-only report for workflows; it does not send notices. The plugin also ships the weather-trend skill: hz system skill show weather-trend. Details: ADR 0002.

Screenshots

Current weather and the coming days on Today — fictional Berlin forecast

Inspect conditions, feels-like temperature and rain chance — fictional local forecast

Weather and near forecast in the phone-sized Today view — fictional local forecast

Command line

Hourly conditions and approaching rain through the real CLI — local fictional forecast

A concise three-day outlook through the real CLI — local fictional forecast

Open the screenshot gallery.