⚽ soccer-cli

Live football scores, ball-by-ball commentary, and an animated ASCII pitch that simulates the run of play — right in your terminal. Built for the 2026 World Cup, works for every major league. No API key required.

⚽ FIFA WORLD CUP 2026                        ● 1 LIVE   3 matches · ⟳15s
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  MATCHES
  ▸ 🇫🇷 France          2-1   England 🏴         ● 67'                     ← selected row is highlighted
    🇧🇷 Brazil           v    Germany 🇩🇪         Thu 8:00 PM
    🇦🇷 Argentina       3-0   Japan 🇯🇵           FT

  🇫🇷 France                  ● 67'                       England 🏴
                          ▀▀█      ▀█
                          █▀▀ ▀▀▀   █                                     ← big block-digit score
                          ▀▀▀       ▀
  ⚽ 23' Mbappé (P) · 38' Bellingham · 66' Mbappé
  0' ────────⚽──────⚽───┃───▮──────⚽──────── 90'                        ← match timeline
  Possession   58% ███████████████████░░░░░░░░░░░░░░ 42%
  Shots         14 ████████████████▏██████████▎░░░░░ 9                    ← duel bars
  ╭────────────────────────────────────────────────────────╮
  │ ·····┆     ◖◗       ┆    ◖◗        ◖◗    ┆····· │
  │▐     ┆  ◖◗    ◖◗    ┆ ◖◗  ◖◗ ◖◗         ◖◗┆     ▌│              ← 22 players, big & easy to track
  │▐ ▐▌  ┆     ◖◗   (  •  ◖◗○)      ◖◗  ◖◗ ◖◗ ┆ ▐▌  ▌│              ← keepers (▐▌) hold their line
  │▐     ┆  ◖◗    ◖◗    ┆ ◖◗  ◖◗            ◖◗┆     ▌│              ← the ○ ball pulses on the play
  │ ·····┆     ◖◗       ┆    ◖◗        ◖◗    ┆····· │
  ╰────────────────────────────────────────────────────────╯
   ● France →    ← England ●     live sim · synced 2s ago

Install

npm install -g soccer-cli
soccer

…or run it without installing:

npx soccer-cli

Usage

soccer                      # FIFA World Cup (default)
soccer --league eng.1       # Premier League
soccer --date 20260611      # a specific day's fixtures
soccer --refresh 10         # scoreboard refresh interval in seconds (min 5)
soccer --once               # print one snapshot and exit (great for piping)
soccer --title "MY CUP"     # override the header title
soccer --version
soccer --help

The layout auto-fits your terminal: on short windows the fixtures list becomes a scrolling window, the scoreboard compacts, and the pitch shrinks — nothing ever smears or scrolls off-screen. Resize the window and it adapts live.

Keys

| Key | Action | |-----|--------| | ↑ / ↓ (or j / k) | Move between matches (scroll the upcoming list when it's open) | | p | Toggle the live pitch | | u | Upcoming fixtures — the week ahead, with kickoff times in your timezone | | r | Force refresh (refreshes the upcoming list when it's open) | | q | Quit | | Esc | Close the upcoming view, or quit |

Leagues

Any ESPN soccer slug works — a few common ones:

fifa.world (World Cup) · eng.1 (Premier League) · esp.1 (La Liga) · ger.1 (Bundesliga) · ita.1 (Serie A) · fra.1 (Ligue 1) · uefa.champions · usa.1 (MLS) · bra.1 (Brasileirão)

What you get

• Live scores that auto-refresh, with a pulsing live indicator and a goal flash the moment anyone scores
• A big block-digit scoreboard with a scorers line (⚽ 23' Mbappé (P) · 66' Kane)
• A match timeline — goals, cards and missed penalties plotted from kickoff to full time
• Visual stat bars — possession as a team-colored split bar, shots / on-target / corners as mirrored duel bars
• Ball-by-ball commentary in a clean, word-wrapped table with color-coded event markers
• A live, animated pitch — a full 22-player match simulation on mowed-grass stripes that runs at ~8fps so the game actually moves. Two formations hold their shape and shift as a block toward the ball, the nearest defender closes down the carrier, keepers ride their line, and a goal sets off a ★ celebration at the net. Players render as bold two-cell tokens (◖◗ outfield, ▐▌ keepers) on a roomy pitch so they're easy to track, and compact to single cells on a small one. It's anchored to the real feed — the ball and run of play follow ESPN's latest event positions, possession share and attacking side — with the players around it smoothly interpolated, so it reads like a living match while staying honest about what's measured vs. simulated. A live sim · synced Ns ago heartbeat shows the feed is alive even between syncs. (Finished matches instead plot the real located events — goals ★ and a fading trail.) Toggle it with p.
• An upcoming-fixtures view (u) — the week ahead at a glance, grouped by day (Today / Tomorrow / date) with each kickoff shown in your local timezone and a live countdown (in 3h 20m). Scrolls when there's a lot on.
• Fast live sync — live matches poll commentary every ~7s, and a detected goal triggers an instant refetch
• Auto-fit layout that adapts to any terminal size, with a scrolling fixtures window on small screens
• Country flags for every nation
• 256-color visuals that degrade gracefully — plain 16-color terminals, NO_COLOR, and piped output all stay clean

Data

Powered by ESPN's public (unofficial) feed. Not affiliated with ESPN or FIFA. Endpoints are undocumented and may change without notice. Requests time out after 8s and retry on the next cycle, so a flaky network never freezes the UI.

Releasing (maintainers)

Releases are fully automated. Every push to main that passes CI (typecheck + tests + build) is published to npm by the Release workflow:

• normally it bumps a patch version, commits chore(release): vX.Y.Z, tags, and publishes;
• to ship a minor/major, bump version in package.json in your PR — that exact version is published instead.

The only setup required is the NPM_TOKEN repository secret.

License

MIT © SpunkySarb