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.
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).
Authentication
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.
Quick Start
# Verify CLI configuration and reachability
yahoo-fantasy-pp-cli doctor --dry-run
# List your Yahoo Fantasy NFL leagues and league keys
yahoo-fantasy-pp-cli users get-leagues nfl --agent
# Inspect your team's week 9 starting lineup and bench
yahoo-fantasy-pp-cli teams get-roster 449.l.365083.t.1 9 --agent
# Preview a starting lineup slot swap before sending the XML PUT request
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
# Preview an atomic add/drop waiver claim with a $15 FAAB bid
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
Unique Features
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.
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.
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.
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.
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.
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.
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.
yahoo-fantasy-pp-cli draft-roi --league 449.l.365083 --agent
Recipes
Preview and apply a Sunday morning lineup swap
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
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 <fantasy_content> XML for an atomic add/drop with a $15 FAAB bid.
Find top RB waiver upgrades over your bench
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
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.
Usage
Run yahoo-fantasy-pp-cli --help for the full command reference and flag list.
Paths & environment variables
This CLI separates local files into four path kinds:
| Kind | Contents |
|---|
config | User-editable settings such as config.toml and saved profiles |
data | Durable local data: credentials.toml, data.db, cookies, browser-session proof files, and other auth sidecars |
state | Runtime state such as persisted queries, jobs, and teach.log |
cache | Regenerable HTTP/cache files |
Each kind resolves independently. The ladder is:
- Per-kind env var:
YAHOO_FANTASY_CONFIG_DIR, YAHOO_FANTASY_DATA_DIR, YAHOO_FANTASY_STATE_DIR, or YAHOO_FANTASY_CACHE_DIR
--home <dir> for this invocationYAHOO_FANTASY_HOME for a flat relocated root- XDG env vars:
XDG_CONFIG_HOME, XDG_DATA_HOME, XDG_STATE_HOME, XDG_CACHE_HOME
- Platform defaults matching existing installs
For containers and agent sandboxes, prefer a single relocated root:
export YAHOO_FANTASY_HOME=/srv/yahoo-fantasy
yahoo-fantasy-pp-cli doctor
Under YAHOO_FANTASY_HOME=/srv/yahoo-fantasy, the four dirs resolve to /srv/yahoo-fantasy/config, /srv/yahoo-fantasy/data, /srv/yahoo-fantasy/state, and /srv/yahoo-fantasy/cache.
On Windows, set the same variable in PowerShell:
$env:YAHOO_FANTASY_HOME = "C:\srv\yahoo-fantasy"
yahoo-fantasy-pp-cli doctor
Under $env:YAHOO_FANTASY_HOME = "C:\srv\yahoo-fantasy", the four dirs resolve to C:\srv\yahoo-fantasy\config, C:\srv\yahoo-fantasy\data, C:\srv\yahoo-fantasy\state, and C:\srv\yahoo-fantasy\cache.
MCP servers do not receive CLI flags from the host. Put relocation in the host env block:
{
"mcpServers": {
"yahoo-fantasy": {
"command": "yahoo-fantasy-pp-mcp",
"env": {
"YAHOO_FANTASY_HOME": "/srv/yahoo-fantasy"
}
}
}
}
Precedence matters in fleets: an ambient per-kind variable such as YAHOO_FANTASY_DATA_DIR overrides an explicit --home for that kind. Use YAHOO_FANTASY_HOME or the per-kind variables for durable fleet relocation; treat --home as the weaker per-invocation lever.
Relocation is one-way. Unsetting YAHOO_FANTASY_HOME does not move files back to platform defaults, and doctor cannot find credentials left under a former root. Move the files manually before unsetting relocation variables.
Existing installs keep working because the platform-default rung matches the legacy layout. On the first auth write, stored secrets leave config.toml and are consolidated into credentials.toml under the data directory. Run yahoo-fantasy-pp-cli doctor --fail-on warn to check path and credential-location warnings in automation.
Local data
Reads are saved locally by default: in --data-source auto mode every successful read is also written to the SQLite store (data.db, or data-<hash>.db per credential) in the data directory. GET responses are cached for five minutes under http/ in the cache directory. Credentials live in credentials.toml in the data directory. The learn journal lives under learn/ in the state directory. yahoo-fantasy-pp-cli doctor prints the resolved paths, every store file, and the response-cache size.
None of it is encrypted. New files are created owner-only; beyond that the data relies on OS account permissions and full-disk encryption (FileVault, BitLocker, LUKS).
- Erase it:
yahoo-fantasy-pp-cli local-data purge lists the store files, response cache, and learn journal it would delete; add --yes to delete them, or --only store|cache|journal to narrow it. Config and credentials are kept.
- Run without a local copy: set
YAHOO_FANTASY_NO_LOCAL_DATA=1. Reads go to the API (--data-source live; --data-source local still reads an existing store), the response cache is off (--no-cache), nothing new is written to the store, and sync and workflow archive refuse to run. Set it in an MCP host's env block and every command the server runs inherits it.
- Choose the read source without flags:
YAHOO_FANTASY_DATA_SOURCE=auto|live|local sets the --data-source default; an explicit flag wins.
Commands
games
Inspect Yahoo Fantasy game seasons, codes, and stat categories
yahoo-fantasy-pp-cli games <game_key> - 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 costyahoo-fantasy-pp-cli leagues get-players - List players in a league filtered by availability status (FA, W, T, A), position, and sort orderyahoo-fantasy-pp-cli leagues get-scoreboard - Get weekly league scoreboard and head-to-head matchups with live and projected pointsyahoo-fantasy-pp-cli leagues get-settings - Get league rules, roster position slots, stat categories, point modifiers, and FAAB settingsyahoo-fantasy-pp-cli leagues get-standings - Get league standings ordered by rank with win-loss-tie records, points for/against, and streakyahoo-fantasy-pp-cli leagues get-teams - List all teams in a league with manager profiles, waiver priority, and remaining FAAB budgetyahoo-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 playersyahoo-fantasy-pp-cli players get-percent-owned - Get Yahoo-wide ownership percentage and week-over-week delta for one or more playersyahoo-fantasy-pp-cli players get-stats - Get player statistics for one or more player keys in a league by week or seasonyahoo-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 logosyahoo-fantasy-pp-cli teams get-matchups - Get head-to-head matchups and projected/actual scores for a team across one or more weeksyahoo-fantasy-pp-cli teams get-roster - Get a team's active and bench roster for a specific NFL weekyahoo-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 processesyahoo-fantasy-pp-cli transactions create - Submit an add, drop, atomic add/drop, waiver claim (with optional FAAB bid), or trade proposalyahoo-fantasy-pp-cli transactions get - Get details of a specific transaction, waiver claim, or pending trade by transaction keyyahoo-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 codeyahoo-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.
Self-learning loop
This CLI caches per-question discovery so repeat queries skip the walk and structurally similar queries get answered via entity substitution. The loop also self-captures: every invocation is journaled locally, and failed-flag corrections plus fresh teaches surface as candidates on the next recall for confirm/reject judgment. Agents call recall before discovery and fire teach & after answering. See the ## Automatic learning section in SKILL.md for the full protocol.
yahoo-fantasy-pp-cli recall <query> - Look up cached resources for a query before running discoveryyahoo-fantasy-pp-cli teach - Record a query -> resource mapping (silent on success, safe to background with &)yahoo-fantasy-pp-cli learnings list - Inspect taught rowsyahoo-fantasy-pp-cli learnings forget <query> - Undo a teachyahoo-fantasy-pp-cli learnings candidates - List auto-captured candidates awaiting confirm/rejectyahoo-fantasy-pp-cli learnings stats - Local loop metrics: recall hit rate, teach-to-reuse, playbook resolution, candidate countsyahoo-fantasy-pp-cli teach-pattern - Install a query/resource template up frontyahoo-fantasy-pp-cli teach-lookup - Add an entity mapping (e.g. country code, team alias) for pattern substitution
Pass --no-learn or set YAHOO_FANTASY_NO_LEARN=true to disable the loop for deterministic flows.
The local store's schema version stamp is one-way: once this version of yahoo-fantasy-pp-cli opens the database, older binaries refuse it with a version error — upgrade the binary rather than downgrading.
Output Formats
# Human-readable table (default in terminal, JSON when piped)
yahoo-fantasy-pp-cli games mock-value
# JSON for scripting and agents
yahoo-fantasy-pp-cli games mock-value --json
# Filter to specific fields
yahoo-fantasy-pp-cli games mock-value --json --select game_key,game_id,name
# Dry run — show the request without sending
yahoo-fantasy-pp-cli games mock-value --dry-run
# Agent mode — JSON + compact + no prompts in one flag
yahoo-fantasy-pp-cli games mock-value --agent
--csv prefixes a leading ' on cells and header keys that start with =, +, -, @, a tab, or a line break (including fullwidth ＝＋－＠) so a spreadsheet does not run them as formulas. Plain signed numbers such as -5 and +2.5e3 are left unchanged.
Agent Usage
This CLI is designed for AI agent consumption:
- Non-interactive - never prompts, every input is a flag
- Pipeable -
--json output to stdout, errors to stderr
- Filterable -
--select <field>[,<field>...] returns only fields you need
- Previewable -
--dry-run shows the request without sending
- Explicit retries - add
--idempotent to create retries and add --ignore-missing to delete retries when a no-op success is acceptable
- Explicit confirmation -
--agent does not imply --yes; pass --yes separately only after the target, arguments, and side effects are clear
- Piped input - write commands can accept structured input when their help lists
--stdin
- Offline-friendly - sync/search commands can use the local SQLite store when available
- Agent-safe by default - no colors or formatting unless
--human-friendly is set
Exit codes: 0 success, 2 usage error, 3 not found, 4 auth error, 5 API error, 6 partial failure, 7 rate limited, 10 config error.
Health Check
yahoo-fantasy-pp-cli doctor
Verifies configuration, credentials, and connectivity to the API.
Configuration
Run yahoo-fantasy-pp-cli doctor to see the resolved config, data, state, and cache directories. The platform-default config path is ~/.config/yahoo-fantasy-pp-cli/config.toml on macOS/Linux and %USERPROFILE%\.config\yahoo-fantasy-pp-cli\config.toml on Windows; --home, YAHOO_FANTASY_HOME, and per-kind env vars can relocate it.
Static request headers can be configured under headers; per-command header overrides take precedence.
--ca-cert, YAHOO_FANTASY_CA_CERT, or ca_cert adds a PEM CA bundle to the system trust roots. --tls-server-name, YAHOO_FANTASY_TLS_SERVER_NAME, or tls_server_name is the name checked against the certificate when the dialed address does not match it. Precedence is flag, then environment, then the config file. A config file other users can change does not supply these settings. Certificate verification failures are not retried.
Environment variables:
| Name | Kind | Required | Description |
|---|
YAHOO_ACCESS_TOKEN | per_call | Yes | Set to your API credential. |
YAHOO_FANTASY_TOKEN | per_call | Yes | Set to your API credential. |
agentcookie (optional)
If you use agentcookie to sync secrets across machines, this CLI auto-adopts agentcookie-managed credentials with no extra setup. When the daemon writes to this CLI's config, yahoo-fantasy-pp-cli doctor reports agentcookie: detected and auth-status labels the source as agentcookie. Skip this section if you don't use agentcookie - the CLI works the same as any other.
Troubleshooting
Authentication errors (exit code 4)
- Run
yahoo-fantasy-pp-cli doctor to check credentials
- Verify the environment variable is set:
echo $YAHOO_ACCESS_TOKEN
Not found errors (exit code 3)
- Check the resource ID is correct
- Run the
list command to see available items
API-specific
- 401 Unauthorized: token_expired or unable_to_determine_oauth_type — Refresh your Yahoo OAuth2 Bearer token or set YAHOO_CLIENT_ID, YAHOO_CLIENT_SECRET, and YAHOO_REFRESH_TOKEN for automatic token refresh.
- 400 Bad Request when changing lineup or adding/dropping a player — Run
lineup --dry-run or add-drop --dry-run first to verify player keys ({game_id}.p.{player_id}) and positional eligibility (QB, RB, WR, TE, W/R/T, BN, IR).
- Rate limit (HTTP 429 / 999) during multi-week scoreboard or player queries — Run
yahoo-fantasy-pp-cli sync --full to cache league data in local SQLite, then pass --data-source local to analytical commands.
Sources & Inspiration
This CLI was built by studying these projects and resources:
Generated by CLI Printing Press