WorldCup26 — World Cup 2026 TUI

A fast, keyboard-driven terminal UI for the FIFA World Cup 2026: schedule, group standings, the knockout bracket, and a live scoreboard — built with Rust and ratatui.

Status: under active development.

Features

• Matches — fixtures by day and stage, status badges, local-timezone kickoff times, and favourite-team filtering; opens on the current (or next) game.
• Live — a glanceable "Live Activity" card: a large block-digit score flanked by real national flags (inline images on Kitty / Ghostty / WezTerm / iTerm2 / Sixel terminals; omitted on terminals without graphics support), the clock, and the most recent event; previews the next kickoff with a countdown when nothing is in play.
• Standings — the 12 group tables (A–L) with qualification highlighting, team-row navigation, and Enter to open a team view.
• Team — opened from Standings: a team's group summary, recent form, and full fixture list.
• Bracket — the knockout tree (Round of 32 → Final).
• Match detail — goals, cards, substitutions, lineups, and team stats.
• Favourite teams — star teams with * from Standings or the team view; favourites are highlighted (★) across every screen and can filter the Matches list.
• Real national flags on the Live card when the terminal supports graphics.
• Pluggable data providers (ESPN by default; API-Football and football-data.org optional), nine colour themes (including Catppuccin and a Government of Canada palette), an offline cache, and mouse support.

Installation

The crates.io package is named worldcup26; it installs the worldcup26 command.

Requirements

• Rust 1.95.0 or newer with Cargo. Install it with rustup if you do not already have Rust.
• Native build tools for your OS:
  • macOS: xcode-select --install
  • Debian/Ubuntu: sudo apt install build-essential
  • Windows: Visual Studio Build Tools with the MSVC toolchain
• A terminal that supports standard TUI apps. Live flag images are shown only in graphics-capable terminals such as Kitty, Ghostty, WezTerm, Konsole, iTerm2, or Sixel-capable terminals; everything else works without graphics support.

Install the latest released version from crates.io:

cargo install worldcup26 --locked
worldcup26

If worldcup26 is not found after installation, add Cargo's bin directory to your PATH (~/.cargo/bin on macOS/Linux, %USERPROFILE%\.cargo\bin on Windows).

WorldCup26 uses ESPN by default and does not require an API key. Optional providers can be enabled with WORLDCUP26_API_FOOTBALL_KEY or WORLDCUP26_FOOTBALL_DATA_KEY; see Data providers.

Run from source

cargo run -p worldcup26 --bin worldcup26

Requires the toolchain pinned in rust-toolchain.toml.

Data providers

WorldCup26 normalizes several upstream APIs behind one interface:

Select a provider with --provider <espn|api-football|football-data> or in the config file.

Keybindings

The full list, including per-screen and mouse bindings, is in docs/keybindings.md.

Workspace layout

• crates/wc-data — normalized domain model and provider backends.
• crates/worldcup26 — the terminal UI (binary worldcup26).

Documentation

• Architecture — crates, data flow, polling, cache.
• Data providers — providers, API keys, configuration.
• Keybindings — full keyboard and mouse reference.

Release automation

Releases are managed by release-please. Conventional Commits merged to main keep a Release PR open with the next version and changelog entry. Merging that Release PR creates the GitHub release, then dispatches the publish workflow.

For non-draft releases, CI publishes both crates to crates.io in dependency order:

1. wc-data
2. worldcup26 (installs the worldcup26 binary)

Repository setup requires a crates.io API token stored as the CARGO_REGISTRY_TOKEN GitHub Actions secret. The same publish workflow also builds the release archives and Debian packages attached to the GitHub release.

License

Apache-2.0. See LICENSE.

Bundled national-flag artwork is from flag-icons (MIT); see crates/worldcup26/assets/flags/ATTRIBUTION.md.