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

The npm package metadata is ready as openfetch-cli, but registry install only works after publishing to npm. Until then, install from the GitHub repo or from a local checkout.

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 Install From GitHub

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

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

npm Registry Install

Use this only after openfetch-cli is published to npm:

npm install -g openfetch-cli
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.