Pp Surfline

<!-- GENERATED FILE — DO NOT EDIT.
     This file is a verbatim mirror of library/other/surfline/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/". -->

Surfline — Printing Press CLI

Prerequisites: Install the CLI

This skill drives the surfline-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:

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

2. Verify: surfline-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.6 or newer). This installs into $GOPATH/bin (default $HOME/go/bin), so add that directory to $PATH instead:

go install github.com/mvanhorn/printing-press-library/library/other/surfline/cmd/surfline-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.

Pulls wave, swell, wind, tide, weather, conditions and rating straight from Surfline's API over a browser-fingerprint transport that clears Cloudflare. The differentiators live in the local SQLite store: 'rank' scans a set of spots and sorts them best-first (Surfline's own comparison is web-only), 'now' collapses one spot's next hours into a paddle/no-paddle readout, 'windows' finds the daylight blocks worth surfing, and 'alert run' evaluates your own threshold rules for cron.

When to Use This CLI

Use this CLI when an agent or script needs Surfline forecast data as structured output: checking whether one break is worth surfing, ranking several spots to choose between them, finding the good daylight windows, or evaluating user-defined surf-condition alerts on a schedule. It is the right tool when you want raw swell/wind/tide numbers rather than a star rating, or a local history of how forecasts read over time.

Anti-triggers

Do not use this CLI for:

• Do not use this CLI to watch live cam video — it returns cam still/stream/rewind URLs, not a video stream.
• Do not use it for global non-Surfline weather or for spots Surfline doesn't cover; use a weather API instead.
• Do not use it to book sessions, post to Surfline, or manage a Surfline account — it is read-only forecast tooling.
• Do not rely on >6-day forecasts without a premium token; those horizons are gated.

Unique Capabilities

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

Decision-shaped readouts

• now — One spot's next few hours as a paddle/no-paddle line readout: swell, wind, tide and rating joined per hour.

  Reach for this when an agent needs a go/no-go answer for one break without parsing five separate forecast payloads.

  surfline-pp-cli now 5842041f4e65fad6a7708807 --agent

• rank — Score and sort several spots best-first on a transparent sum of wave, wind and swell optimalScore.

  Reach for this to pick today's best break from a set instead of opening N forecast pages.

  surfline-pp-cli rank 5842041f4e65fad6a7708807 5842041f4e65fad6a7708cfd --agent

• windows — Emit only the contiguous time blocks where wave, wind and swell optimalScore are all good, daylight-only.

  Reach for this to find the good time slots at one spot without eyeballing an hourly graph.

  surfline-pp-cli windows 5842041f4e65fad6a7708807 --days 3 --agent

Raw data for scripts

• raw — Pipe-friendly table/JSON of min/max/optimalScore/humanRelation plus swell components and wind directionType/gust, no rating editorializing.

  Reach for this when an agent needs raw numbers to feed its own scoring instead of a pre-judged rating.

  surfline-pp-cli raw 5842041f4e65fad6a7708807 --agent --select data.wave.surf.max,data.wave.swells.period

• buoy-check — Show nearby-buoy observed swell against the spot's wave forecast for the same window, side by side.

  Reach for this to tell whether the forecast is tracking the actual buoy readings before trusting it.

  surfline-pp-cli buoy-check 5842041f4e65fad6a7708807 --agent

Local state that compounds

• alert run — Store swell/wind/tide threshold rules locally; alert run fetches a fresh forecast, evaluates them, prints matches and sets an exit code for cron.

  Reach for this in unattended/cron contexts to get a nonzero exit when conditions a user defined are met.

  surfline-pp-cli alert run --agent

• journal show — Snapshot the current forecast into local SQLite and review a spot's snapshots over time.

  Reach for this to review how a spot's forecast has read over the past days from your own captures.

  surfline-pp-cli journal show 5842041f4e65fad6a7708807 --agent

• search — Resolve spot names to spotIds via FTS over the locally-synced taxonomy, with no network.

  Reach for this to turn a spot name into an ID before calling forecast commands, even offline.

  surfline-pp-cli search "Ocean Beach" --agent

HTTP Transport

This CLI uses Chrome-compatible HTTP transport for browser-facing endpoints. It does not require a resident browser process for normal API calls.

Command Reference

buoys — Nearby NDBC-style buoy observations

• surfline-pp-cli buoys — Buoys near a lat/lon with observed swell readings

regions — Region/subregion-level forecasts

• surfline-pp-cli regions — Subregion conditions forecast (multi-day AM/PM rating across a subregion)

spots — Find spots and pull per-spot forecasts and reports (wave, wind, tide, weather, conditions, rating)

• surfline-pp-cli spots batch — Rich per-spot info for many spots in one call (conditions, cameras, current swell/wind/tide)
• surfline-pp-cli spots conditions — AM/PM conditions: rating, observation, surf range, forecaster notes, humanRelation
• surfline-pp-cli spots details — Spot metadata: name, location, ability levels, travel info
• surfline-pp-cli spots find — Live spot search by name (online); returns hits with spotIds.
• surfline-pp-cli spots forecast — Combined forecast: forecasts + tides + sunrise/sunset in one call
• surfline-pp-cli spots rating — Rating forecast: VERY_POOR..EPIC key plus numeric value per time point
• surfline-pp-cli spots report — Spot report: forecaster narrative, current conditions, cameras
• surfline-pp-cli spots sunlight — Sunlight forecast: dawn, sunrise, sunset, dusk local times
• surfline-pp-cli spots tides — Tide forecast: HIGH/LOW/NORMAL extremes with heights and local times
• surfline-pp-cli spots wave — Wave and swell forecast: surf min/max, optimalScore, swell components (height/period/direction)
• surfline-pp-cli spots weather — Weather forecast: temperature, condition, pressure, plus sunlight times
• surfline-pp-cli spots wind — Wind forecast: speed, direction, directionType (Onshore/Offshore/Cross-shore), gust, optimalScore

taxonomy — Browse Surfline's geographic hierarchy (geoname > region > subregion > spot)

• surfline-pp-cli taxonomy <id> — Fetch a taxonomy node and its children (ancestors via in, children via contains)

Finding the right command

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

surfline-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 match; exit code 2 means no confident match — fall back to --help or use a narrower query.

Recipes