OpenFetch

OpenFetch is a local-first terminal app and CLI for browsing, previewing, and downloading public weather, radar, observation, earthquake, and map datasets without memorizing source URLs or bucket paths.

It includes:

• An interactive Textual TUI for selecting data sources, plot products, regions, parameters, and quick actions.
• A Typer CLI for direct fetch commands and scripts.
• A FastAPI local server for integrations.
• A SQLite-backed local cache under ~/.openfetch/.
• An npm wrapper package named openfetch-cli that installs and launches the Python app.

Status

OpenFetch is public on GitHub at:

https://github.com/ShianMike/OpenFetch

OpenFetch is published on npm as openfetch-cli:

https://www.npmjs.com/package/openfetch-cli

Requirements

• Python 3.9+
• Node.js and npm, only if using the npm wrapper
• Internet access to the selected public data sources

Installation

Python Development Install

git clone https://github.com/ShianMike/OpenFetch.git
cd OpenFetch

# Option 1: Poetry
poetry install
poetry run openfetch

# Option 2: pip in a virtual environment
python -m venv .venv
.\.venv\Scripts\activate
pip install -e .
openfetch

On macOS/Linux, activate the virtual environment with:

source .venv/bin/activate

npm Registry Install

The npm wrapper creates a package-local Python virtual environment during postinstall, then installs OpenFetch into it.

npm install -g openfetch-cli
openfetch

npm Install From GitHub

Use the GitHub install path when you want the latest repository version before a new npm release.

npm install -g github:ShianMike/OpenFetch
openfetch

npm Install From Local Checkout

git clone https://github.com/ShianMike/OpenFetch.git
cd OpenFetch
npm install -g .
openfetch

Quick Start

Launch the interactive terminal UI:

openfetch

Fetch model ingredients directly:

# Latest HRRR surface CAPE
openfetch fetch hrrr sbcape

# GFS surface pressure and 10 m wind ingredients
openfetch fetch gfs sfc_mslp_wind --date 20260601 --cycle 12 --fhr 6

# GFS 2 m temperature with a Philippines plot/domain selection
openfetch fetch gfs sfc_tmp_2m --date 20260601 --cycle 12 --fhr 6 --region philippines

# ECMWF Open Data direct GRIB file
openfetch fetch ecmwf sfc_tmp_2m --date 20260601 --cycle 12 --fhr 3

Fetch non-model sources:

# GOES ABI CONUS product
openfetch fetch goes --satellite GOES-16 --product ABI-L2-MCMIPC

# NEXRAD Level II by station
openfetch fetch nexrad kltx

# SPC storm reports
openfetch fetch spc today

# METAR observations
openfetch fetch metar kord --hours 2

# USGS earthquakes
openfetch fetch usgs --minmagnitude 4.5 --hours 24

# USGS radius search
openfetch fetch usgs --minmagnitude 1.0 --hours 72 --latitude 37.7749 --longitude -122.4194 --maxradiuskm 500

# OpenStreetMap POI search
openfetch fetch osm cafe --latitude 40.7128 --longitude -74.006 --radius-km 3

CLI Reference

openfetch fetch CONNECTOR [ACTION] [OPTIONS]

Common options:

Option	Used by	Description
--date	Models, GOES, NEXRAD, SPC	latest, today, yesterday, or YYYYMMDD depending on connector
--cycle	Models, GOES, NEXRAD	UTC cycle/hour
--fhr	Weather models	Forecast hour
--region	Weather models	Region/domain slug such as native, global, conus, europe, western_pacific, or philippines
--satellite	GOES	Satellite mission, for example GOES-16 or GOES-18
--product	GOES	ABI product code, for example ABI-L2-MCMIPC
--hours	METAR, USGS	Lookback window
--minmagnitude	USGS	Minimum earthquake magnitude
--latitude, --longitude	USGS, OSM	Center point for radius searches
--maxradiuskm	USGS	Earthquake radius in kilometers
--radius-km	OSM	POI radius in kilometers

Interactive TUI

The TUI is the main workflow for browsing sources without memorizing commands.

It supports:

• Connector search and category browsing.
• Quick actions for sources that do not have plot-product lists.
• Weather-model plot-product selection.
• Region/domain picker for models.
• Request preview and equivalent CLI command display.
• Cache explorer, settings, and help tabs.

Keyboard shortcuts:

Key	Action
/	Focus connector search
f	Fetch selected dataset
c	Open cache explorer
s	Open settings
h	Open help
q	Quit
Tab / Shift+Tab	Move focus
Enter	Select or activate
Esc	Unfocus input or go back

Supported Sources

Weather Models

Connector	Aliases	Source	Notes
HRRR	hrrr, noaa-hrrr	NOAA NOMADS	Filtered GRIB ingredients, CONUS/native domains
GFS	gfs, noaa-gfs	NOAA NOMADS	Filtered 0.25 degree global GRIB ingredients
GEFS	gefs, noaa-gefs	NOAA NOMADS	Ensemble member support, defaults to p01 in CLI
RAP	rap, noaa-rap	NOAA NOMADS	Filtered regional GRIB ingredients
NAM	nam, noaa-nam	NOAA NOMADS	Uses current awphys filtered GRIB files
NBM	nbm, noaa-nbm	NOAA NOMADS	Uses current core blend filtered GRIB files
GDPS	gdps, cmc-gdps	MSC Datamart	Direct GRIB2 field files from Environment Canada
HREF	href, noaa-href	NOAA NOMADS	HREF CONUS ensemble products via filter_hrefconus.pl
ICON	icon, dwd-icon	DWD OpenData	Direct compressed GRIB2 files
RRFS	rrfs, noaa-rrfs	NOAA RRFS AWS bucket	Public prototype/direct GRIB2 files
ECMWF	ecmwf, euro	ECMWF Open Data	Direct IFS 0.25 degree GRIB2 files

NOAA NOMADS connectors use server-side GRIB filtering where available. Direct-file sources such as ECMWF, ICON, GDPS, and RRFS download source files directly; region selection is still used for plot/domain metadata and cache identity.

Radar, Satellite, Observations, and General Data

Connector	Aliases	Source	Output
GOES	goes, satellite	NOAA public S3 buckets	NetCDF/HDF5 satellite files
NEXRAD	nexrad, radar	Unidata NEXRAD Level II S3 bucket	Radar volume files
SPC Storm Reports	spc, reports, storms	NOAA SPC	CSV storm reports
METAR	metar, weather	AviationWeather.gov	JSON METAR reports
USGS Earthquakes	usgs, quakes	USGS FDSN event API	GeoJSON earthquake catalog
OpenStreetMap	osm, map, openstreetmap	Overpass API	JSON POI extracts

Region Selection

Model connectors expose only region presets that make sense for their source.

Global models commonly include:

• global
• north_america
• conus
• europe
• western_pacific
• philippines
• tropics

CONUS/regional models commonly include:

• native
• conus
• northeast
• southeast
• central
• west
• california

Use:

openfetch fetch gfs sfc_tmp_2m --region philippines
openfetch fetch hrrr sbcape --region southeast

Cache

OpenFetch stores cache metadata in:

~/.openfetch/openfetch.db

Downloaded files are stored in:

~/.openfetch/cache/

Commands:

openfetch cache list
openfetch cache clear
openfetch cache clear --connector metar

Local API Server

Start the local API:

openfetch serve

Open:

http://127.0.0.1:8000/docs

Useful endpoints:

• GET /connectors
• GET /connectors/{name}
• POST /fetch/{connector_name}
• GET /cache
• DELETE /cache

Development

Run the test suite and linter:

python -m pytest
python -m ruff check .

Check the npm package contents:

npm pack --dry-run

The package dry run should produce an openfetch-cli-0.1.0.tgz preview without writing a tracked tarball.

License

OpenFetch is licensed under the MIT License. See LICENSE.