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

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

Contents

• Installation
• Configuration
• Usage
• Privacy
• Roadmap
• License

Installation

Via Cargo

Build from Source

You need Rust installed.

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

Arch Linux

Available in AUR:

or

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;
    };
};

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

You can also place a config.toml in the current working directory, which takes priority over the default location.

Setup

# Linux
mkdir -p ~/.config/weathr

# macOS
mkdir -p ~/Library/Application\ Support/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 = 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:

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.

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.