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