ESPN — Printing Press CLI
Prerequisites: Install the CLI
This skill drives the
espn-pp-cli
binary.
You must verify the CLI is installed before invoking any command from this skill.
If it is missing, install it first:
Install via the Printing Press installer:
npx
-y
@mvanhorn/printing-press
install
espn --cli-only
Verify:
espn-pp-cli --version
Ensure
$GOPATH/bin
(or
$HOME/go/bin
) is on
$PATH
.
If the
npx
install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.23+):
go
install
github.com/mvanhorn/printing-press-library/library/media-and-entertainment/espn/cmd/espn-pp-cli@latest
If
--version
reports "command not found" after install, the install step did not put the binary on
$PATH
. Do not proceed with skill commands until verification succeeds.
When to Use This CLI
Reach for this when a user wants a quick sports lookup - current score, standings, upcoming schedule, head-to-head record, or a rich per-game summary (box score, leaders, scoring plays, odds, win probability). Also good for cross-league discovery (
today
) and offline search across synced data.
Don't reach for this if the user has a paid feed like Stats Perform or Sportradar that provides cleaner data, or if they need real-time websocket updates (ESPN's endpoints are polling-only). For betting odds in isolation, the per-game
summary
payload includes them but there is no league-wide odds command.
Unique Capabilities
Commands that only work because of local sync + cross-league tooling.
Cross-league discovery
today
— Today's scores across all major sports in one call. The fastest "what's on tonight" answer without picking a sport first.
trending
— Most-followed athletes and teams across all leagues, ranked by current popularity. Good for "who is hot right now" without naming a sport.
dashboard
— Reads
[favorites]
from
~/.config/espn-pp-cli/config.toml
and shows scores for each favorited team across leagues, in one call.
watch --league --league --league --league
historical records from synced data
espn-pp-cli streak football nfl --agent
current streaks
espn-pp-cli summary football nfl --event < id
--agent
full game payload incl. odds and box score
Run sync once, then rivals and streak answer instantly from the local store. summary is the richest single payload for a specific game (box score, leaders, scoring plays, odds, win probability). Offline search after sync espn-pp-cli sync --sport football --league nfl espn-pp-cli search "Mahomes"
finds in local store
Useful for repeated lookups in poor-connectivity environments or when batch-analyzing historical data. Favorites dashboard Add a [favorites] block to ~/.config/espn-pp-cli/config.toml : [favorites] nfl = ["KC", "BAL"] nba = ["LAL"] Then: espn-pp-cli dashboard --agent One call surfaces tonight's matchup status for every favorited team, grouped by league. Per-league fetches run in parallel and partial failures are reported alongside successful results. Pre-game odds and player digging espn-pp-cli odds basketball nba --agent
tonight's spreads / totals / moneylines
espn-pp-cli leaders basketball nba --category points --agent espn-pp-cli compare "LeBron James" "Stephen Curry" --sport basketball --league nba --agent espn-pp-cli boxscore < event_id
--agent
post-game player stats
espn-pp-cli plays basketball nba --event < id
--limit 50 --agent odds reads the scoreboard's per-event lines (no per-game summary calls). leaders --category filters to one stat category. compare resolves athlete ids by name, listing candidates and exiting 2 on ambiguity. boxscore infers sport+league from the most recent cache hit; pass --sport / --league to skip inference. Auth Setup None required. ESPN's public endpoints don't require an API key. The auth command exists for consistency but is a no-op. Optional config: ESPN_CONFIG — override config file path ESPN_BASE_URL — override base URL (for proxies or mirrors) NO_COLOR — standard no-color env var Agent Mode Add --agent to any command. Expands to --json --compact --no-input --no-color --yes . Use --select for field cherry-picking, --dry-run to preview requests, --no-cache to bypass GET cache. Filtering output --select accepts dotted paths to descend into nested responses; arrays traverse element-wise: espn-pp-cli < command
--agent --select id,name espn-pp-cli < command
--agent --select items.id,items.owner.name Use this to narrow huge payloads to the fields you actually need — critical for deeply nested API responses. Response envelope Data-layer commands wrap output in {"meta": {...}, "results": } . Parse .results for data and .meta.source to know whether it's live or local. The N results (live) summary is printed to stderr only when stdout is a TTY; piped/agent consumers see pure JSON on stdout. Exit Codes Code Meaning 0 Success 2 Usage error 3 Not found (team, game, athlete) 5 API error 7 Rate limited Installation go install github.com/mvanhorn/printing-press-library/library/media-and-entertainment/espn/cmd/espn-pp-cli@latest espn-pp-cli doctor MCP Server go install github.com/mvanhorn/printing-press-library/library/media-and-entertainment/espn/cmd/espn-pp-mcp@latest claude mcp add espn-pp-mcp -- espn-pp-mcp Argument Parsing Given $ARGUMENTS : Empty, help , or --help → run espn-pp-cli --help install → CLI; install mcp → MCP Anything else → resolve
from user intent (e.g., "Lakers" → basketball nba ), check which espn-pp-cli (offer install if missing), run with --agent . Agent Workflow Features This CLI exposes three shared agent-workflow capabilities patched in from cli-printing-press PR #218. Named profiles Persist a set of flags under a name and reuse them across invocations.
Save the current non-default flags as a named profile
espn-pp-cli profile save < name
Use a profile — overlays its values onto any flag you don't set explicitly
espn-pp-cli --profile < name
< command
List / inspect / remove
espn-pp-cli profile list espn-pp-cli profile show < name
espn-pp-cli profile delete < name
--yes Flag precedence: explicit flag > env var > profile > default. --deliver Route command output to a sink other than stdout. Useful when an agent needs to hand a result to a file, a webhook, or another process without plumbing. espn-pp-cli < command
--deliver file:/path/to/out.json espn-pp-cli < command
--deliver webhook:https://hooks.example/in File sinks write atomically (tmp + rename). Webhook sinks POST application/json (or application/x-ndjson when --compact is set). Unknown schemes produce a structured refusal listing the supported set. feedback Record in-band feedback about this CLI from the agent side of the loop. Local-only by default; safe to call without configuration. espn-pp-cli feedback "what surprised you or tripped you up" espn-pp-cli feedback list
show local entries
espn-pp-cli feedback clear --yes
wipe
Entries append to ~/.espn-pp-cli/feedback.jsonl as JSON lines. When ESPN_FEEDBACK_ENDPOINT is set and either --send is passed or ESPN_FEEDBACK_AUTO_SEND=true , the entry is also POSTed upstream (non-blocking — local write always succeeds).