A collection of simple, asynchronous, and configurable prompt sections for the Tide Fish prompt. This plugin provides prompt items that display Weather, Moon Phase, Ocean Tides, and GitHub data without slowing down your shell.

• Asynchronous: Fetches data in the background to keep your prompt fast.
• Efficient: With the default weather provider (Open-Meteo), weather is fetched in the background; moon uses a separate request when needed.
• Modular: Provides independent prompt items. Use only the ones you want.
• Configurable: Easily customize formats, units, location, and refresh rates.
• Helpful: Provides succinct weather data, moon phase data, GitHub stats, or if you really want to lean into the maritime theme, tide data.

1. Install the plugin: fisher install MrBasa/TideReport@v1
2. On a fresh install, the plugin adds weather, moon, and github to your prompt automatically. The tide item is not added by default.
3. Run tide reload or open a new terminal to see the prompt.
4. If weather shows as unavailable at first, the plugin may still be detecting your location in the background; wait a moment or set weather location manually.

• curl: Required by the weather, moon, and tide modules to fetch data.
• gh: The GitHub CLI. Required by the github module. You must be authenticated (gh auth login).
• jq: Required by all modules (github, tide, weather, moon) for parsing JSON data.
• The latest version of Fish.
• Fisher plugin manager.
• A Nerd Font (optional, for icons).

Install with Fisher:

fisher install MrBasa/TideReport@v1

Or add MrBasa/TideReport@v1 to ~/.config/fish/fish_plugins and run fisher update. This is the recommended workflow when using a dotconfig manager. See the Fisher and Tide documentation for more details on installing plugins.

• github: Displays stars, forks, watchers, issues, and PRs for the current gh repo.
• weather: Displays the current weather (from Open-Meteo or wttr.in).
• moon: Displays the current moon phase (from wttr.in; when weather provider is wttr, one request fills both).
• tide: Displays the next high/low tide from NOAA (US-based).

On a fresh install, weather, moon, and github are added to your prompt for you. To add tide or change the order of items, edit the Tide prompt lists and reload:

set -Ua tide_right_prompt_items tide
tide reload

Set any of the following variables universally or add them to your config.fish to override defaults.

To keep your prompt fast, this plugin fetches data in the background and relies on cached data. This is done to prevent slow network requests from blocking your shell. Background fetch jobs are disowned so the shell does not wait for them when drawing the prompt (avoiding a 3–6 second delay on new shells when cache is empty or expired).

All file-based caches are stored in ~/.cache/tide-report/.

These modules use an asynchronous, file-based caching system with two timers:

1. Refresh (..._refresh_seconds): This is the "stale" timer. If you load your prompt and the cached data is older than this value, the prompt will show the stale data and trigger a fetch in the background. Your prompt is not blocked.
2. Expire (..._expire_seconds): This is the "invalid" timer. If the cached data is older than this value (or doesn't exist), the prompt will show the unavailable text (e.g., 🌊) and trigger a background fetch.

This means it is expected behavior to see the "unavailable" text for a few seconds when the cache is empty or has expired.

With the wttr weather provider, one API call fills both weather and moon (cache file ~/.cache/tide-report/wttr.json). With Open-Meteo (the default), weather and moon use separate requests and caches.

The github module's caching is simpler and based on Fish's universal variables (not files).

• It caches data per-repository.
• Data is fetched synchronously if:
  1. You change to a new directory that is a git repository.
  2. You are in the same repository, but the cache is older than tide_report_github_refresh_seconds.

These settings apply to all modules in this plugin.

Requires gh CLI to be installed and authenticated.

The module displays stats for the current repository, with icons you can customize.

This module requires jq for parsing JSON.

The weather format is a string with custom specifiers.

tide_report_weather_location controls where weather is fetched for. Valid values depend on the weather provider (tide_report_weather_provider). Both providers accept GPS coordinates as latitude,longitude (e.g. -78.46,106.79). No spaces.

When provider is openmeteo (default):

• Empty string "" (default): Your location is detected from your IP in the background and cached per shell session (file under ~/.cache/tide-report/). A new terminal in a new place will detect again. No need to set anything for IP-based weather.
• Place name or postal code: The value is sent to the Open-Meteo Geocoding API. Use a city name, region, or postal code (e.g. Berlin, London, 90210). At least three characters are recommended for fuzzy matching.
• GPS coordinates: Use latitude,longitude to skip geocoding.

When provider is wttr:

• Empty string "": wttr.in uses your IP address to guess your location.
• City or place name: Use a single word or hyphenated name (e.g. Paris, Saint-Petersburg, New-York). Unicode is supported. For spaces use hyphens or + (e.g. Eiffel+tower).
• 3-letter airport code: e.g. muc, lhr, jfk.
• Postal or area code: e.g. 90210, 94107.
• GPS coordinates: latitude,longitude (e.g. -78.46,106.79).
• Domain name: Prefix with @ (e.g. @stackoverflow.com) for location derived from the domain.

This module requires jq. It uses its own cache file (~/.cache/tide-report/moon.json). When the weather provider is wttr, one wttr.in request fills both weather and moon; when the provider is openmeteo (default), the moon item fetches moon data separately from wttr.in. It displays the moon phase emoji.

This module requires jq and you must set a Station ID (default Boston).

To find your nearest station, use the NOAA Tides and Currents Map. Search for your location (e.g., by city or ZIP code), click on a nearby station icon on the map, and copy the Station ID number. Ensure that the station has high and low tide predictions available.

The project uses Fishtape for unit and integration tests. Install it with Fisher:

CI: GitHub Actions runs the test suite on Ubuntu (GNU date) and macOS (BSD date) on every push and PR so that date-formatting and cache logic stay compatible with both.

fisher install jorgebucaran/fishtape

From the repo root, run all tests:

fishtape test/unit/*.fish test/integration/*.fish

Run only unit tests or only integration tests:

fishtape test/unit/*.fish
fishtape test/integration/*.fish

Tests use fixture data under test/fixtures/ and do not require network access or Tide to be installed.

• Weather shows as unavailable: With the default provider (Open-Meteo) and empty location, the plugin detects your location from your IP in the background. Wait a few seconds for the first fetch to complete, or open a new terminal to trigger a fresh lookup. You can also set weather location explicitly.

• Jorge Bucaran and Ilan Cosman for making Fisher and Tide.
• Moby Dick, the sweet air of the ocean breeze, and the gentle lullaby the sea sings before she breaks you on the rocks.
• NOAA - we'll miss them when they're gone... 🇺🇸😢
• Igor Chubin and all the contributors/sponsors of wttr.in.

• jorgebucaran/fisher
• ilancosman/tide
• gazorby/fish-abbreviation-tips
• laughedelic/pisces
• meaningful-ooo/sponge
• nickeb96/puffer-fish
• jorgebucaran/spark.fish
• jorgebucaran/humantime.fish
• jhillyerd/plugin-git
• PatrickF1/fzf.fish