--- name: pp-yahoo-fantasy description: "Full Yahoo Fantasy Sports read/write CLI and MCP server — set lineups, execute add/drops and FAAB waiver claims, and run local SQLite league analytics. Trigger phrases: `set my Yahoo fantasy football lineup`, `add and drop a player on Yahoo fantasy`, `check Yahoo fantasy waiver wire upgrades`, `show my Yahoo fantasy matchup and standings`, `use yahoo-fantasy`, `run yahoo-fantasy`." author: "BenHof" license: "Apache-2.0" argument-hint: " [args] | install cli|mcp" allowed-tools: "Read Bash" metadata: openclaw: requires: bins: - yahoo-fantasy-pp-cli install: - kind: go bins: [yahoo-fantasy-pp-cli] module: github.com/mvanhorn/printing-press-library/library/media-and-entertainment/yahoo-fantasy/cmd/yahoo-fantasy-pp-cli --- # Yahoo Fantasy Sports — Printing Press CLI ## Prerequisites: Install the CLI This skill drives the `yahoo-fantasy-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 yahoo-fantasy --cli-only ``` 2. Verify: `yahoo-fantasy-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.10 or newer). This installs into `$GOPATH/bin` (default `$HOME/go/bin`), so add that directory to `$PATH` instead: ```bash go install github.com/mvanhorn/printing-press-library/library/media-and-entertainment/yahoo-fantasy/cmd/yahoo-fantasy-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. Wraps the complete Yahoo Fantasy Sports v2 API for NFL, NBA, MLB, and NHL with automatic XML payload construction for lineup changes (`lineup`) and free-agent/waiver transactions (`add-drop`). Syncs leagues, rosters, matchups, draft results, and transactions into a local SQLite store for instant FTS5 search, all-play power rankings (`power-rankings`), waiver upgrade recommendations (`waiver-wire`), and FAAB bid audits (`faab-audit`). ## When to Use This CLI Use this CLI and MCP server to inspect Yahoo Fantasy Football (and NBA/MLB/NHL) leagues, standings, weekly matchups, rosters, and free agents, as well as to execute starting lineup changes (`lineup`), free-agent pickups, drops, and FAAB waiver claims (`add-drop`). Prefer the compound commands (`lineup`, `add-drop`, `waiver-wire`, `matchup-radar`, `power-rankings`, `faab-audit`, `draft-roi`) over raw endpoint calls. ## Anti-triggers Do not use this CLI for: - Do not use this CLI for Yahoo Finance stock quotes or options chains (use yahoo-finance-pp-cli). - Do not use this CLI for ESPN or Sleeper fantasy leagues. - Do not execute live roster or transaction mutations without previewing via --dry-run when user intent is ambiguous. ## Unique Capabilities ### Roster & Transaction Operations - **`lineup`** — Audit active starting slots for OUT, IR, or BYE players, preview bench swaps, and submit Yahoo XML roster updates. _Use this instead of raw PUT /roster calls when checking for inactive starters or moving players between starting, bench, and IR slots._ ```bash yahoo-fantasy-pp-cli lineup --team 449.l.365083.t.1 --week 9 --set QB=449.p.31862,BN=449.p.30123 --dry-run --agent ``` - **`add-drop`** — Execute or dry-run free-agent adds, drops, atomic add/drops, and FAAB waiver claims with automatic XML payload construction. _Use this to safely preview and submit single adds, drops, or atomic add/drop waiver claims without hand-writing Yahoo XML._ ```bash yahoo-fantasy-pp-cli add-drop --league 449.l.365083 --team 449.l.365083.t.1 --add 449.p.31862 --drop 449.p.30123 --faab 15 --dry-run --agent ``` ### Weekly Matchup & Waiver Intelligence - **`waiver-wire`** — Rank available free agents and waiver players by net points-per-game upgrade over your weakest bench player at each position. _Reach for this before Tuesday waiver runs to find highest-leverage roster upgrades without scanning raw 25-player pages._ ```bash yahoo-fantasy-pp-cli waiver-wire --league 449.l.365083 --team 449.l.365083.t.1 --pos RB --limit 10 --agent ``` - **`matchup-radar`** — Compare both opponents' starting lineups slot-by-slot with projected vs. actual points, remaining starters, and injury flags. _Use this for a complete single-call head-to-head matchup breakdown instead of fetching scoreboard and two team rosters separately._ ```bash yahoo-fantasy-pp-cli matchup-radar --league 449.l.365083 --team 449.l.365083.t.1 --week 9 --agent ``` ### League Analytics & SQLite Intelligence - **`power-rankings`** — Compute every team's true weekly all-play record, schedule luck delta, scoring consistency, and composite power rank. _Use this when evaluating true league contenders and unlucky teams beyond raw win-loss standings._ ```bash yahoo-fantasy-pp-cli power-rankings --league 449.l.365083 --through-week 9 --agent ``` - **`faab-audit`** — Track every manager's remaining FAAB budget, positional spending breakdown, winning bids, and blocking bid thresholds. _Use this before setting a FAAB bid to see exactly how much budget rival managers have left and what they typically bid._ ```bash yahoo-fantasy-pp-cli faab-audit --league 449.l.365083 --agent ``` - **`draft-roi`** — Evaluate snake draft rounds or auction dollar costs against season-to-date fantasy points and current roster retention. _Use this to grade draft performance and identify the highest-surplus steals and biggest busts in the league._ ```bash yahoo-fantasy-pp-cli draft-roi --league 449.l.365083 --agent ``` ## Command Reference **games** — Inspect Yahoo Fantasy game seasons, codes, and stat categories - `yahoo-fantasy-pp-cli games ` — Get Yahoo Fantasy game metadata by game code (nfl, nba, mlb, nhl) or numeric game ID **leagues** — Query Yahoo Fantasy league settings, standings, weekly scoreboards, players, draft results, and transactions - `yahoo-fantasy-pp-cli leagues get` — Get league overview metadata (name, current week, scoring type, season) - `yahoo-fantasy-pp-cli leagues get-draft-results` — Get complete league draft results with round, overall pick, team key, player key, and auction cost - `yahoo-fantasy-pp-cli leagues get-players` — List players in a league filtered by availability status (FA, W, T, A), position, and sort order - `yahoo-fantasy-pp-cli leagues get-scoreboard` — Get weekly league scoreboard and head-to-head matchups with live and projected points - `yahoo-fantasy-pp-cli leagues get-settings` — Get league rules, roster position slots, stat categories, point modifiers, and FAAB settings - `yahoo-fantasy-pp-cli leagues get-standings` — Get league standings ordered by rank with win-loss-tie records, points for/against, and streak - `yahoo-fantasy-pp-cli leagues get-teams` — List all teams in a league with manager profiles, waiver priority, and remaining FAAB budget - `yahoo-fantasy-pp-cli leagues get-transactions` — Get league transaction activity log filtered by transaction types (add, drop, trade, commish) **players** — Look up Yahoo Fantasy player profiles, weekly/season statistics, percent owned, and league ownership - `yahoo-fantasy-pp-cli players get-ownership` — Get league-specific ownership status (free agent, waivers, or owning fantasy team) for players - `yahoo-fantasy-pp-cli players get-percent-owned` — Get Yahoo-wide ownership percentage and week-over-week delta for one or more players - `yahoo-fantasy-pp-cli players get-stats` — Get player statistics for one or more player keys in a league by week or season - `yahoo-fantasy-pp-cli players search` — Search players by name within a league and return their profile and season stats **teams** — Inspect fantasy teams, weekly rosters, head-to-head matchups, and update starting lineups - `yahoo-fantasy-pp-cli teams get` — Get fantasy team details including manager, waiver priority, FAAB balance, and logos - `yahoo-fantasy-pp-cli teams get-matchups` — Get head-to-head matchups and projected/actual scores for a team across one or more weeks - `yahoo-fantasy-pp-cli teams get-roster` — Get a team's active and bench roster for a specific NFL week - `yahoo-fantasy-pp-cli teams update-roster` — Update a team's starting lineup and bench positions for a given week or date **transactions** — Execute and manage league transactions including free-agent adds, drops, atomic add/drops, FAAB waiver claims, and trades - `yahoo-fantasy-pp-cli transactions cancel` — Cancel a pending waiver claim or proposed trade before it processes - `yahoo-fantasy-pp-cli transactions create` — Submit an add, drop, atomic add/drop, waiver claim (with optional FAAB bid), or trade proposal - `yahoo-fantasy-pp-cli transactions get` — Get details of a specific transaction, waiver claim, or pending trade by transaction key - `yahoo-fantasy-pp-cli transactions update` — Edit a pending waiver claim (FAAB bid or priority) or accept/reject a pending trade proposal **users** — List leagues and teams belonging to the authenticated Yahoo user - `yahoo-fantasy-pp-cli users get-leagues` — List all Yahoo Fantasy leagues for the authenticated user filtered by sport code - `yahoo-fantasy-pp-cli users get-teams` — List all fantasy teams owned by the authenticated Yahoo user across seasons **add-drop** - `yahoo-fantasy-pp-cli add-drop` — Execute or dry-run free-agent adds, drops, atomic add/drops, and FAAB waiver claims with automatic XML payload construction. **draft-roi** - `yahoo-fantasy-pp-cli draft-roi` — Evaluate snake draft rounds or auction dollar costs against season-to-date fantasy points and current roster retention. **faab-audit** - `yahoo-fantasy-pp-cli faab-audit` — Track every manager's remaining FAAB budget, positional spending breakdown, winning bids, and blocking bid thresholds. **lineup** - `yahoo-fantasy-pp-cli lineup` — Audit active starting slots for OUT, IR, or BYE players, preview bench swaps, and submit Yahoo XML roster updates. **matchup-radar** - `yahoo-fantasy-pp-cli matchup-radar` — Compare both opponents' starting lineups slot-by-slot with projected vs. actual points, remaining starters, and injury flags. **power-rankings** - `yahoo-fantasy-pp-cli power-rankings` — Compute every team's true weekly all-play record, schedule luck delta, scoring consistency, and composite power rank. **waiver-wire** - `yahoo-fantasy-pp-cli waiver-wire` — Rank available free agents and waiver players by net points-per-game upgrade over your weakest bench player at each position. ### Finding the right command When you know what you want to do but not which command does it, ask the CLI directly: ```bash yahoo-fantasy-pp-cli which "" ``` `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. `--json` (and other machine formats) keep that exit-2 contract and write `{"matches":[]}` on stdout so agents can inspect the envelope without treating a miss as success. ## Recipes ### Preview and apply a Sunday morning lineup swap ```bash yahoo-fantasy-pp-cli lineup --team 449.l.365083.t.1 --week 9 --set QB=449.p.31862,BN=449.p.30123 --dry-run --agent ``` Validates positional eligibility and previews the XML roster payload before updating your starting lineup. ### Submit an atomic add/drop waiver claim with FAAB ```bash yahoo-fantasy-pp-cli add-drop --league 449.l.365083 --team 449.l.365083.t.1 --add 449.p.31862 --drop 449.p.30123 --faab 15 --dry-run --agent ``` Constructs Yahoo's XML for an atomic add/drop with a $15 FAAB bid. ### Find top RB waiver upgrades over your bench ```bash yahoo-fantasy-pp-cli waiver-wire --league 449.l.365083 --team 449.l.365083.t.1 --pos RB --limit 5 --agent --select upgrades.add_player_name,upgrades.percent_owned,upgrades.net_upgrade_ppg ``` Compares available free agents and waiver RBs against your lowest-scoring bench RB and filters to key decision fields. ### Audit league FAAB budgets before Tuesday waivers ```bash yahoo-fantasy-pp-cli faab-audit --league 449.l.365083 --agent ``` Shows every manager's remaining FAAB balance, total spent by position, and blocking bid thresholds. ## Auth Setup Set `YAHOO_ACCESS_TOKEN` (or `YAHOO_FANTASY_TOKEN`) with a Yahoo OAuth 2.0 Bearer token, or configure `YAHOO_CLIENT_ID`, `YAHOO_CLIENT_SECRET`, and `YAHOO_REFRESH_TOKEN` so the CLI can automatically refresh expired access tokens against `https://api.login.yahoo.com/oauth2/get_token`. Run `yahoo-fantasy-pp-cli doctor` to verify setup. ## Agent Mode Add `--agent` to any command. Expands to: `--json --compact --no-input --no-color`. Global format flags share one contract on promoted, novel, sync, and `--deliver` paths: - `--json` — one JSON document on stdout (sync progress events go to stderr) - `--compact` — keep identity/status/timestamp fields; does not change the document vs stream shape - `--csv` / `--plain` — tabular rows (collection envelopes unwrap to the row array). `--csv` prefixes `'` on a cell or header key that starts with `=`, `+`, `-`, `@`, tab, CR, or LF (fullwidth `＝＋－＠` too) so a spreadsheet does not run it as a formula; a plain signed number such as `-5` or `+2.5e3` is unchanged. - `--quiet` — one identity value per row, no envelope - **Pipeable** — JSON on stdout, errors on stderr - **Filterable** — `--select` keeps a subset of fields. Dotted paths descend into nested structures; arrays traverse element-wise. Critical for keeping context small on verbose APIs: ```bash yahoo-fantasy-pp-cli games mock-value --agent --select game_key,game_id,name ``` - **Previewable** — `--dry-run` shows the request without sending. A completed dry run exits 0 with `"success": true` and `"dry_run": true` and no HTTP `status`; validation failures still exit non-zero with `"success": false`. - **Offline-friendly** — sync/search commands can use the local SQLite store when available - **Non-interactive** — never prompts, every input is a flag - **Explicit confirmation** — `--agent` does not imply `--yes`; pass `--yes` separately only after the target, arguments, and side effects are clear - **Explicit retries** — use `--idempotent` only when an already-existing create should count as success, and use `--ignore-missing` only when a missing delete target should count as success ### Response envelope Commands that read from the local store or the API wrap output in a provenance envelope: ```json { "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."}, "results": } ``` Parse `.results` for data and `.meta.source` to know whether it's live or local. A human-readable `N results (live)` summary is printed to stderr only when stdout is a terminal AND no machine-format flag (`--json`, `--csv`, `--compact`, `--quiet`, `--plain`, `--select`) is set — piped/agent consumers and explicit-format runs get pure JSON on stdout. ## Paths and state Agents should treat the CLI's path resolver as part of the runtime contract: - Use `--home ` for one invocation, or set `YAHOO_FANTASY_HOME=` to relocate all four path kinds under one root. - Use per-kind env vars only when a specific kind must diverge: `YAHOO_FANTASY_CONFIG_DIR`, `YAHOO_FANTASY_DATA_DIR`, `YAHOO_FANTASY_STATE_DIR`, `YAHOO_FANTASY_CACHE_DIR`. - Resolution order is per-kind env var, `--home`, `YAHOO_FANTASY_HOME`, XDG (`XDG_CONFIG_HOME`, `XDG_DATA_HOME`, `XDG_STATE_HOME`, `XDG_CACHE_HOME`), then platform defaults. - `config` contains settings like `config.toml` and profiles. `data` contains `credentials.toml`, `data.db`, cookies, and auth sidecars. `state` contains persisted queries, jobs, and `teach.log`. `cache` contains regenerable HTTP/cache files. - Stored secrets live in `credentials.toml` under the data dir. Existing legacy `config.toml` secrets are read for compatibility and leave `config.toml` on the first auth write. - Run `yahoo-fantasy-pp-cli doctor --fail-on warn` to surface path and credential-location warnings. `agent-context` exposes a schema v4 `paths` block for agents that need the resolved dirs. - For MCP, pass relocation through the MCP host config. The MCP binary does not inherit CLI flags: ```json { "mcpServers": { "yahoo-fantasy": { "command": "yahoo-fantasy-pp-mcp", "env": { "YAHOO_FANTASY_HOME": "/srv/yahoo-fantasy" } } } } ``` Fleet precedence: an inherited per-kind env var overrides an explicit `--home` for that kind. Use `YAHOO_FANTASY_HOME` or per-kind vars as durable fleet levers, and use `--home` only for a single invocation. Relocation is not reversible by unsetting env vars; move files manually before clearing `YAHOO_FANTASY_HOME`, or `doctor` will not find credentials left under the former root. Local data is unencrypted and relies on OS account permissions plus disk encryption. Reads in the default `--data-source auto` mode are written to the SQLite store; GET responses are cached for five minutes under the cache dir. `local-data purge` previews what it would erase (store files, response cache, learn journal) and deletes only with `--yes`; it is not exposed over MCP. `YAHOO_FANTASY_NO_LOCAL_DATA=1` disables the response cache and store writes, turns `auto` reads into live reads, and blocks `sync` and `workflow archive`; `--data-source local` still reads an existing store, and `YAHOO_FANTASY_DATA_SOURCE` sets the `--data-source` default. ## Automatic learning This CLI ships a self-capturing learning loop. The CLI does its own bookkeeping: every invocation is journaled locally, a failed flag followed by a corrected retry auto-derives a `flag_alias` candidate, and a `teach` on a query family without a playbook auto-synthesizes a `playbook_candidate` from the session's journal. Your job is judgment only: `recall` first, act on surfaced candidates, `teach` the final answer, `playbook amend` when you observe a correction. You never record failures by hand. ### Step 1: `recall` before any discovery Before list/search/drill commands on a new user question, pass the question as an argv or MCP tool argument to `recall --agent`. Do not interpolate user-controlled text into a shell command line. Quoted `recall ""` breaks on an apostrophe, which is ordinary English. A quoted heredoc breaks when a body line equals the delimiter, and that delimiter is published in these docs. Write the question with a non-shell file-writing tool, then read it back as data: ```bash # Write the question verbatim with your file-writing tool (no shell involved). # Command substitution on a file only ever yields data — the shell never # parses the file's bytes as syntax. QUERY=$(cat /path/to/question.txt) yahoo-fantasy-pp-cli recall "$QUERY" --agent ``` Prefer MCP: pass the question as the tool's query argument. `"$QUERY"` after a file read is argv-safe; putting the question itself in the command text is not. The response envelope: ```json { "query": "...", "normalized