lol-live

Real-time text commentary CLI for LoL esports. A terminal HUD streams kills, towers, dragons, barons, and gold as they happen. Powered by the unofficial lolesports API — zero dependencies (Node built-ins only).

🇰🇷 한국어 문서 바로가기 →

Run (no install)

npx lol-live                 # auto-detect a live match → start commentary
npx lol-live --list          # live / recently ended / upcoming matches
npx lol-live --replay <gameId>

Global install

npm install -g lol-live
lol-live

Usage

lol-live                     auto-detect a live match and start commentary
lol-live --list              list live / upcoming / recently ended matches
lol-live --match-id <id>     commentate the in-progress game of a match (BoN)
lol-live --game-id <id>      commentate a specific game feed directly
lol-live --replay <gameId>   replay a finished game from the start

Options

| Option | Description | |--------|-------------| | --locale <hl> | display language (default ko-KR) | | --interval <sec> | live polling interval in seconds (default 10) | | --speed <n> | replay speed multiplier (default 1 ≈ 17x) | | --replay-step <sec> | game-seconds advanced per replay tick (default 20) | | --no-history | skip past-history restore on live connect (fast start) | | --history-step <sec> | history restore stride in seconds (default 30) | | --no-cache | disable local caching of past window frames | | --no-gui | log only, no scoreboard (for pipes / log capture) | | --nerd \| --emoji \| --ascii | icon theme (default nerd = needs a Nerd Font) |

Controls (GUI)

↑↓ scroll · PageUp/PageDn (Space) · Home/End (g/G latest) · q·Ctrl+C quit

Local cache

Past window frames (immutable data) are cached locally, so replaying the same game or restoring history after a reconnect works instantly without re-downloading. Enabled by default; turn off with --no-cache. Only the 20 most recently accessed games are kept — older ones are pruned automatically.

Cache location:

• macOS: ~/Library/Caches/lol-live
• Linux: $XDG_CACHE_HOME/lol-live (default ~/.cache/lol-live)
• Windows: %LOCALAPPDATA%\lol-live\Cache

Override the location with the LOL_LIVE_CACHE_DIR environment variable.

Features

• Every poll diffs the latest cumulative frame against the previous one and turns kill / objective / gold changes into commentary events
• Joining mid-broadcast restores the full history from game start automatically
• Uses the terminal's alternate screen buffer — no scrollback pollution on exit
• Layout auto-condenses to the terminal size; Nerd Font / emoji / ASCII themes

If Nerd Font glyphs render as □, use --emoji or --ascii.

Disclaimer

This is an unofficial fan project. It is not affiliated with, endorsed, or sponsored by Riot Games. It relies on an undocumented public API used by the official lolesports website, which may change or stop working at any time. League of Legends and all related assets are trademarks of Riot Games, Inc.

License

MIT