weather/README.md

weather

Small CLI for waybar-style weather output using free APIs:

• Location search: OpenStreetMap Nominatim
• Forecast: NWS points → forecastHourly
• Output: single line with NerdFont icon

Usage

# Set location by search (uses fzf if multiple matches)
go run . -s "Somerville, MA"
go run . --search "Somerville, MA"

# Subsequent runs use cached location
go run .

# Include short forecast description
go run . -d
go run . --desc

# Enable NerdFont icons
go run . -p
go run . --pretty

# Use Celsius
go run . -u C
go run . --units C

# Force forecast refresh (bypass cache)
go run . -r
go run . --refresh

# Clear cached location and forecast
go run . -c
go run . --clear-cache

# Show all icons used by the app
go run . -i
go run . --icon-test

# Display radar loop for the current location (requires mpv)
go run . -R
go run . --radar

# Interactive search (requires rofi)
go run . -S
go run . --interactive-search

Radar mode caches the GIF on disk (10 minute TTL) under the cache directory.

Note: go run main.go only compiles that file. Use go run . to include the whole package.

Output format (default, text only):

<CONDITION> <TEMP>°F <POP%> in <CITY, ST>

If -d is set, a title-cased short forecast description is prepended.

Output format (with --pretty):

<COND_GLYPH> <TEMP>°F <POP_GLYPH> <POP%> in <CITY, ST>

Caching

• Location is cached forever until you run with -s again.
• Forecast is cached for 10 minutes to avoid API hammering.
• Use --clear-cache to remove both caches.
• Use --refresh to bypass the forecast cache for one run.

Cache location is stored in:

• $WEATHER_CACHE_DIR if set
• Otherwise $XDG_CACHE_HOME/weather
• Otherwise ~/.cache/weather

Notes

• If Nominatim returns multiple matches, fzf is required for selection.
• If fzf is not installed and multiple matches are returned, the command exits with an error.
• User-Agent is automatically generated and includes hostname + repo/contact.

Waybar example

"custom/weather": {
  "exec": "weather -p",
  "interval": 60
}