fpl-cli

Fantasy Premier League analysis from the terminal. Classic and Draft formats. Six data sources, one interface.

Example output from fpl player — real-time player analysis with form, xGI and availability flags.

Features

• Multi-source data - FPL API, Draft API, Understat (npxG/xGChain), historical data (vaastav 2022-25 + Core-Insights 2025-26), and football-data.org in one place.
• Player scouting - Filter by any stat, track xG trends, spot underperformers, check fixture runs.
• Fixture intelligence - Bayesian difficulty ratings from actual match results, blank/double GW detection, squad exposure analysis.
• Custom analysis - Captain picks, transfer targets, differentials, waivers, and ILP-optimal squad allocation. Opt-in, off by default.
• Gameweek reports - Post-GW reviews and league recaps with optional LLM narrative.
• Draft parity - Most commands work for both Classic and Draft. Waivers cover the free-agent wire.
• Agent-friendly - --format json with a consistent envelope on key commands. Ready-made agent skills in .agents/skills/.

Quickstart

$ pipx install fplkit
$ fpl init
$ fpl status
$ fpl stats -p MID -s form --available-only

fpl init configures your FPL IDs and optional features. With just an entry ID you get the full data toolkit.

Installation

Requires Python 3.11+.

$ pipx install fplkit

Alternatives: uv pip install fplkit or pip install fplkit.

[!NOTE] Browser scraping (fpl squad sell-prices --refresh) requires the scraper extra and Playwright:

$ pipx install 'fplkit[scraper]'
$ playwright install chromium

Usage

After the Gameweek

$ fpl status                       # GW result, deadline, rank movement, flagged players
$ fpl review --save --summarise    # Full review with LLM narrative
$ fpl league                       # Live league standings
$ fpl league-recap                 # Awards, standings movement, and running streaks
$ fpl league-recap --summarise     # Add the LLM editorial for the group chat

Checking Your Setup

$ fpl doctor                       # Verify configured IDs and data files - essential after a season rollover

Every ID in settings.yaml is resolved against the live API and the team/league name reported back, so a dead or recycled ID (which otherwise fails silently) is visible. Per-team data files are checked against the current season's clubs. Exits non-zero when something needs fixing.

Scouting Players

$ fpl stats -p FWD -s form -a             # Forwards by form, excluding unavailable
$ fpl player Rice -f -u                   # Deep dive: fixtures + Understat analysis
$ fpl xg                                  # xG/xA analysis, over/underperformers
$ fpl history                             # Career arc across 3 seasons
$ fpl price-history -n 4 -s price_slope   # Bandwagon detection

Before the Deadline

$ fpl squad                        # Squad health: form, injuries, recommendations
$ fpl squad grid -n 8 -w Mbeumo    # 8-GW fixture difficulty grid with a watchlist player
$ fpl fdr --my-squad               # Your squad's blank/double GW exposure
$ fpl preview --save --scout       # Full analysis + BUY/SELL research via LLM

Strategic Planning

$ fpl fdr --blanks                 # Confirmed + predicted blank/double GWs
$ fpl chips timing                 # Rule-based Free Hit / Bench Boost / Triple Captain signals
$ fpl fixtures                     # Next GW fixtures with FDR

Season Preview Intel

Optional. Notes you write up per team before the season — projected XIs, long-term injuries, new signings with no Premier League record — from whatever source you read. Nothing ships with the tool; the previews are yours.

$ fpl intel schema                 # The file format, every field explained
$ fpl intel init                   # Scaffold one empty file per team
$ fpl intel resolve ARS --write    # Match player names to FPL codes, save them
$ fpl intel                        # Coverage across the league, and what it permits
$ fpl intel show ARS               # One team's intel, aged to the current gameweek

Intel expires on a schedule (fpl intel --show-decay prints it): each section is aged out at the point where real data supersedes it — API news for injuries, actual minutes for projected XIs. There is no in-season upkeep, and squad-builder and gw-prep read it automatically when present.

Custom Analysis

Off by default. Enable via fpl init or custom_analysis: true in settings.yaml.

$ fpl captain                      # Ranked captain picks (0-100 matchup scoring)
$ fpl targets --min-own 30         # Transfer targets, template tier
$ fpl differentials -t 3           # Ultra-differentials (<3% owned)
$ fpl waivers                      # Free-agent waiver picks with drop suggestions (draft)
$ fpl transfer-eval --out Palmer --in "Salah,Mbeumo"  # Side-by-side comparison
$ fpl allocate --horizon 1         # Free Hit: optimal squad for a single GW
$ fpl ratings                      # Bayesian team strength ratings from match results

Enabling custom analysis also enriches other commands: fpl stats gains --value columns, fpl xg adds Value Picks, fpl fdr upgrades to Bayesian FDR with ATK/DEF split.

JSON Output

Commands with --format json emit a consistent envelope:

{
  "command": "stats",
  "metadata": {"gameweek": null, "format": "classic", "custom_analysis": true},
  "data": [...]
}

$ fpl stats --format json -p MID -s expected_goal_involvements
$ fpl status --format json
$ fpl fdr --blanks --format json
$ fpl league-recap --format json

Configuration

Run fpl init to configure interactively. Settings stored in your platform's config directory (override with FPL_CLI_CONFIG_DIR, and also home to the optional previews/ intel files); generated data such as team ratings, chip plans and the league history ledger league-recap builds up is stored in your platform's data directory (override with FPL_CLI_DATA_DIR). In ephemeral environments (e.g. Claude Code on the web), point both at a persistent workspace. Both overrides must be absolute paths — see Directories. Saved reports (--save, --output) are written to a season subdirectory — <output_dir>/2026-27/gw21-review.md — so a new season never overwrites the last one's files; see Report layout.

Required: FPL classic entry ID or draft league + entry IDs.

# LLM providers (for --summarise and --scout)
export PERPLEXITY_API_KEY="your-key"    # Research role
export ANTHROPIC_API_KEY="your-key"     # Synthesis role

See Command Reference for the full settings.yaml schema and LLM provider setup.

Development

$ git clone https://github.com/rossgroomio/fpl-cli.git
$ cd fpl-cli
$ python3 -m venv .venv && source .venv/bin/activate
$ pip install -e ".[dev]"
$ fpl init

$ ruff check fpl_cli/    # Lint
$ pyright fpl_cli/       # Type check
$ pytest tests/          # Tests

[!NOTE] Football data provided by the Football-Data.org API. Player and fixture data is property of the Premier League. Expected goals data is property of Understat. Historical data from vaastav/Fantasy-Premier-League (MIT, 2022-25) and olbauday/FPL-Core-Insights (2025-26+). This tool fetches data at runtime and does not redistribute third-party data.

[!WARNING] Browser scraping (fpl squad sell-prices) uses your FPL login to read sell prices. Automated access may violate FPL website terms - use at your own risk.

Command Reference | Custom Analysis Guide | Architecture | Agent Tools & Skills | Contributing