playball

You can try Playball immediately using npx without a permanent installation, or install it globally to use the playball command directly.

Quick Start

$ npx playball

Global Installation

To install the package globally:

$ npm install -g playball

Then run it using:

$ playball

If you do not have Node.js installed, you can run Playball using Docker. By default, times are shown in Eastern Time. You can change the timezone by setting the TZ environment variable.

Basic Run

$ docker run -it --rm paaatrick0/playball

Run with specific Timezone

Use the -e TZ=... flag to set your desired timezone (e.g., America/Chicago for Central Time, America/Denver for Mountain Time, or America/Los_Angeles for Pacific Time).

# Central Time
$ docker run -it --rm -e TZ=America/Chicago paaatrick0/playball

# Mountain Time
$ docker run -it --rm -e TZ=America/Denver paaatrick0/playball

# Pacific Time
$ docker run -it --rm -e TZ=America/Los_Angeles paaatrick0/playball

By default, Playball displays MLB games. To watch World Baseball Classic games, you can either update your persistent configuration or use an environment variable for a one-time session.

Persistent Configuration

To switch to WBC permanently:

playball config sport wbc

To switch back to MLB:

playball config sport mlb

One-time viewing via Environment Variable

PLAYBALL_SPORT=wbc playball

One-time viewing via Docker

docker run -it --rm -e PLAYBALL_SPORT=wbc paaatrick0/playball

Use the config subcommand to view and modify your settings.

List all settings

Run the subcommand without arguments to see current values:

playball config

Get a single setting

Pass the specific key as an argument:

playball config color.strike

Change a setting

Pass the key and the new value:

playball config color.strike blue

Revert a setting to default

Use the --unset flag with the key:

playball config color.strike --unset

You can override the default sport (MLB) by setting the PLAYBALL_SPORT environment variable. This takes precedence over the sport configuration key.

To set the sport to World Baseball Classic, use:

export PLAYBALL_SPORT=wbc

Playball uses keyboard shortcuts to navigate between different views and control the game display.

Global Keys

• q: Quit
• c: Go to schedule view
• s: Go to standings view

Schedule View Keys

• ↓/j, ↑/k, ←/h, →/l: Change highlighted game
• enter: View highlighted game
• p: Show previous day's schedule/results
• n: Show next day's schedule
• t: Return to today's schedule

Game View Keys

• ↓/j, ↑/k: Scroll list of all plays

The screen.js module provides utilities to manage the title of the terminal screen used by Playball!. These functions interact with the underlying blessed screen instance.

• setTitle(title): Sets the terminal window title to the provided string.
• resetTitle(): Resets the terminal window title to the default value 'Playball!'.

import { setTitle, resetTitle } from './src/screen.js';

// Set a custom title
setTitle('My Custom Playball Session');

// Reset back to 'Playball!'
resetTitle();

The App component is the main entrypoint for the Playball application. It manages the application state, including the current view (Schedule, Standings, or Game) and keyboard navigation.

It accepts two optional props to control the initial state:

• replayId (string): If provided, the application will attempt to load a specific replay game. If successful, it switches the view to the Game view; otherwise, it falls back to the Schedule view.
• defaultDate (string): An ISO-formatted date string that sets the initial date in the application schedule.

import App from './src/components/App.jsx';

// Example usage with a specific replay and date
function Root() {
  return <App replayId="12345" defaultDate="2026-07-21T00:00:00Z" />;
}

Use getSport() to retrieve the current sport identifier as a string ('mlb' or 'wbc').

Priority for determining the sport is as follows:

1. The PLAYBALL_SPORT environment variable (case-insensitive).
2. The sport configuration key.
3. Defaults to mlb.

import { getSport } from './utils.js';

const sport = getSport(); // Returns 'mlb' or 'wbc'

Use these selectors to access static or semi-static game information from the gameData object:

• selectGameStatus: Returns the current status of the game.
• selectPlayers: Returns the list of players.
• selectTeams: Returns the team information.
• selectVenue: Returns the venue details.
• selectStartTime: Returns the game start time (datetime.dateTime).
• selectProbablePitchers: Returns the probable pitchers.
• selectReview: Returns review information.
• selectAbsChallenges: Returns ABS (Automated Ball-Strike) challenges.

Use the fetchSchedule async thunk to retrieve MLB schedule data for a specific date. It performs a GET request to the MLB Stats API using the current sportId and formats the provided date as MM/dd/yyyy. This thunk integrates with Redux Toolkit to manage loading, error, and data states automatically.

import { fetchSchedule } from './path/to/schedule';

// Dispatch the thunk with a specific Date object
dispatch(fetchSchedule(new Date('2023-07-21')));