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

> Explore common use cases and commands for the Herbie CLI tool. Discover, inspect, and download NWP model data quickly and easily without writing code.

- Repository: [Brian Blaylock/herbie](https://github.com/blaylockbk/herbie)
- Tags: how-to-guide
- Published: 2026-02-26

---

**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`](https://github.com/blaylockbk/herbie/blob/main/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`](https://github.com/blaylockbk/herbie/blob/main/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`](https://github.com/blaylockbk/herbie/blob/main/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.

```bash
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()`).

```bash

# 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()`.

```bash

# 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.

```bash
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`](https://github.com/blaylockbk/herbie/blob/main/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`](https://github.com/blaylockbk/herbie/blob/main/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`](https://github.com/blaylockbk/herbie/blob/main/hrrr.py), [`gfs.py`](https://github.com/blaylockbk/herbie/blob/main/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:**

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

```

**Download GFS temperature at 850 hPa for forecast hour 24:**

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

```

**List all variables in a RAP run:**

```bash
herbie inventory -m rap -d 2023031512 -f 0

```

**Retrieve index file URL for debugging:**

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

```

**Show all possible source URLs:**

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

```

**Download multiple forecast hours:**

```bash
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:**

```bash
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`](https://github.com/blaylockbk/herbie/blob/main/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`](https://github.com/blaylockbk/herbie/blob/main/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`](https://github.com/blaylockbk/herbie/blob/main/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`](https://github.com/blaylockbk/herbie/blob/main/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`.