mlbt

A terminal user interface for the MLB Statcast API, written in Rust.

Check scores, standings, and stats. Even watch a live game using Gameday!

Table of Contents

• What
• Installation
  • Homebrew
  • Binaries
  • Cargo
  • Docker
• Features
• Usage
  • Scoreboard
  • Gameday
  • Stats
  • Standings
  • Date Picker
  • Help
• Config
• Shout out
• Copyright Notice
• License

What

The MLB Statcast API is a publicly available (see its license information below) REST API that you can query to get back almost any information about a baseball game, past or present. If you've ever watched a baseball game on TV you've seen the data the API passes around in action. Two prime examples are the pitch/strike zone overlay, and home run stats (like distance and launch angle). This is accomplished by MLB's sophisticated Statcast vision system, which is implemented in every Major League ballpark.

This TUI is an interface for the API, with the intention of providing a light weight way to consume baseball data. See the features listed below for more details.

A TUI and baseball data make a pretty natural combination, at least compared to other sports. The Gameday view allows you to "watch" a live game by polling the API every 10 seconds. This matches the poll rate at which the official Gameday, found here, operates at. The goal with the TUI version is to mimic the official version as closely as possible.

Installation

Homebrew

brew tap mlb-rs/mlbt
brew install mlbt

To update to the latest version:

brew upgrade mlbt

Binaries

macOS, Linux, and Windows binaries are available on the releases page.

Cargo

After cloning or downloading the source:

cargo install mlbt --path .

Docker

mlbt publishes docker images on ghcr.

docker run -it --rm --name mlbt ghcr.io/mlb-rs/mlbt

mlbt follows semver practices. You can execute individual releases explicitly.

docker run -it --rm --name mlbt ghcr.io/mlb-rs/mlbt:v0.0.18

Alternately build the mlbt image with:

docker build -t mlbt .

Execute mlbt within the container with:

docker run -it --rm --name mlbt mlbt:latest

Features

• scoreboard and box score

  • sorted by favorite team
  • selectable date
  • win probability graph

• gameday

  • pitch display
  • batter strike zone with heat map coloring
  • selectable at bats (view the pitches and outcome of any at bat in the game)
  • hit stats (exit velocity, launch angle, distance)
  • win probability per at bat

• pitching and hitting stats

  • player stats
  • team stats
  • sorting
  • selectable date

• standings

  • sorted by favorite team
  • selectable date

• configuration

  • favorite team
  • time zone

Usage

After installing, run mlbt from your terminal to open the program.

Press q to exit at any time.

Tabs

There are four main tabs.

• Scoreboard
• Gameday
• Stats
• Standings

Press f for full screen mode to hide the tab bar.

Scoreboard

Press 1 to activate this tab.

Key	Description
j / ↓	move down
k / ↑	move up
Enter	view current game in Gameday
:	activate date picker (see Date Picker)
w	toggle win probability graph
h	switch to home team in box score
a	switch to away team in box score
Shift + j/ ↓	scroll box score down
Shift + k/ ↑	scroll box score up

Gameday

Press 2 to activate this tab.

By default, the info and pitches panes are shown. However, each pane can be toggled on and off using:

Key	Description
i	info pane
p	pitches pane
b	box score pane
w	toggle win probability graph

To view different at bats in the game, use:

Key	Description
j / ↓	move to previous play
k / ↑	move to next play
l	move to the "live" play, or latest available
s	move to first play of the game

To interact with the box score, use:

Key	Description
h	switch to home team in box score
a	switch to away team in box score
Shift + j/ ↓	scroll box score down
Shift + k/ ↑	scroll box score up

Stats

Press 3 to activate this tab.

You can switch between pitching and hitting stats and filter based on team or player using:

Key	Description
p	pitching
h	hitting
t	team
l	player

Within each stat group (pitching or hitting) you can toggle the display of individual stat columns by selecting the stat with Enter. This selection pane can be turned on/off with o.

To sort the stats by a column, instead of hitting Enter you can press s. To flip the sort order from ascending to descending or vice versa press s again.

Key	Description
j / ↓	move down
k / ↑	move up
Enter	toggle stat column
s	sort by the currently selected column
:	activate date picker (see Date Picker)
o	toggle stat selection pane

If your terminal is too small to display all columns, they will be turned off starting from the right side.

Standings

Press 4 to activate this tab.

Key	Description
j / ↓	move down
k / ↑	move up
:	activate date picker (see Date Picker)

Date Picker

With the date picker active, input a date in the form of YYYY-MM-DD, or use the left/right arrow keys, and press Enter.

Key	Description
← / →	use arrow keys to navigate date
Enter	confirm the selected date
Esc	cancel selection
today / t	go back to the current day

Note that each tab has its own date, i.e. if you're viewing older stats or standings, the schedule can be the current date.

Help

Key	Description
?	display help box
Esc	close help box
"	display logs

If your terminal is too small to display the full help box, the border will be displayed red.

Config

You can configure the TUI with the toml file located at your users' home directory. For a user named Alice this would be:

• Linux: /home/alice/.config/mlbt/mlbt.toml
• Windows: C:\Users\Alice\AppData\Roaming\mlbt\mlbt.toml
• macOS: /Users/Alice/Library/Application Support/mlbt/mlbt.toml

You can see the path for your user in the Help page.

Available settings

• favorite_team: This will make that team always show up first in the schedule if they have a game that day. See here for options (note: use the full name and not the short name).
• timezone: This will change the time zone of the start time for the games in the schedule. The default is US/Pacific. Some common options are:
  • US/Pacific
  • US/Mountain
  • US/Central
  • US/Eastern
  • For the full list see here
• log_level: Set the log level to be displayed. If not present, error level is used. Use a lowercase word, e.g. debug. See here for the options.

Example config

# See https://github.com/mlb-rs/mlbt#config for options
favorite_team = "Chicago Cubs"
timezone = "US/Pacific"
log_levl = "error"

Shout out

This was originally built with the wonderful tui-rs. It is now using the also wonderful fork, ratatui.

These TUIs were extremely helpful: spotify-tui, tickrs, bottom.

A reference MLB stats API client by toddrob99 helped make up for the lack of API documentation.

Copyright Notice

The data used in this application is supplied by the MLB's Stats API. Use of this data is subject to the license posted here: http://gdx.mlb.com/components/copyright.txt.

This application and its author are not affiliated with the MLB.

License

This project is under the MIT License.