weathr 1.2.1

A terminal-based ASCII weather application with animated scenes driven by real-time weather data
Documentation

weathr

Crates.io Downloads License

A terminal weather app with ASCII animations driven by real-time weather data.

Features real-time weather from Open-Meteo with animated rain, snow, thunderstorms, flying airplanes, day/night cycles, and auto-location detection.

Demo

Thunderstorm Night Snow

Contents

Installation

Via Cargo

cargo install weathr

Build from Source

You need Rust installed.

git clone https://github.com/veirt/weathr.git
cd weathr
cargo install --path .

Configuration

The config file is at ~/.config/weathr/config.toml.

Setup

mkdir -p ~/.config/weathr

Edit ~/.config/weathr/config.toml:

# Hide the HUD (Heads Up Display) with weather details
hide_hud = false

[location]
# Location coordinates (overridden if auto = true)
latitude = 40.7128
longitude = -74.0060

# Auto-detect location via IP (defaults to true if config missing)
auto = false

# Hide the location name in the UI
hide = false

[units]
# Temperature unit: "celsius" or "fahrenheit"
temperature = "celsius"

# Wind speed unit: "kmh", "ms", "mph", or "kn"
wind_speed = "kmh"

# Precipitation unit: "mm" or "inch"
precipitation = "mm"

Example Locations

# Tokyo, Japan
latitude = 35.6762
longitude = 139.6503

# Sydney, Australia
latitude = -33.8688
longitude = 151.2093

Usage

Run with real-time weather:

weathr

CLI Options

Simulate weather conditions for testing:

# Simulate rain
weathr --simulate rain

# Simulate snow at night
weathr --simulate snow --night

# Clear day with falling leaves
weathr --simulate clear --leaves

Available weather conditions:

  • Clear Skies: clear, partly-cloudy, cloudy, overcast
  • Precipitation: fog, drizzle, rain, freezing-rain, rain-showers
  • Snow: snow, snow-grains, snow-showers
  • Storms: thunderstorm, thunderstorm-hail

Override configuration:

# Use imperial units (°F, mph, inch)
weathr --imperial

# Use metric units (°C, km/h, mm) - default
weathr --metric

# Auto-detect location via IP
weathr --auto-location

# Hide location coordinates
weathr --hide-location

# Hide status HUD
weathr --hide-hud

# Combine flags
weathr --imperial --auto-location

Keyboard Controls

  • q or Q - Quit
  • Ctrl+C - Exit

Environment Variables

The application respects several environment variables:

  • NO_COLOR - When set, disables all color output (accessibility feature)
  • COLORTERM - Detects truecolor support (values: "truecolor", "24bit")
  • TERM - Used for terminal capability detection (e.g., "xterm-256color")

Examples:

# Disable colors for accessibility
NO_COLOR=1 weathr

Privacy

Location Detection

When using auto = true in config or the --auto-location flag, the application makes a request to ipinfo.io to detect your approximate location based on your IP address.

This is optional. You can disable auto-location and manually specify coordinates in your config file to avoid external API calls.

Roadmap

  • Support for OpenWeatherMap, WeatherAPI, etc.
  • Pre-built binaries for ARM64 arch.
  • Installation via AUR.
  • Key bindings for manual refresh, speed up animations, pause animations, and toggle HUD.

License

GPL-3.0-or-later

Credits

Weather Data

Weather data provided by Open-Meteo.com under the CC BY 4.0 license.

ASCII Art

  • Source: https://www.asciiart.eu/
  • House: Joan G. Stark
  • Airplane: Joan G. Stark
  • Sun: Hayley Jane Wakenshaw (Flump)
  • Moon: Joan G. Stark

Note: If any ASCII art is uncredited or misattributed, it belongs to the original owner.