# tft - TheFantasyTool on the command line `tft` asks TheFantasyTool's predictions about your fantasy team from a terminal or a script: your team, captain picks, the best transfer, a wildcard squad, players and fixtures. - **Read-only.** It can only call TheFantasyTool's tools, and every one of them only reads. - **One file, no dependencies.** Python 3.9 or newer, standard library only. - **Thin.** The commands come from the server: when TheFantasyTool adds a tool, it shows up in `tft` without updating the CLI. - Requires a TheFantasyTool subscription that includes the game you ask about. Without a subscription no data is returned; the FPL plan covers FPL only, Full Access covers every game. Fantasy advice only - predicted points (pP) for fantasy games, never betting advice. ## Install ```bash curl -fsSLO https://thefantasytool.com/cli/tft.py # or download it in a browser python tft.py --help # python3 on macOS/Linux ``` Optional: put it on your PATH as `tft`: ```bash # macOS / Linux chmod +x tft.py && mv tft.py ~/.local/bin/tft ``` ```powershell # Windows (PowerShell): keep tft.py somewhere and add a small wrapper Set-Content "$HOME\bin\tft.cmd" '@python "%USERPROFILE%\bin\tft.py" %*' ``` The examples below write `tft`; use `python tft.py` if you did not install it. ## Quick start ```bash tft login # opens your browser to sign in to TheFantasyTool tft list-games # the games, their exact names, and which your account includes tft my-team --game "Fantasy Premier League 2026/2027" tft captain-options --game "Fantasy Premier League 2026/2027" --scope squad tft best-transfers --game "Fantasy Premier League 2026/2027" --rounds 4 ``` In FPL-style games (Fantasy Premier League, Allsvenskan, Eliteserien and similar) your own team loads automatically once you have saved your team ID under **My Teams** on thefantasytool.com (signed in with the same login). Otherwise pass `--team-id`, or the squad as names with `--squad`. ## Commands Every command has `--help` with examples. Global options work before or after the command: `--json`, `--quiet` / `-q`, `--timeout SECONDS` (default 120), `--mcp-url URL`. ### Built-in commands | Command | What it does | Example | |---|---|---| | `login` | Sign in in your browser (OAuth with PKCE; the answer comes back to a one-shot listener on 127.0.0.1). `--no-browser` prints the sign-in URL instead of opening it (open it in a browser on this same machine). `--device` is device-code sign-in; it only works if the sign-in server enables it (thefantasytool.com does not yet). | `tft login` | | `logout` | Revokes the saved sign-in at TheFantasyTool's sign-in server, then deletes the token file. | `tft logout` | | `status` | Signed in or not, when the sign-in expires, whether the server is reachable, how many tools it has, which games your account includes. Never prints the token. Checking the games uses one of the day's lookups. | `tft status --json` | | `tools` | Lists the server's tools (cached for an hour); `--refresh` asks the server again. | `tft tools --refresh` | | `call` | Raw escape hatch: call any tool with a JSON object of arguments from `--args`, `--args-file` or stdin (`-`). | `tft call best_transfers --args '{"game": "Fantasy Premier League 2026/2027", "rounds": 3}'` | | `mcp-config` | Prints the snippet to connect an AI client straight to the MCP server (see below). | `tft mcp-config cursor` | | `version` | Version and server URL. | `tft version` | ### Tool commands (from the server) These are what the server offers today; `tft tools` shows the live list. Each tool `name_x` is the command `name-x` (the underscore form works too), and each of its inputs is a flag of the same name (`--max-price` or `--max_price`). | Command | What it does | Example | |---|---|---| | `list-games` | The games TheFantasyTool predicts, their exact names and current round, which your account includes, and your saved teams. | `tft list-games` | | `search-players` | Players by name, or a market scan by position / club / max price, with pP per round. | `tft search-players --game "Fantasy Premier League 2026/2027" --position MID --max-price 8 --rounds 3` | | `my-team` | Your own team in an FPL-style game: squad, selling prices, bank, free transfers, pP per round, best XI and captain. | `tft my-team --game "Fantasy Premier League 2026/2027" --rounds 3` | | `captain-options` | Captain candidates per round. `--scope squad` (your team) or `--scope all`. | `tft captain-options --game "Fantasy Premier League 2026/2027" --scope squad` | | `best-transfers` | The single transfers that raise your team's predicted points most. | `tft best-transfers --game "Fantasy Premier League 2026/2027" --position FWD --max-results 3` | | `build-squad` | A full squad (wildcard or fresh) that maximises predicted points. | `tft build-squad --game "Fantasy Premier League 2026/2027" --mode wildcard --rounds 5 --keep Haaland` | | `team-fixtures` | Upcoming fixtures per club with win probability, expected goals and clean-sheet probability. | `tft team-fixtures --game "Fantasy Premier League 2026/2027" --clubs Arsenal --clubs Chelsea` | How flags map to the tool's inputs: | Input type | Flag | |---|---| | text | `--club Arsenal` | | whole number / number | `--rounds 3`, `--max-price 7.5` | | list | repeat the flag or separate with commas: `--avoid "Player A" --avoid "Player B"` or `--avoid "Player A,Player B"` (a value that itself contains a comma: use `tft call`) | | choice | only the listed values: `--scope squad` | | yes/no | `--flag` / `--no-flag` | Required inputs are enforced before anything is sent. ## Output - **Data goes to stdout, everything else (progress, warnings, errors) to stderr.** - Default: a readable rendering - tables for lists, `key: value` otherwise. - `--json`: the tool's result as JSON on stdout - nothing else is written there. On an error, stdout gets `{"error": ..., "hint": ..., "exit_code": ...}` (or, for a tool refusal, the tool's own `{"error": ...}`), so a script always gets valid JSON. - `--quiet`: no progress messages. Errors are still printed. ## Exit codes | Code | Meaning | |---|---| | 0 | ok | | 1 | usage or validation error (a missing or wrong flag, bad JSON), or the server refused the request - the tool's message is printed verbatim, e.g. an unknown game name or a game your account does not include | | 2 | runtime error: network, timeout, rate limit, or a server error | | 3 | not signed in, or the sign-in expired or was revoked - run `tft login` | Ctrl-C exits with 130. ## Sign-in, tokens and security - `tft login` uses OAuth 2.1 with PKCE (S256) against TheFantasyTool's sign-in server. The CLI identifies itself with a public client metadata document, `https://thefantasytool.com/cli/client.json`; there is no client secret. The `state` and the `iss` (issuer) in the browser's answer are checked, and the one-shot listener binds to 127.0.0.1 only and closes after the answer. - If the browser sign-in fails at the authorize step, run `tft login` again. On a remote or headless machine, sign in on your own computer; for CI, pass a token via `TFT_TOKEN`. - The token is stored in your per-user config directory: - Windows: `%APPDATA%\thefantasytool\token.json` - macOS / Linux: `~/.config/thefantasytool/token.json` (or `$XDG_CONFIG_HOME/thefantasytool/`) It is written with permissions `0600` (only you can read it) in a `0700` directory. **On Windows this is best effort**: Python cannot set POSIX permissions there, so the file is protected by your user profile's own permissions. - The CLI never prints, logs or echoes the token. `TFT_DEBUG=1` logs the HTTP traffic with tokens and codes redacted. - When the token expires, the CLI refreshes it once; if that fails you get exit code 3. - The token is only ever sent to the MCP server it was issued for, never over plain `http://` to another machine (`http://` is accepted for `localhost` / `127.0.0.1` only), and never along a redirect. - Rate limits: the server allows a limited number of lookups per user per day. When it answers "too many requests", the CLI waits once (at most 30 seconds, as the server asks) and retries once; then it stops with exit code 2. - **Log out:** `tft logout` revokes the sign-in and deletes the token file. You can also simply delete `token.json`. ### Configuration Precedence: **flags > environment > config file > defaults.** | Setting | Flag | Environment | `config.json` key | |---|---|---|---| | MCP server | `--mcp-url` | `TFT_MCP_URL` | `mcp_url` | | HTTP timeout | `--timeout` | | `timeout` | | Config directory | | `TFT_CONFIG_DIR` | | | Access token for CI | | `TFT_TOKEN` | | `config.json` lives in the config directory. `TFT_TOKEN` is for CI: it overrides the saved sign-in, is never refreshed, and is not touched by `tft logout`. Keep it in your CI's secret store, never in a repository. The config directory also holds `tools.json`, the cached tool list. ## Connect an AI client directly Claude, Cursor and VS Code can use TheFantasyTool's MCP server directly - no CLI needed. They do their own sign-in; your CLI token is never put in a config. `tft mcp-config` prints these: **Claude Code** ```bash claude mcp add --transport http thefantasytool https://thefantasytool.com/api/mcp ``` Then type `/mcp` in Claude Code and sign in. **Claude Desktop / claude.ai** - Settings > Connectors > Add custom connector, name `TheFantasyTool`, URL `https://thefantasytool.com/api/mcp`. **Cursor** - `~/.cursor/mcp.json` (or `.cursor/mcp.json` in a project): ```json { "mcpServers": { "thefantasytool": { "url": "https://thefantasytool.com/api/mcp" } } } ``` **VS Code** - `.vscode/mcp.json`: ```json { "servers": { "thefantasytool": { "type": "http", "url": "https://thefantasytool.com/api/mcp" } } } ``` ## For AI agents `tft` is built to be driven by an agent: stable exit codes, JSON on stdout, logs on stderr, and every command documented in `--help`. Typical workflow: 1. `tft status --json` - check `signed_in`. Exit code 3 means a human must run `tft login` (`tft login`, or `tft login --no-browser` to print the URL); do not try to sign in for them. 2. `tft list-games --json` - get the **exact** game name and check `included_in_account`. `my_teams` shows the manager's saved teams (squad, bank, free transfers) if any. 3. `tft my-team --game "" --json` - the manager's own team with pP per round. 4. Then the question at hand: - captain: `tft captain-options --game "" --scope squad --json` - one transfer: `tft best-transfers --game "" --rounds 4 --json` - wildcard: `tft build-squad --game "" --mode wildcard --json` - a player or position: `tft search-players --game "" --query --json` Pitfalls: - **Use the exact game name from `list-games`.** A vague name is refused with the list of options (exit 1) - read the `error` text and retry with one of them. - **A refusal is not a bug.** Exit 1 with an `error` such as "This TheFantasyTool account does not include predictions for ..." means the account does not cover that game: say so to the user plainly and leave it there. Do not retry it. - **Every number you report must come from a tool result.** Never invent predictions, injuries, prices or rules. pP already includes expected minutes. - **Lookups are capped per day**, and `status` spends one. Cache results within a task instead of calling the same tool repeatedly; never loop on a failing call. - **Exit 2 on 429** means rate limited: wait, do not hammer. - The squad is as of the last deadline; transfers made since are not public until the next deadline. - `best-transfers` covers one transfer and `build-squad` a full wildcard; for multi-week plans and chips, point the user to the Team Planner on thefantasytool.com. - Fantasy advice only: never give betting advice. - `tft call --args ''` reaches a tool with exactly the server's argument names when a flag mapping is awkward (e.g. list values containing commas). - `tft tools --json` returns the full input schemas if you need to know every argument.