weathr

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

Night

Contents

• Installation
• Packaging Status
• Configuration
• Usage
• Privacy
• Roadmap
• License

Packaging Status

Installation

Quick Install (macOS, Linux, FreeBSD)

Download and install the latest binary with one command:

curl -fsSL https://raw.githubusercontent.com/Veirt/weathr/main/install.sh | sh

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 .

Docker

Run the published image from GHCR:

docker run --rm -it ghcr.io/veirt/weathr:latest

Mount your config if you want to use your existing settings:

docker run --rm -it \
  -v "$HOME/.config/weathr:/.config/weathr:ro" \
  ghcr.io/veirt/weathr:latest

Build the image locally:

docker build -t weathr .

Run it interactively so the TUI can access your terminal:

docker run --rm -it weathr

Mount your config if you want to use your existing settings:

docker run --rm -it \
  -v "$HOME/.config/weathr:/.config/weathr:ro" \
  weathr

Homebrew (macOS)

brew install Veirt/veirt/weathr

MacPorts (macOS)

sudo port install weathr

Arch Linux

Available in AUR:

yay -S weathr

or

yay -S weathr-bin

Nix flake (NixOS)

Available as a flake:

inputs = {
    weathr.url = "github:Veirt/weathr";
};

Add to packages:

environment.systemPackages = [
    inputs.weathr.packages.${system}.default
];

or use home-manager module option:

imports = [
    inputs.weathr.homeModules.weathr
];

programs.weathr = {
    enable = true;
    settings = {
        hide_hud = true;
    };
};

Windows

Available through Winget:

winget install -i Veirt.weathr

Configuration

The config file location depends on your platform:

• Linux: ~/.config/weathr/config.toml (or $XDG_CONFIG_HOME/weathr/config.toml)
• macOS: ~/Library/Application Support/weathr/config.toml
• Windows: ~/AppData/Roaming/weathr/config.toml

Setup

# Linux
mkdir -p ~/.config/weathr

# macOS
mkdir -p ~/Library/Application\ Support/weathr

# Windows (PowerShell)
New-Item -Path $env:APPDATA/weathr -Type Directory

# Windows (Command Prompt)
mkdir %APPDATA%/weathr

Edit the config file at the appropriate path for your platform:

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

# Run silently without startup messages (errors still shown)
silent = false

[location]
# Location coordinates (overridden if auto = true)
latitude = 52.5200
longitude = 13.4050

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

# Hide the location name in the UI
hide = false

# How to display the location in the HUD: "coordinates" | "city" | "mixed"
display = "mixed"

# Optional: manually override the city name shown in the HUD.
# When set, skips reverse geocoding entirely.
# city = "Berlin"

# Language for the resolved city name. "auto" uses the locale of the coordinates.
# Accepts BCP-47 language tags: "en", "de", "ru", "ja", etc.
# city_name_language = "auto"

[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"

Location Display Modes

The display option controls how the location appears in the HUD. City names are resolved via reverse geocoding (Nominatim/OpenStreetMap). When a city cannot be resolved (e.g. open sea or no Nominatim match), all modes fall back to showing coordinates.

Mode	City resolved	City not resolved
coordinates	Location: 52.52°N, 13.41°E	Location: 52.52°N, 13.41°E
city	Location: Berlin	Location: 52.52°N, 13.41°E
mixed	Location: Berlin (52.52°N, 13.41°E)	Location: 52.52°N, 13.41°E

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

# Run silently (suppress non-error output)
weathr --silent

# 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.
• 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.

Geocoding

City name resolution powered by Nominatim (OpenStreetMap). Data © OpenStreetMap contributors, licensed under ODbL.

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.