Herbie CLI Tool: Common Use Cases and Commands for Weather Data Retrieval

The Herbie CLI tool provides a command-line interface that wraps the Herbie Python class to discover, inspect, and download archived Numerical Weather Prediction (NWP) model data without writing code.

The Herbie CLI tool enables terminal-based access to high-resolution weather models like HRRR, GFS, and RAP in the blaylockbk/herbie repository. It translates shell commands into method calls on the Herbie class, allowing researchers to locate GRIB2 files, view inventory tables, and retrieve specific atmospheric variables directly from archives hosted on AWS, Google Cloud, and NOAA servers.

What is the Herbie CLI Tool?

The Herbie CLI tool is implemented in src/herbie/cli.py and serves as a thin wrapper around the core Herbie Python API. It translates command-line arguments into method calls on the Herbie class from src/herbie/core.py, allowing users to locate GRIB2 files, view inventory tables, and download specific atmospheric variables from archives hosted on AWS, Google Cloud, and NOAA servers.

Core Herbie CLI Commands and Use Cases

The CLI organizes functionality into sub-commands defined in src/herbie/cli.py, each mapping to specific workflows in NWP data retrieval.

Locating Data Files with herbie data

The herbie data command prints the URL of a requested GRIB2 file without downloading it. This is useful for verifying data availability or integrating Herbie into external download pipelines. The command calls the cmd_data() helper function, which accesses the Herbie.grib property.

herbie data -m hrrr --product sfc -d "2023-03-15 12:00" -f 0

Inspecting Inventory with herbie index and herbie inventory

These commands help users understand what variables are available in a model run before downloading. The herbie index command returns the URL of the inventory index file (accessing Herbie.idx), while herbie inventory parses and displays a table of all available fields (calling Herbie.inventory()).

# Get the index file URL

herbie index -m hrrr -d 2023-03-15T00:00 -f 0

# View parsed inventory table

herbie inventory -m rap -d 2023031512 -f 0

Downloading Data with herbie download

The herbie download command retrieves full GRIB2 files or variable subsets to a local directory. It supports regex-based subsetting via the --subset flag to download only specific variables, reducing bandwidth and storage requirements. This command uses the cmd_download() helper which invokes Herbie.download().

# Download full file

herbie download -m gfs --product 0p25 -d 2023-03-15T00:00 -f 24

# Download subset (temperature at 850 hPa)

herbie download -m gfs --product 0p25 \
    -d 2023-03-15T00:00 -f 24 \
    --subset ":TMP:850 mb:"

Listing Available Sources with herbie sources

This command displays all possible source URLs for a given model run in JSON format, useful for debugging or understanding data replication across NOAA, AWS, and Google Cloud endpoints. It accesses the Herbie.SOURCES property.

herbie sources -m hrrr -d 2023-03-15 -f 0

How the Herbie CLI Works Under the Hood

The CLI implementation in src/herbie/cli.py uses a modular architecture that separates argument parsing from execution logic.

The common_arguments() function defines shared parameters across all sub-commands, including:

• -m / --model: The NWP model name (e.g., hrrr, gfs, rap)
• -d / --date: The model run date/time
• -f / --fxx: The forecast hour
• -p / --priority: Data source priority (e.g., aws, google, nomads)

Each sub-command handler (such as cmd_data(), cmd_download(), and cmd_inventory()) instantiates a Herbie object from src/herbie/core.py and calls the corresponding method. Model-specific URL templates and source priorities are defined in src/herbie/models/*.py (e.g., hrrr.py, gfs.py), which the CLI loads dynamically based on the --model argument.

The CLI also supports a global --show_versions flag that prints the version of herbie-data together with the versions of its key dependencies (e.g., xarray, cfgrib, pandas).

Practical Herbie CLI Examples

Here are complete, runnable examples demonstrating common workflows with the Herbie CLI tool:

Locate a HRRR surface file for today at 12Z:

herbie data -m hrrr --product sfc -d "2023-03-15 12:00" -f 0

Download GFS temperature at 850 hPa for forecast hour 24:

herbie download -m gfs --product 0p25 \
    -d 2023-03-15T00:00 -f 24 \
    --subset ":TMP:850 mb:"

List all variables in a RAP run:

herbie inventory -m rap -d 2023031512 -f 0

Retrieve index file URL for debugging:

herbie index -m hrrr -d 2023-03-15T00:00 -f 0

Show all possible source URLs:

herbie sources -m hrrr -d 2023-03-15 -f 0

Download multiple forecast hours:

herbie download -m hrrr -d 2023-03-15T00:00 2023-03-15T06:00 \
    -f 1 3 6 --subset ":UGRD:10 m:"

Restrict to Google Cloud source:

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

Summary

• The Herbie CLI tool wraps the Python Herbie class to provide terminal-based access to NWP model archives.
• Core commands include herbie data (locate files), herbie inventory (inspect contents), and herbie download (retrieve data).
• The CLI shares common arguments across all sub-commands via common_arguments() in src/herbie/cli.py.
• Model-specific logic resides in src/herbie/models/*.py, while core download and inventory methods are implemented in src/herbie/core.py.
• Users can filter by data source priority (-p aws, -p google, -p nomads) and download variable subsets using regex patterns.

Frequently Asked Questions

What is the Herbie CLI tool used for?

The Herbie CLI tool is used to discover, inspect, and download archived Numerical Weather Prediction (NWP) model data from the command line. It supports models like HRRR, GFS, and RAP, allowing users to locate GRIB2 files, view inventory tables, and download specific atmospheric variables without writing Python code.

How do I download specific variables using the Herbie CLI?

Use the herbie download command with the --subset flag followed by a regex pattern that matches the GRIB2 field you need. For example, to download only temperature at 850 hPa from a GFS run, execute: herbie download -m gfs --product 0p25 -d 2023-03-15T00:00 -f 24 --subset ":TMP:850 mb:".

Where is the Herbie CLI implemented in the source code?

The Herbie CLI is implemented in src/herbie/cli.py in the blaylockbk/herbie repository. This file defines the argument parser, the common_arguments() function for shared parameters, and individual command handlers like cmd_data(), cmd_download(), and cmd_inventory() that instantiate the Herbie class from src/herbie/core.py.

Can I specify which data source to use with the Herbie CLI?

Yes, use the -p or --priority flag to specify the data source priority. The CLI supports sources like aws (Amazon Web Services), google (Google Cloud), and nomads (NOAA operational servers). For example, to force the use of Google Cloud for a HRRR query, run: herbie data -m hrrr -d 2023-03-15 -f 0 -p google.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}