# sportsball

A terminal dashboard for live sports — [Plain Text Sports](https://plaintextsports.com) meets [Golazo][golazo],
as a [Bubble Tea][bubbletea] TUI. On-going, upcoming, and past games across the
**World Cup, MLB, NBA, WNBA, NHL, and NFL** — filter by league and state, favorite
teams, browse standings and full team schedules, and open any game into a live
detail view with box scores, scoring plays, team-stat bars, and a breathing LIVE
indicator.

```
 SPORTSBALL!  live scores                                    ● 3 live
 ALL │ ⚽ WC │ ⚾ MLB │ 🏀 NBA │ 🏀 WNBA │ 🏒 NHL │ 🏈 NFL
 All │ ● Live │ ◼ Recent │ ○ Upcoming
 …
```

> _Screenshot / asciicast: TODO_

## Features

- **Live dashboard** — per-league cards (team-colored from ESPN data), live / upcoming / final states, a breathing LIVE pulse, and a state filter (live / recent / upcoming).
- **Favorites** — star teams; favorite games pin to the top.
- **Standings** — per-league tables (soccer groups, MLB divisions, NBA/NHL/NFL conferences), ranked.
- **Team schedules** — any team's full season, past results + upcoming fixtures.
- **Live detail** — box scores, scoring plays, soccer team-stat comparison bars, and a ticker of other games.
- **Configurable leagues** — show/hide/reorder; off-season leagues auto-hide and return when in season.
- **Six themes** — Flexoki / Uchu / Humdrum, light + dark.

## Install

  ```sh
  brew tap humdrum/tap https://codex.humdrum.me/git/homebrew-tap.git
  brew trust humdrum/tap   # Homebrew gates third-party taps
  brew install sportsball
  ```

Upgrade later:

```sh
brew update && brew upgrade sportsball
```

## Usage

```bash
sportsball            # launch the TUI
sportsball --version  # print version
```

### Keys

**Dashboard**

| Key | Action |
| --- | --- |
| `↑`/`↓` (`k`/`j`) | move selection by grid row |
| `←`/`→` | move selection horizontally |
| `enter` (`l`) | open the selected game |
| `tab` / `⇧tab` | next / previous league |
| `v` / `V` | cycle state filter forward / back (all · live · recent · upcoming) |
| `f` / `F` | favorite the away / home team |
| `g` / `G` | open the away / home team's schedule |
| `s` | standings for the selected game's league |
| `L` | league settings (show / hide / reorder) |
| `r` | refresh now |
| `t` | cycle theme (matches your terminal's light/dark) |
| `q` (`ctrl+c`) | quit |

**Detail view**

| Key | Action |
| --- | --- |
| `tab` / `⇧tab` | move through the live ticker of other games |
| `enter` | switch to the selected ticker game |
| `↑`/`↓` | scroll the box score / events |
| `f` / `F` | favorite away / home |
| `g` / `G` | open the away / home team's schedule |
| `esc` (`h`) | back to the dashboard |

**Standings** (`s`)

| Key | Action |
| --- | --- |
| `↑`/`↓` | move the team cursor |
| `tab` / `⇧tab` | switch league |
| `enter` | open the selected team's schedule |
| `f` / `F` | favorite the selected team |
| `esc` / `s` | back |

**League settings** (`L`)

| Key | Action |
| --- | --- |
| `↑`/`↓` | move |
| `space` | show / hide the selected league |
| `K`/`J` (`⇧↑`/`⇧↓`) | reorder |
| `0` | reset to seasonal auto |
| `esc` | done |

## Data & config

Scores come from ESPN's public (unofficial) scoreboard API — **no API key
required**. Preferences (favorite teams, active theme, league show/hide/order)
persist to `~/.config/sportsball/config.json` (XDG:
`$XDG_CONFIG_HOME/sportsball/config.json`).

## Themes

Six palettes ported from the Flexoki, Uchu, and Humdrum token sets, each in a
light and dark variant. `t` cycles only the variants matching your terminal's
background, and the whole frame is painted in the theme's colors.

## License

Sportsball — Copyright (C) 2026 humdrum-tiv.

Free software under the [GNU Affero General Public License v3.0](LICENSE) (or, at
your option, any later version). You may use, study, share, and modify it; any
distributed derivative — **or modified version offered to users over a network** —
must also be AGPL-licensed with source available. It comes with **no warranty**.
See [LICENSE](LICENSE) for the full terms.

[golazo]: https://github.com/0xjuanma/golazo
[bubbletea]: https://github.com/charmbracelet/bubbletea