--- id: gh-pp-espn name: "pp-espn" url: https://skills.yangsir.net/skill/gh-pp-espn author: mvanhorn domain: data-ai tags: ["sports", "espn", "scores", "data-retrieval", "cli"] install_count: 2000 rating: 4.30 (120 reviews) github: https://github.com/mvanhorn/printing-press-library/tree/main/cli-skills/pp-espn --- # pp-espn > 此技能提供 ESPN 体育数据查询，包括实时比分、赛程、排名、球队统计、比赛总结（含数据统计、赔率、胜率）、头对头比较等。覆盖 NFL、NBA、MLB 等多个联赛，无需 API 密钥，支持离线搜索，快速获取体育信息。 **Stats**: 2,000 installs · 4.3/5 (120 reviews) ## Before / After 对比 ### 快速获取体育赛事信息 **Before**: 手动在 ESPN 网站或应用中搜索特定比赛的比分、统计数据或赛程，需要多次点击和页面跳转，耗时且打断工作流。 **After**: 通过命令行工具直接查询，一步到位获取实时比分、详细赛况、赔率等信息，极大提升信息获取效率。 | Metric | Before | After | Change | |---|---|---|---| | 信息获取步骤 | 10步 | 1步 | -90% | ## Readme # 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: 1. Install via the Printing Press installer: ```bash npx -y @mvanhorn/printing-press install espn --cli-only ``` 2. Verify: `espn-pp-cli --version` 3. 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.26.3 or newer): ```bash 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 --event `** — Live score updates for a specific game (polls every 30s). Use `scores` or `today` to find the game, then `watch` to follow it live. ### Game-state intelligence - **`summary --event `** — Detailed game summary including box score, leaders, scoring plays, odds, and win probability. The single richest payload per game. - **`boxscore `** — Just the per-player box score for an event id, with sport+league inferred from a recent scoreboard cache hit. Pass `--sport`/`--league` to skip inference. - **`plays --event `** — Play-by-play feed for a specific event. Optional `--limit` (default 200). - **`recap `** — Post-game recap with box score and leaders for the most recent completed game in a league. - **`scoreboard `** — Live scoreboard with date filtering, week/group selectors, and competition metadata. - **`odds `** — Spread, over/under, and moneyline lines for tonight's slate, derived from the scoreboard payload (no per-game summary calls). ### Standings and rankings - **`standings `** — Conference/division standings. - **`rankings `** — Current AP, Coaches, and CFP poll rankings (NCAAF/NCAAM). - **`streak `** — Current win/loss streaks across teams in a league, computed from synced data. - **`rivals `** — Head-to-head records between teams in a league from synced data. - **`h2h --sport --league `** — Deeper head-to-head detail for one specific pair, including average score and recent meetings list. - **`sos `** — Strength-of-schedule per team, derived from the standings payload, sorted descending. ### People - **`leaders [--category ]`** — Statistical leaders across categories with optional filter. - **`compare --sport --league `** — Side-by-side season stats for two athletes. Ambiguous names list candidates and exit 2. - **`injuries `** — Active injury report across the league, grouped by team. - **`transactions `** — Recent trades, signings, and waivers. ### Local store - **`sync`** — Pull a sport+league dataset into local SQLite for offline analysis. - **`search ""`** — Full-text search across synced events and news. - **`sql `** — Run read-only SQL queries against the local database. ## Command Reference Live action: - `espn-pp-cli scores ` — Current scores - `espn-pp-cli today` — Today's scores across all major sports - `espn-pp-cli scoreboard ` — Scoreboard with optional date filtering - `espn-pp-cli watch --event ` — Live score polling for one game - `espn-pp-cli standings ` — League standings - `espn-pp-cli trending` — Most-followed athletes and teams across leagues - `espn-pp-cli dashboard` — Favorites snapshot from `~/.config/espn-pp-cli/config.toml` Team detail: - `espn-pp-cli teams ` — Schedule for one team (past + upcoming) - `espn-pp-cli teams get ` — Team record, links, and logos - `espn-pp-cli teams list ` — All teams in a league - `espn-pp-cli streak ` — Current win/loss streaks from synced data - `espn-pp-cli rivals ` — Head-to-head records between teams from synced data - `espn-pp-cli h2h --sport --league ` — Deeper detail for one team pair (avg score, meetings) - `espn-pp-cli sos ` — Strength-of-schedule, sorted descending Game detail: - `espn-pp-cli summary --event ` — Full game summary (box score, leaders, scoring plays, odds, win probability) - `espn-pp-cli boxscore ` — Just the box score subtree (sport/league inferred from cache) - `espn-pp-cli plays --event ` — Play-by-play feed (optional `--limit`, default 200) - `espn-pp-cli recap ` — Most recent completed game recap - `espn-pp-cli odds ` — Spread, over/under, moneyline for tonight's slate People: - `espn-pp-cli leaders [--category ]` — Statistical leaders by category - `espn-pp-cli compare --sport --league ` — Side-by-side athlete stats - `espn-pp-cli injuries ` — Active injury report - `espn-pp-cli transactions ` — Recent trades, signings, waivers Polls and rankings: - `espn-pp-cli rankings ` — AP, Coaches, and CFP polls Info: - `espn-pp-cli news ` — Latest news Discovery and local: - `espn-pp-cli search ""` — Full-text search across synced events and news - `espn-pp-cli sync` — Sync a sport+league into local SQLite - `espn-pp-cli sql ""` — Run read-only SQL against the local store - `espn-pp-cli load` — Show workload distribution per assignee (synced data) - `espn-pp-cli orphans` / `stale` — Maintenance views over the local store - `espn-pp-cli doctor` — Verify connectivity and configuration Sport values: `football`, `basketball`, `baseball`, `hockey`, `soccer`. League values: `nfl`, `nba`, `mlb`, `nhl`, `ncaaf`, `ncaam`, `ncaaw`, `mls`, `eng.1` (EPL), `wnba`. ## Recipes ### Morning sports scan ```bash espn-pp-cli today --agent --select events.shortName,events.status espn-pp-cli scores football nfl --agent --select events.shortName,events.competitions.competitors.team.displayName,events.status.type.detail espn-pp-cli standings football nfl --agent ``` One `today` call covers cross-league activity, one `scores` for the league you care about, one `standings` for context. The nested `--select` paths cut a scoreboard payload from tens of KB down to the fields that actually matter — essential for keeping agent context small. ### Pre-game research from synced data ```bash espn-pp-cli sync --sport football --league nfl espn-pp-cli rivals football nfl --agent # historical records from synced data espn-pp-cli streak football nfl --agent # current streaks espn-pp-cli summary football nfl --event --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 ```bash 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: ```bash 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 ```bash 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 --agent # post-game player stats espn-pp-cli plays basketball nba --event --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: ```bash espn-pp-cli --agent --select id,name espn-pp-cli --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 ```bash go install github.com/mvanhorn/printing-press-library/library/media-and-entertainment/espn/cmd/espn-pp-cli@latest espn-pp-cli doctor ``` ### MCP Server ```bash 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`: 1. **Empty, `help`, or `--help`** → run `espn-pp-cli --help` 2. **`install`** → CLI; **`install mcp`** → MCP 3. **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. ```bash # Save the current non-default flags as a named profile espn-pp-cli profile save # Use a profile — overlays its values onto any flag you don't set explicitly espn-pp-cli --profile # List / inspect / remove espn-pp-cli profile list espn-pp-cli profile show espn-pp-cli profile delete --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. ```bash espn-pp-cli --deliver file:/path/to/out.json espn-pp-cli --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. ```bash 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). --- *Source: https://skills.yangsir.net/skill/gh-pp-espn* *Markdown mirror: https://skills.yangsir.net/api/skill/gh-pp-espn/markdown*