rdrop 0.1.0

A beautiful, feature-rich weather CLI for your terminal

Raindrop

A beautiful, feature-rich weather CLI for your terminal.
Sparklines, route planning, live dashboards, marine forecasts, and more — all without an API key.

---

Why Raindrop?

Most weather CLIs give you temperature and a condition. Raindrop gives you everything:

• Sparkline graphs — ▁▂▃▅▇█▅▃ temperature and precipitation trends at a glance
• Technical analysis — EMA crossovers, rate-of-change, and volatility on forecasts
• Real driving routes — weather checkpoints along actual roads via OpenStreetMap
• Full-screen dashboard — live TUI with auto-refresh
• Astronomical data — moon phases, golden hour, blue hour, daylight tracking
• Marine forecasts — wave height, swell, water temp for coastal trips
• Zero API keys — entirely free, open APIs

---

Installation

Requirements: Python 3.12+

# pip
pip install rdrop

# From source
git clone https://github.com/binarydoubling/raindrop.git
cd raindrop
pip install -e .

---

Quick Start

raindrop current Seattle                          # current conditions
raindrop hourly "New York" --spark --hours 12     # sparkline forecast
raindrop daily Portland                           # 10-day with trend analysis
raindrop dashboard Seattle --refresh 300          # live full-screen TUI
raindrop route "Seattle" "San Francisco" -i 100   # road trip weather
raindrop aqi Beijing                              # air quality index
raindrop favorites add home "Seattle, WA"         # save a location
raindrop current home                             # use it anywhere

---

Features

Current Weather

Hourly Forecast with Sparklines

10-Day Forecast with Technical Analysis

EMA crossovers, rate-of-change indicators, and trend detection applied to weather data.

Route Weather Planning

Plan road trips with weather at every checkpoint along the actual driving route.

Compare Multiple Locations

Air Quality Index

Astronomical Data

Moon phases, golden hour, blue hour, and weekly daylight tracking.

Marine Forecasts

Clothing Recommendations

Live Dashboard

Full-screen TUI powered by Rich with automatic refresh.

raindrop dashboard Seattle --refresh 300

---

Commands

Command	Description	Example
current	Current conditions	raindrop current Seattle
hourly	Hourly forecast (48h)	raindrop hourly Seattle --spark
daily	10-day forecast with trends	raindrop daily Seattle
dashboard	Full-screen live TUI	raindrop dashboard Seattle
route	Weather along a driving route	raindrop route "A" "B" -i 50
compare	Compare multiple locations	raindrop compare NYC LA Chicago
alerts	NWS weather alerts (US)	raindrop alerts Seattle
aqi	Air quality index	raindrop aqi Seattle
astro	Moon phase, golden hour	raindrop astro Seattle
marine	Ocean/wave forecasts	raindrop marine "San Diego"
clothing	What to wear	raindrop clothing Seattle
history	Compare with past years	raindrop history Seattle
discussion	NWS forecast discussion	raindrop discussion Seattle
precip	Precipitation totals	raindrop precip Seattle --days 7
favorites	Manage saved locations	raindrop favorites list
config	View/edit settings	raindrop config show
completions	Shell completions	raindrop completions bash

Global Options

--units metric|imperial    Set temperature and distance units (default: imperial)
--no-cache                 Bypass cache for fresh data
--json                     Output raw JSON for scripting
--help                     Show help for any command

---

Configuration

Settings live at ~/.config/raindrop/config.json.

raindrop config show                  # view current settings
raindrop config set units metric      # switch to metric
raindrop config set location "NYC"    # set default location
raindrop config cache                 # view cache stats
raindrop config cache --clear         # clear cache

Setting	Values	Default	Description
units	imperial, metric	imperial	Temperature and distance units
location	any string	none	Default location
cache_ttl	seconds	600	Cache lifetime

---

Shell Completions

# Bash
raindrop completions bash >> ~/.bashrc && source ~/.bashrc

# Zsh
raindrop completions zsh >> ~/.zshrc && source ~/.zshrc

# Fish
raindrop completions fish > ~/.config/fish/completions/raindrop.fish

---

How It Works

Raindrop combines several free, open APIs — no keys required:

API	Purpose
Open-Meteo	Forecasts, historical data, air quality, geocoding
OSRM	Real driving routes via OpenStreetMap
NWS	Weather alerts and forecast discussions (US)

The entire project has only 2 runtime dependencies (Click and Rich). HTTP, caching, geocoding, and astronomical calculations are all handled with Python's standard library.

Technical Highlights

• Sparklines via Unicode block characters (▁▂▃▄▅▆▇█)
• EMA crossovers and rate-of-change analysis on temperature data
• Pure-Python astronomy — moon phases, Julian day, daylight duration with no external libs
• Haversine sampling along OSRM polylines for route weather checkpoints
• File-based cache with SHA256 keys and configurable TTL
• 14 weather models selectable: ECMWF, GFS, HRRR, ICON, ARPEGE, AROME, UKMO, GEM, JMA, MetNo, and more

---

Regenerating Screenshots

The feature screenshots in this README are real CLI output captured as SVGs:

python scripts/capture.py            # capture all commands
python scripts/capture.py current    # capture a specific command

---

Contributing

git clone https://github.com/binarydoubling/raindrop.git
cd raindrop
pip install -e ".[dev]"
pytest

---

License

MIT

---

_{Built with coffee and curiosity in the Pacific Northwest — where checking the weather is a lifestyle.}