fishin 0.2.1

Terminal solunar, tide, and weather forecast for the fishing / hunting day-planner crowd

fishin

Terminal solunar, tide, and weather forecast — one command, full picture, btop-dense layout.

fishin rolls a solunar app, a tide app (xtides-style), and wttr.in into a single terminal panel. Solunar major/minor periods, sun/moon ephemera, NOAA tide predictions, open-meteo weather, and a per-day "best fishing window" cross-correlation all rendered in ~12 terminal lines per day.

Install

From PyPI (once published):

pipx install fishin

From a git checkout or this repo directly:

pipx install git+https://github.com/sjwasko/fishin.git

First run downloads the JPL DE421 ephemeris (~17 MB) into ~/.cache/fishin/ephemeris/. NOAA + open-meteo + Nominatim responses are cached at ~/.cache/fishin/responses/.

Requires Python ≥ 3.11.

Quick start

fishin                          # full panel for today, default location
fishin --city "sarasota fl"     # geocode and resolve nearest tide station
fishin --city "..." --save      # write resolved location to ~/.config/fishin/config.toml
fishin 7                        # compact 7-day list view
fishin month                    # 30-day calendar grid with star ratings
fishin best 14                  # next 14 days ranked, top 5 highlighted

Modes

Command	Output
fishin	One full panel for today
fishin N	N-day list view, one row per day
fishin month	Calendar grid for the month of --date
fishin best N	Next N days sorted by score, top 5 highlighted
fishin --days N	Legacy: render N full panels back-to-back

Skip network fetches with --no-tides / --no-weather (e.g. offline or for quick recompute).

Configuration

~/.config/fishin/config.toml:

location = "Sarasota, FL"
lat = 27.3366
lon = -82.5313
tz = "America/New_York"
station = "8726083"

Resolution order: explicit flags > --city > config file > built-in Sarasota default.

Inland queries (>100 km from the nearest NOAA tide station) automatically drop the tide section — there are no ocean tides in Austin.

How the "Best" ranking works

Every major/minor period is scored:

Factor	Weight
Major period base	+4
Minor period base	+2
Sunrise overlap (±1 hr)	+3
Sunset overlap (±1 hr)	+3
Each H/L tide overlap (±30 min)	+2
Calm wind (≤6 mph)	+1
Strong wind (≥18 mph)	−1
Rain ≥60%	−2

Top two windows are shown — first in bright amber, second dimmed.

Credits & data sources

fishin would not exist without the following free / open projects and public-data services. Please respect each provider's terms when running this tool at scale.

Runtime APIs

Source	Data	License / TOS
NOAA CO-OPS	Tide predictions	US Government public domain
open-meteo	Weather forecasts	CC BY 4.0
OpenStreetMap Nominatim	Geocoding	ODbL · usage policy
NASA JPL DE421	Planetary ephemeris	Public domain

The OSM Nominatim usage policy specifically asks clients to send a meaningful User-Agent and cache responses; both are honored — geocode results are cached on disk for 30 days.

Python dependencies

Package	Role	License
skyfield	Astronomy / ephemeris	MIT
rich	Terminal rendering	MIT
diskcache	Response cache	Apache 2.0
timezonefinder	Lat/lon → IANA timezone	MIT

Design inspiration

The visual language and information density of fishin borrow shamelessly from:

• wttr.in — terminal weather, the gold standard for "feels native to the shell"
• btop — pack-every-pixel monitoring panels
• xtides — tide curve visualization and harmonic predictions
• F&H Solunar Time — daily forecast layout, day-rating ring, calendar grid

None of these projects are affiliated with fishin; we just learned from them.

License

MIT. Fork, improve, redistribute — just keep the copyright notice.

Architecture

See ARCHITECTURE.md for the module layout, data flow, and extension points if you'd like to contribute.