worldcup26-cli ⚽

A colorful terminal CLI to follow the FIFA World Cup 2026 (USA · Canada · Mexico). View today's games, group standings, country stats, and the knockout bracket — right from your shell.

$ worldcup --date 2026-06-11

⚽ Matches on Thu, Jun 11, 2026

  🇲🇽 Mexico                  vs  South Africa 🇿🇦  · 13:00 UTC-6 @ Mexico City  [Group A]
  🇰🇷 South Korea             vs  Czech Republic 🇨🇿  · 20:00 UTC-6 @ Guadalajara  [Group A]

Features

• today — matches scheduled for today, with scores once played. For any other day, use the top-level --date.
• groups — all 12 group tables, or a single group with --group. Standings (Pts → GD → GF) are computed from results; the top 2 are highlighted.
• country — a team's group, current standing, and full match list, looked up by name (partial, case-insensitive).
• knockout — the bracket by stage (Round of 32 → Final), filterable with --stage.

Install

npm install -g worldcup26-cli
worldcup today

Or run it without installing:

npx worldcup26-cli groups --group A

Requires Node.js ≥ 18 (uses the built-in fetch).

Usage

The CLI is available as both worldcup and the shorter wcup — they're interchangeable.

worldcup today                          # today's fixtures (or: wcup today)
worldcup --date 2026-06-11              # fixtures for a specific day
worldcup groups [--group A]             # all groups, or just one
worldcup country <name>                 # e.g. "mexico", "kor", "brazil"
worldcup knockout [--stage <name>]      # r32 | r16 | qf | sf | third | final
worldcup ko --stage final               # 'ko' is an alias for 'knockout'

# Global flags
-d, --date <YYYY-MM-DD>   # show matches for a specific day
--refresh                 # bypass the local cache and re-fetch
--no-color                # plain output (also honors the NO_COLOR env var)
-v, --version
-h, --help

Data source

Match data comes from the public-domain openfootball/worldcup.json project — no API key required. The CLI fetches it once and caches it at ~/.worldcup-cli/cache.json (1-hour TTL), so repeat commands are instant and it still works offline from the last successful fetch. Use --refresh to force an update.

Scores reflect final/official results (updated after matches finish) — there is no live in-progress ticker. Group standings use the common Pts → goal-difference → goals-for tiebreakers (a simplification of the full FIFA criteria).

Development

npm install
npm run dev -- --date 2026-06-11         # run from source via tsx
npm run build                            # compile TypeScript to dist/
node dist/index.js groups                # run the build

Test it locally as a global command

npm run build
npm link                 # makes `worldcup` available system-wide
worldcup --date 2026-06-11
npm unlink -g worldcup26-cli   # when finished

Alternatives without linking: node dist/index.js <cmd> or npm install -g ..

Publishing to npm

1. Check the name is free: npm view worldcup26-cli. If taken, switch to a scoped name (e.g. @yourname/worldcup26-cli) in package.json.
2. Log in: npm login.
3. Bump the version: npm version patch (or minor / major).
4. Publish: npm publish.
   • For a scoped package, the first publish needs npm publish --access public.
   • The prepublishOnly script builds dist/ automatically, and "files": ["dist"] keeps the published package lean.
5. Users can now npm install -g worldcup26-cli or npx worldcup26-cli.

Project structure

src/
  index.ts            # commander program + global flags
  types.ts            # Match / Score / Standing types
  data/
    fetch.ts          # fetch upstream JSON, TTL cache, offline fallback
    cache.ts          # ~/.worldcup-cli/cache.json read/write
    flags.ts          # team → flag emoji + 3-letter code
  lib/
    standings.ts      # compute group tables from results
    dates.ts          # date parsing / "today" handling
    format.ts         # chalk rendering (match lines, tables)
  commands/
    today.ts  groups.ts  country.ts  knockout.ts

License

MIT