pp-usgs-earthquakes

What this skill does

<!-- GENERATED FILE — DO NOT EDIT.
     This file is a verbatim mirror of library/other/usgs-earthquakes/SKILL.md,
     regenerated post-merge by tools/generate-skills/. Hand-edits here are
     silently overwritten on the next regen. Edit the library/ source instead.
     See the repository agent guide, section "Generated artifacts: registry.json, cli-skills/". -->

# USGS Earthquakes — Printing Press CLI

## Prerequisites: Install the CLI

This skill drives the `usgs-earthquakes-pp-cli` binary. **You must verify the CLI is installed before invoking any command from this skill.** If it is missing, install it first:

1. Install via the Printing Press installer. It defaults binaries to `$HOME/.local/bin` on macOS/Linux and `%LOCALAPPDATA%\Programs\PrintingPress\bin` on Windows:
   ```bash
   npx -y @mvanhorn/printing-press-library install usgs-earthquakes --cli-only
   ```
2. Verify: `usgs-earthquakes-pp-cli --version`
3. Ensure the reported install directory is on `$PATH` for the agent/runtime that will invoke this skill.

If the `npx` install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.26.3 or newer):

```bash
go install github.com/mvanhorn/printing-press-library/library/other/usgs-earthquakes/cmd/usgs-earthquakes-pp-cli@latest
```

If `--version` reports "command not found" after install, the runtime cannot see the binary directory on `$PATH`. Do not proceed with skill commands until verification succeeds.

## When to Use This CLI

Reach for this CLI any time an agent needs to answer questions about USGS earthquakes — recent activity, historical search, single-event detail, aftershock sequences, regional comparisons, or live monitoring. It is the right choice when speed matters (offline SQLite cache), when output must be agent-friendly (--json, --select, --compact, --csv on every command), or when the workflow spans multiple events that the raw FDSN API would require stitching together. Not the right choice for non-USGS seismic networks (IRIS event service, EMSC) or for waveform/station data — those need an FDSN station-service client like obspy.

## When Not to Use This CLI

Do not activate this CLI for requests that require creating, updating, deleting, publishing, commenting, upvoting, inviting, ordering, sending messages, booking, purchasing, or changing remote state. This printed CLI exposes read-only commands for inspection, export, sync, and analysis.

## Unique Capabilities

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

### Real-time monitoring
- **`watch`** — Long-running poll of a USGS summary feed with deduplication against the local store. Invokes an optional shell hook per new event for custom alerting.

  _Reach for this when you want a long-running monitor over USGS earthquakes without writing a polling loop. Pluggable shell hook means it composes with notify-send, Slack curl, paging systems, anything._

  ```bash
  usgs-earthquakes-pp-cli watch --min-magnitude 5 --notify "echo {id}: {place}" --interval 60s
  ```

### Cross-event analysis
- **`aftershocks`** — Show events within R km and T days after a mainshock, ordered by time. Local SQLite haversine query with FDSN fallback when uncached.

  _Reach for this any time you have a mainshock event ID and need to see what came after. The single-call alternative is dozens of /query invocations stitched in jq._

  ```bash
  usgs-earthquakes-pp-cli aftershocks us7000abcd --radius-km 100 --days 30 --min-mag 3.0 --json
  ```
- **`swarm-detect`** — Detect time-space clusters in the local earthquake store. Grid-bucket clustering finds foreshock/aftershock sequences, volcanic swarms, and induced seismicity hotspots.

  _Reach for this when monitoring a volcano, fault zone, or fracking region for unusual clustering. The output names each cluster with center, count, peak magnitude, and time range._

  ```bash
  usgs-earthquakes-pp-cli swarm-detect --bbox -122.5,46.5,-121.5,47.5 --window 7d --min-events 10 --cluster-radius-km 20 --json
  ```
- **`compare`** — Side-by-side comparison of two regions or two time periods. Returns parallel columns with counts, max magnitude, and total seismic energy.

  _Reach for this when answering 'is region A more active than region B?' or 'is this region quieter than it used to be?'. Outputs delta percentages and energy ratios._

  ```bash
  usgs-earthquakes-pp-cli compare --region-a -122.5,37.5,-122.0,37.9 --region-b -118.5,33.8,-118.0,34.2 --window 30d --json
  ```

### Agent-native output
- **`brief`** — Agent-ready briefing for a single earthquake: magnitude, place, PAGER alert, DYFI felt count, ShakeMap MMI, tsunami status, and product inventory.

  _Reach for this in newsroom or Slack contexts where you need a one-event summary an editor or downstream agent can drop straight into copy. Includes the USGS event-page URL._

  ```bash
  usgs-earthquakes-pp-cli brief us7000abcd --format markdown
  ```
- **`top`** — Rank recent events by composite editorial score: significance × alert weight × felt count × tsunami flag. Default window 24h, limit 10.

  _Reach for this when you need 'the events that matter right now' rather than 'all events by magnitude'. The composite score promotes felt + PAGER + tsunami over raw magnitude._

  ```bash
  usgs-earthquakes-pp-cli top --window 24h --limit 10 --score composite --json
  ```

### Local state that compounds
- **`changes`** — Diff since the last sync: what events appeared, what events had magnitudes/depths/alerts revised, what events were retracted. Tracks USGS solution revisions over time. Returns 'no revisions recorded yet' until at least two sync runs have completed.

  _Reach for this when a previously-automatic event might have just been reviewed by an analyst (revising magnitude or alert), or to answer 'what's new since I last looked?'_

  ```bash
  usgs-earthquakes-pp-cli changes --since 24h --type revised --min-mag-delta 0.3 --json
  ```
- **`decode-id`** — Parse a USGS event ID into its source network code, sequence, and operator name. Joins the cached contributors dictionary for the network display name.

  _Reach for this when you see an opaque USGS event ID (e.g. nc73947885, ak0202xyz) and need to know which network reported it before reading the data._

  ```bash
  usgs-earthquakes-pp-cli decode-id us7000abcd
  ```

## Command Reference

**catalogs** — USGS earthquake source catalogs (ANSS contributors and processing centers)

- `usgs-earthquakes-pp-cli catalogs` — List all source catalogs known to the FDSN Event service (XML response)

**contributors** — USGS earthquake data contributors

- `usgs-earthquakes-pp-cli contributors` — List all data contributors known to the FDSN Event service (XML response)

**events** — Search and retrieve earthquakes from the USGS FDSN Event service

- `usgs-earthquakes-pp-cli events count` — Count events matching the given filter, without returning event data (fast precheck before a full search)
- `usgs-earthquakes-pp-cli events get` — Fetch a single earthquake event by USGS event ID (e.g. us7000abcd)
- `usgs-earthquakes-pp-cli events search` — Search the USGS earthquake catalog with full FDSN parameter coverage

**feeds** — Pre-built GeoJSON earthquake summary feeds (updated every minute by USGS)

- `usgs-earthquakes-pp-cli feeds <feed>` — Fetch a named GeoJSON summary feed. Use one of: significant_{hour|day|week|month}, 4.5_{hour|day|week|month},...

**metadata** — FDSN Event service metadata: enumerated values for every parameter

- `usgs-earthquakes-pp-cli metadata` — Show enum dictionaries for catalogs, contributors, event types, product types, and magnitude types


### Finding the right command

When you know what you want to do but not which command does it, ask the CLI directly:

```bash
usgs-earthquakes-pp-cli which "<capability in your own words>"
```

`which` resolves a natural-language capability query to the best matching command from this CLI's curated feature index. Exit code `0` means at least one m