National Hurricane Center CLI

Credible, real-time National Hurricane Center data for AI agents: active storms, parsed advisories, and tropical outlooks, text-first with link-outs for everything else.

This CLI gives agents the most credible real-time hurricane information straight from the National Hurricane Center and the National Weather Service: active storms (CurrentStorms.json), parsed Public Advisories and Forecast Discussions, the Tropical Weather Outlook with formation odds, and live tropical watches and warnings. It is built text-first and links out to the official GIS for anyone who wants polygons. Deep thanks to the forecasters, hurricane hunters, and support staff at NHC who sacrifice so much for the safety of so many. This is an unofficial tool; in an emergency, follow the official watches, warnings, and evacuation orders from NHC, the NWS, and your local authorities.

Install from source

This repository builds with the Go toolchain (1.26.4 or newer):

go install github.com/mvanhorn/printing-press-library/library/other/nhc/cmd/nhc-pp-cli@latest

Or clone and build the CLI plus the bundled MCP server:

git clone https://github.com/mvanhorn/printing-press-library
cd nhc-pp-cli
make build       # binaries in ./bin
go test ./...    # parsers verified against real 2024-season fixtures in internal/cli/testdata

Then run nhc-pp-cli doctor (no API key needed) and nhc-pp-cli brief --markdown for a one-call situational briefing.

Install via the Printing Press library

Once this CLI is published to the public library, one command installs both the nhc-pp-cli binary and the pp-nhc agent skill (Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, and other agents supported by the upstream skills CLI):

npx -y @mvanhorn/printing-press-library install nhc

For CLI only (no skill):

npx -y @mvanhorn/printing-press-library install nhc --cli-only

For skill only — installs the skill into the same agents as the default command above, but skips the CLI binary (use this to update or reinstall just the skill):

npx -y @mvanhorn/printing-press-library install nhc --skill-only

To constrain the skill install to one or more specific agents (repeatable — agent names match the skills CLI):

npx -y @mvanhorn/printing-press-library install nhc --agent claude-code
npx -y @mvanhorn/printing-press-library install nhc --agent claude-code --agent codex

Without Node

The generated install path is category-agnostic until this CLI is published. If npx is not available before publish, install Node or use the category-specific Go fallback from the public-library entry after publish.

Pre-built binary

Download a pre-built binary for your platform from the latest release. On macOS, clear the Gatekeeper quarantine: xattr -d com.apple.quarantine <binary>. On Unix, mark it executable: chmod +x <binary>.

Quick Start

# Confirm the CLI is wired up; no API key needed.
nhc-pp-cli doctor --dry-run

# What tropical cyclones are active right now (empty in the quiet season).
nhc-pp-cli storms list

# What may be developing, even when no storms are named.
nhc-pp-cli outlook --basin atl

# One-call situational briefing across storms, outlook, and alerts.
nhc-pp-cli brief --markdown

Unique Features

These capabilities aren't available in any other tool for this API.

One-call situational awareness

• brief — One command returns active storms, the tropical outlook, and live NWS tropical alerts as a single payload, with an optional human briefing.

  Reach for this first when an agent asks 'what is the tropical situation right now' — one call instead of four.

  nhc-pp-cli brief --basin atl --markdown
  

Parsed NHC products

• storm — Full detail for one storm: vitals plus every advisory-product URL and GIS link-out, with not-applicable fields returned as explicit null.

  Use when you have a storm id and need its products and graphics without parsing the raw feed.

  nhc-pp-cli storm al092024
  

• advisory — Fetches and parses the Public Advisory, Forecast Discussion, or Forecast/Marine Advisory into structured fields plus the clean body text, with no HTML scraping by the agent.

  Use when you need the meteorologist's reasoning or exact wind/pressure/movement fields, not a web page.

  nhc-pp-cli advisory al092024 --type tcd
  

• outlook — Parses the Tropical Weather Outlook for any basin into development areas and 48-hour / 7-day formation chances, with graphic link-outs.

  Use in the quiet season or to forecast-ahead; it is useful when 'storms list' is empty.

  nhc-pp-cli outlook --basin atl
  

Link-outs done right

• graphics — Returns the cone, track, surge, and wind link-outs for a storm; --download saves the files locally and --open views them.

  Use to hand a dashboard or person the official NHC graphics without re-deriving file paths.

  nhc-pp-cli graphics al092024 --kind cone,surge
  

• gis — Maps a storm to its ArcGIS REST layer URLs (forecast cone, wind field, watch/warning) for mapping clients. Link-out only; never ingested.

  Use when a caller wants the spatial layers; this CLI references them instead of parsing them.

  nhc-pp-cli gis al092024
  

Gratitude and safety

• credits — Thanks the people of the National Hurricane Center and states plainly that this is an unofficial tool and NHC/NWS is authoritative.

  Read or surface this so users know the source of truth and who to thank.

  nhc-pp-cli credits
  

Recipes

Active storms as compact JSON for an agent

nhc-pp-cli storms list --json --select id,name,classification,intensity,pressure

Returns just the high-gravity fields so an agent does not burn context on the full feed.

Read the forecast discussion

nhc-pp-cli advisory al092024 --type tcd

Fetches and parses the meteorologist's narrative for a storm id.

One-call situational briefing

nhc-pp-cli brief --basin atl --markdown

Bundles active storms, the outlook, and tropical alerts into a single human-readable briefing.

Official cone and surge graphics for a storm

nhc-pp-cli graphics al092024 --kind cone,surge

Hands back the official NHC link-outs without re-deriving file paths.

Usage

Run nhc-pp-cli --help for the full command reference and flag list.

Commands

alerts

Active NWS tropical watches and warnings (api.weather.gov)

• nhc-pp-cli alerts - Active tropical alerts. Pass a comma-separated --event list (Hurricane/Tropical Storm/Storm Surge x Warning/Watch). A descriptive User-Agent is mandatory (sent automatically).

storms

Active tropical cyclones from NHC CurrentStorms.json (all basins)

• nhc-pp-cli storms - List every active tropical cyclone across all basins. Returns [] when none are active (quiet season); run 'outlook' to see what may be developing.

Output Formats

# Human-readable table (default in terminal, JSON when piped)
nhc-pp-cli storms

# JSON for scripting and agents
nhc-pp-cli storms --json

# Filter to specific fields
nhc-pp-cli storms --json --select id,name,status

# Dry run — show the request without sending
nhc-pp-cli storms --dry-run

# Agent mode — JSON + compact + no prompts in one flag
nhc-pp-cli storms --agent

Agent Usage

This CLI is designed for AI agent consumption:

• Non-interactive - never prompts, every input is a flag
• Pipeable - --json output to stdout, errors to stderr
• Filterable - --select id,name returns only fields you need
• Previewable - --dry-run shows the request without sending
• Read-only by default - this CLI does not create, update, delete, publish, send, or mutate remote resources
• Offline-friendly - sync/search commands can use the local SQLite store when available
• Agent-safe by default - no colors or formatting unless --human-friendly is set

Exit codes: 0 success, 2 usage error, 3 not found, 5 API error, 7 rate limited, 10 config error.

Health Check

nhc-pp-cli doctor

Verifies configuration and connectivity to the API.

Configuration

Config file: ~/.config/nhc-pp-cli/config.toml

Static request headers can be configured under headers; per-command header overrides take precedence.

Troubleshooting

Not found errors (exit code 3)

• Check the resource ID is correct
• Run the list command to see available items

API-specific

• api.weather.gov returns 403 — A descriptive User-Agent is mandatory; nhc-pp-cli sends one automatically, so re-run rather than calling the API by hand.
• storms list is empty — That is the verified quiet-season contract (zero active storms). Run 'nhc-pp-cli outlook' to see formation chances.
• advisory says product not found — Products only exist for active or recent storms; check 'nhc-pp-cli storms list' for valid ids first.