weather ⛅

A fast, beautiful terminal weather client with multi-provider fallbacks, AQI metrics, and smart caching.

Install

# With uv (recommended)
uv tool install weathr

# With pipx
pipx install weathr

First-Run Onboarding

On your first launch (or at any time by running weather setup), weather launches an interactive onboarding flow. It detects your location using IP geolocation, asks to confirm your preferred city, and lets you pick your default unit system.

Your preferences are saved locally (config.toml). After setup, simply running weather displays your local forecast instantly.

Usage

# Check current weather + 6-day forecast for your saved location
weather

# Check weather for any city, landmark, address or postal codes
weather -l Tokyo
weather -l "Berlin, Germany"
weather -l 94103

# Specify total days of forecast (1 to 16 days)
weather -d 3
weather -l London -d 10

# Override unit system
weather --metric     # °C, km/h, mm
weather --imperial   # °F, mph, in

# Bypass cache and fetch fresh data
weather --refresh
weather -l "Paris" -r

# Output JSON for scripting
weather --json
weather -l "Reykjavik" --json | jq .weather.current.temperature

# Verbose logging
weather -l "Berlin" -v

CLI Options & Subcommands

Options

Default File Paths

Cache Management

weather maintains a fast binary msgpack cache to eliminate redundant network calls:

# View cache file location
weather cache path

# View cache size, entries and status
weather cache stats

# Remove expired entries (>1 week old)
weather cache prune

# Wipe the cache entirely
weather cache clear

Configuration Management

# Run interactive setup at any time
weather setup

# Display config file path
weather config path

# View current configuration
weather config show

# Update configuration preferences
weather config set --location "Paris" --units imperial

# Reset configuration to defaults
weather config reset

Config file example (config.toml):

unit_system = "metric"
theme = "default"

[location]
latitude = 37.774929
longitude = -122.419416
display_name = "San Francisco, California, United States"

Optional: OpenWeather API Key

weather works out of the box with zero configuration using Open-Meteo. If you want OpenWeather as an automatic secondary fallback for Air Quality (AQI) data, obtain a free API key and set the OPENWEATHER_API_KEY environment variable:

Linux & macOS (Bash / Zsh)

echo 'export OPENWEATHER_API_KEY="your_api_key_here"' >> ~/.bashrc  # or ~/.zshrc
source ~/.bashrc  # or source ~/.zshrc

Windows (Powershell)

[System.Environment]::SetEnvironmentVariable('OPENWEATHER_API_KEY', 'your_api_key_here', 'User')

Attributions & Data Sources

This project is powered by several free and open data providers:

• Weather Forecast:

  • Open-Meteo (Weather Forecast API) under CC BY 4.0.

• Air Quality:

  • Open-Meteo (Air Quality API) under CC BY 4.0.
  • OpenWeather (Air Pollution API).

• Geocoding:

  • Nominatim (Data © OpenStreetMap contributors).
  • Open-Meteo (Geocoding API) under CC BY 4.0.

• IP Geolocation:

  • IPWhoIs
  • FreeIPAPI
  • CountryIs
  • IPInfo

License

This project is licensed under the MIT License.