⌨️ Herbie CLI#

The Herbie Command Line Interface (CLI) provides easy access to archived Numerical Weather Prediction (NWP) model data through a simple command-line tool. It leverages the Herbie Python package to search for, inspect, and download GRIB2 files from various data sources.

Installation#

The CLI is installed automatically when you install the Herbie package:

pip install herbie-data

You may also install it as a tool with uv

uv tool install herbie-data

Or use it with uvx

uvx --from herbie-data herbie

Basic Usage#

Show all the options with --help

herbie --help

The basic usage is:

herbie COMMAND [OPTIONS]

Available Commands#

Command	Description
`data`	Find and show a GRIB2 file URL.
`index`	Find and show a GRIB2 index file URL.
`inventory`	Show inventory of GRIB2 fields or subset.
`download`	Download GRIB2 file or subset.
`sources`	Return JSON of possible GRIB2 source URLs.
`plot`	Quick plot of GRIB2 field (Not implemented).

Examples#

# Get the URL for a HRRR surface file from today at 12Z
herbie data -m hrrr --product sfc -d "2023-03-15 12:00" -f 0

# Download GFS 0.25° forecast hour 24 temperature at 850mb
herbie download -m gfs --product 0p25 -d 2023-03-15T00:00 -f 24 --subset ":TMP:850 mb:"

# View all available variables in a RAP model run
herbie inventory -m rap -d 2023031512 -f 0

# Download multiple forecast hours for a date range
herbie download -m hrrr -d 2023-03-15T00:00 2023-03-15T06:00 -f 1 3 6 --subset ":UGRD:10 m:"

# Specify custom source priority (check only Google)
herbie data -m hrrr -d 2023-03-15 -f 0 -p google

Common Arguments#

All commands support the following arguments:

Required Arguments#

Argument	Description
`-d`, `--date`	Model initialization date (required)

Optional Arguments#

Argument	Description	Default
`-m`, `--model`	The name of the NWP model	`hrrr`
`--product`	Product type specific to the model	model's default
`-f`, `--fxx`	Forecast hour(s)	`[0]`
`-p`, `--priority`	Data source priority order	model's default
`--verbose`	Enable verbose output	`False`

Some commands accept additional arguments:

Command	Additional Arguments
`inventory`, `download`, `plot`	`--subset`: Search string for filtering variables
`download`	`--save_dir`: The root directory to save downloaded files.\n`--overwrite`: Replace existing GRIB2 files.

Global Options#

Option	Description
`-v`, `--version`	Show Herbie version number
`--show_versions`	Show versions of Herbie and dependencies

Detailed Argument Reference#

Date Format (`-d`, `--date`)#

The date argument accepts multiple formats:

YYYYMMDDHH (e.g., 2023031500)
YYYY-MM-DD (e.g., 2023-03-15, assumes 00Z)
YYYY-MM-DDTHH:MM (e.g., 2023-03-15T12:00)
"YYYY-MM-DD HH:MM" (e.g., "2023-03-15 12:00")

You can also specify multiple dates for batch processing:

herbie data -d 2023-03-15T00:00 2023-03-15T06:00 2023-03-15T12:00 -m hrrr -f 0

Model (`-m`, `--model`)#

The model argument specifies which NWP model to use. Common options include:

Model	Description
`hrrr`	High-Resolution Rapid Refresh (3km CONUS)
`gfs`	Global Forecast System (global coverage)
`rap`	Rapid Refresh (13km CONUS)
`nam`	North American Mesoscale (12km North America)
`rrfs`	Rapid Refresh Forecast System
`ifs`	European Centre for Medium-Range Weather Forecasts
`nwm`	National Water Model

Product Type (`--product`)#

The product type is model-specific and determines which variant of the model output to use.

Some examples:

HRRR Products#

sfc - Surface fields (2D)
prs - Pressure level fields (3D)
nat - Native model level fields (3D)
subh - Subhourly fields (15min)

GFS Products#

0p25 - 0.25° resolution
0p50 - 0.50° resolution
1p00 - 1.00° resolution

If not specified, Herbie will use the default product for the selected model.

Forecast Hour (`-f`, `--fxx`)#

Forecast hour represents the number of hours into the future that the model is predicting. You can specify a single forecast hour or multiple hours:

herbie download -m hrrr -d 2023-03-15T00:00 -f 0 1 3 6 12

Available forecast hours vary by model.

Data Source Priority (`-p`, `--priority`)#

Herbie can download data from multiple archive sources. You can control the order in which these sources are checked:

herbie data -m hrrr -d 2023-03-15 -f 0 -p aws nomads

Available data sources:

Source	Description
`aws`	Amazon Web Services (NOAA Open Data Program)
`google`	Google Cloud Platform (NOAA Open Data Program)
`nomads`	NOAA NOMADS server
`azure`	Microsoft
`ecmwf`	ECMWF Open-data
others