rift-tui

A terminal-based League of Legends stats tracker built with Python and Textual. Three-panel dashboard — rank, recent form, champion mastery, match history, top champions, and full per-match breakdowns (runes, spells, items, objectives, gold/XP diff over time) — all live from Riot's API.

Features

• Live profile tracking — rank, LP, recent-form sparkline, champion mastery, last 10 matches, top champions
• Match detail — full scoreboard both teams, bans, objectives, runes, summoner spells, multikill badges, kill participation / damage-per-minute, item builds, and a gold/XP/damage timeline chart per match
• Search any player — region-aware, arrow-key platform picker (no need to know Riot's routing codes)
• Bookmarks — save favorite Riot IDs, jump to them with one keypress
• Multi-account — track a main + smurfs, switch between them
• Compare mode — side-by-side stat comparison against a searched player
• Queue filter — Solo / Flex / ARAM
• Champion filter — filter your match list down to one champion
• In-app settings — manage tracked accounts, bookmarks, refresh interval, and your Riot API key, all without touching a config file
• Copy Riot ID to clipboard — one key, no manual selecting
• Scrollable, resizable panels — Tab to focus a panel, arrow keys or mouse wheel to scroll
• Built-in help overlay — full keybind reference, one key away

Requirements

• Python 3.10+
• A free Riot Developer API key (get one here) — personal dev keys expire every 24h, this is normal Riot behavior, not a bug
• A terminal that properly supports ANSI/VT input. On Windows, use Windows Terminal — legacy cmd.exe and the old PowerShell console host don't handle keyboard input correctly for full-screen terminal apps like this one. If you're on Windows 10 LTSC (no Microsoft Store), grab the portable build from Terminal's GitHub releases, or use WezTerm / Alacritty instead.

Installation

pipx install rift-tui
rift-tui

pipx installs it in its own isolated environment and puts the rift-tui command on your PATH. If you don't have pipx yet:

python -m pip install --user pipx
pipx ensurepath

(restart your terminal after that last command)

From source (for development):

git clone https://github.com/rileriaaa/rift-tui.git
cd rift-tui
pip install -e .

First run

On first launch, rift-tui walks you through setup — no config files to hand-edit:

1. Paste your Riot API key when prompted (or press Esc to skip and add it later with K)
2. Enter your Riot ID (e.g. YourName#TAG) and pick your region with ←/→ (or skip and add it later with A)

That's it — your account and key are saved locally and reused on every future launch.

Keybinds

Where your data lives

Nothing is stored next to the installed package. rift-tui uses your OS's proper per-user data folder (via platformdirs) — e.g. %LOCALAPPDATA%\rift-tui on Windows, ~/.local/share/rift-tui on Linux:

• accounts.json — your tracked accounts
• bookmarks.json — saved players
• app_settings.json — refresh interval and your API key

Troubleshooting

• "Rate limited by Riot API (429)" — personal dev keys are capped at 20 requests/second and 100 requests/2 minutes. Wait a moment and retry.
• "Invalid or expired Riot API key" — dev keys expire every 24 hours. Press K in-app to paste a fresh one, no restart needed.
• "Player not found" — double check the exact Riot ID (name#tag), and try a different region with ←/→ — Riot IDs are region-locked to wherever the account actually plays.
• Keys not responding on Windows — see the terminal note under Requirements above.
• Screen looks broken on a small window — Tab to focus a panel, then scroll it with arrow keys or your mouse wheel.

A note on API keys

This project uses a bring-your-own-key model: each user gets their own free personal Riot API key rather than the app shipping with one baked in. This isn't a limitation — Riot's developer terms explicitly prohibit embedding any API key (personal or production) in software you distribute to others, and personal keys are specifically meant for exactly this kind of individual-use tool.

License

MIT