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
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 | shVia Cargo
cargo install weathrBuild 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:latestMount 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:latestBuild the image locally:
docker build -t weathr .Run it interactively so the TUI can access your terminal:
docker run --rm -it weathrMount your config if you want to use your existing settings:
docker run --rm -it \
-v "$HOME/.config/weathr:/.config/weathr:ro" \
weathrHomebrew (macOS)
brew install Veirt/veirt/weathrMacPorts (macOS)
sudo port install weathrArch Linux
Available in AUR:
yay -S weathror
yay -S weathr-binNix 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%/weathrEdit 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.2093Usage
Run with real-time weather:
weathrCLI 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 --leavesAvailable 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-locationKeyboard Controls
qorQ- QuitCtrl+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 weathrPrivacy
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.
