cli

neaps Command Line Interface

Command line interface for tide predictions. Search for stations, view high/low tides, and generate water level timelines from your terminal.

Install

Homebrew (macOS / Linux)

brew install openwatersio/tap/neaps

Shell script (macOS / Linux)

curl -fsSL https://raw.githubusercontent.com/openwatersio/neaps/main/install.sh | sh

npm

npm install -g @neaps/cli

Download binary

Pre-built binaries for macOS (Apple Silicon), Linux, and Windows are available on the GitHub Releases page.

Usage

Find stations

Search for tide prediction stations by name, region, or country:

neaps stations "san francisco"

Find stations near a location:

neaps stations --near 37.8,-122.5

Combine search with proximity:

neaps stations "portland" --near 45.5,-122.7

Options:

Flag	Description
-n, --near <lat,lon>	Find stations near coordinates
--ip	Use IP geolocation to find nearby stations
-l, --limit <n>	Maximum results (default: 10)
-a, --all	Show all matching stations (no limit)
-f, --format <format>	Output format: text, json

Tide extremes (high/low)

Get predicted high and low tides for a station:

neaps extremes --station noaa/9414290

Use your current location:

neaps extremes --ip

Options:

Flag	Description
-s, --station <id>	Station ID
-n, --near <lat,lon>	Find nearest station to coordinates
--ip	Use IP geolocation to find nearest station
--start <date>	Start date in ISO format (default: now)
--end <date>	End date (default: 72h from start)
-u, --units <units>	meters or feet (default: meters)
-f, --format <format>	Output format: text, json

Water level timeline

Get a water level timeline with an ASCII chart:

neaps timeline --station noaa/9414290

Specify a date range and interval:

neaps timeline --station noaa/9414290 --start 2026-01-01 --end 2026-01-02 --interval 30

Options:

Flag	Description
-s, --station <id>	Station ID
-n, --near <lat,lon>	Find nearest station to coordinates
--ip	Use IP geolocation to find nearest station
--start <date>	Start date in ISO format (default: now)
--end <date>	End date (default: 24h from start)
-u, --units <units>	meters or feet (default: meters)
--interval <minutes>	Minutes between data points (default: 60)
-f, --format <format>	Output format: text, json

API server

Start the Neaps REST API server locally:

neaps serve

Specify a custom port:

neaps serve --port 8080

Options:

Flag	Description
-p, --port <n>	Port to listen on (default: 3000)

JSON output

All commands support --format json for machine-readable output:

neaps extremes --station noaa/9414290 --format json
neaps timeline --station noaa/9414290 --format json
neaps stations "seattle" --format json

License

MIT