BaseballCommand

Baseball scores and statistics in your terminal.

BaseballCommand (base) is a command-line tool for looking up player stats, team stats, standings, league leaders, and the day's scores. It reads from the public MLB Stats API, so there is no API key, no account, and no signup — install it and run it.

$ base scores yesterday

Scores — Thursday, August 13, 2026
9 games

  Status  Away                    R  Home                  R
  ------  ---------------------  --  --------------------  -
  Final   Cleveland Guardians     0  Detroit Tigers        3
  Final   Cincinnati Reds         9  Chicago White Sox     8
  Final   Pittsburgh Pirates     13  Miami Marlins         1
  Final   Seattle Mariners        1  New York Yankees      0
  Final   Boston Red Sox          7  Toronto Blue Jays     0

$ base player "Aaron Judge"

Aaron Judge
#99 · Outfielder · New York Yankees

  Bats/Throws    Right/Right
  Height/Weight  6' 7", 282 lb
  Age            34
  Born           1992-04-26 (Linden, CA, USA)
  MLB debut      2016-08-13
  Status         Active
  MLBAM id       592450

Hitting — 2026
   G   PA   AB   R   H  2B  3B  HR  RBI  BB  SO  SB  CS   AVG   OBP   SLG   OPS
  --  ---  ---  --  --  --  --  --  ---  --  --  --  --  ----  ----  ----  ----
  59  261  214  43  53  10   0  17   38  42  72   5   3  .248  .375  .533  .908

Contents

• Data Sources and Dependencies
• Install
• Quick start
• Commands
• Global options
• Naming players and teams
• JSON output and scripting
• Caching
• Troubleshooting
• Data source and terms of use
• Development
• License

Data Sources and Dependencies

Everything comes from statsapi.mlb.com, the same public API that powers MLB.com's own scoreboards. It is unauthenticated and free to query. There is no paid tier, no rate-limit key, and nothing to configure.

BaseballCommand also has zero runtime dependencies. It runs on the Python standard library alone, so pip install pulls in nothing else and the tool keeps working regardless of what happens to any third-party package.

Please read Data source and terms of use before building anything on top of it — MLBAM permits individual, non-commercial, non-bulk use of this data.

Install

Requires Python 3.9 or newer.

The recommended way is pipx, which installs the CLI into its own environment and puts base on your PATH:

pipx install https://github.com/opowell28/BaseballCommand.git

Or with pip:

pip install https://github.com/opowell28/BaseballCommand.git

From a local clone:

git clone https://github.com/opowell28/BaseballCommand.git && cd BaseballCommand && pip install -e .

Check that it worked:

base --version

The package installs two identical entry points, base and baseballcommand, and also runs as a module with python -m baseballcommand.

Quick start

base scores                          # today's games
base scores yesterday --linescore    # yesterday's games, inning by inning
base player "Aaron Judge"            # a player's current season
base player Ohtani --years           # every season a player has played
base team NYY                        # a club's record and season totals
base standings --league al           # American League standings
base leaders hr -n 5                 # this season's top five home run hitters
base roster LAD --stats --sort HR    # a full roster, sorted by home runs
base compare Judge Ohtani            # two players side by side

Commands

Every command takes -h for its own options. The full reference, with examples and output for each, is in docs/commands.md.

Global options

These go before the subcommand — base --json scores, not base scores --json.

Color is enabled only when stdout is a terminal, and is disabled automatically when you pipe or redirect output, or when NO_COLOR is set.

Naming players and teams

You do not have to be precise. Teams accept an abbreviation, a city, a nickname, a club name, a full name, or a numeric id:

base team NYY
base team "New York Yankees"
base team yanks
base team 147

Players accept any part of a name, or an MLBAM id. Retired players work too:

base player judge
base player "Ken Griffey Jr."
base player 592450

When a query genuinely matches more than one, BaseballCommand says so and lists the candidates rather than guessing:

$ base team sox
base: 'sox' matches more than one team:
   CWS  Chicago White Sox
   BOS  Boston Red Sox

$ base player "ken griffey"
base: 'ken griffey' matches 2 players — rerun with a fuller name or an id:
  115135  Ken Griffey Jr. (retired)  [CF — Seattle Mariners]
  115136  Ken Griffey Sr. (retired)  [RF — Seattle Mariners]

Run base teams for the full list of clubs and abbreviations.

JSON output and scripting

Every command supports --json, which prints a stable, flattened structure rather than the API's raw envelope. This makes base usable as a data source in scripts:

# Tonight's matchups
base --json scores | jq -r '.games[] | "\(.away.name) @ \(.home.name)"'

# Every team over .500
base --json standings | jq -r '.groups[].teams[] | select((.pct|tonumber) > 0.5) | .name'

# A player's home run total
base --json player "Aaron Judge" | jq '.stats.hitting[0].stat.homeRuns'

Exit codes are script-friendly:

Caching

Responses are cached on disk so repeated commands are fast and the free public API is not hammered. Live scores get a 30-second lifetime; season stats get an hour; team lists and biographical data get a day.

base cache          # location, entry count, size on disk
base cache clear    # throw it all away
base --no-cache …   # bypass for one command

The cache lives in ~/.cache/baseballcommand by default, honoring XDG_CACHE_HOME. Set BASEBALLCOMMAND_CACHE_DIR to put it somewhere else. It is safe to delete at any time.

Troubleshooting

TLS certificate verification failed

Your Python installation has no usable root certificates. This is common with the python.org macOS installer, which ships certificates but does not install them.

• macOS, python.org build: run /Applications/Python 3.x/Install Certificates.command
• Any platform: pip install certifi — BaseballCommand uses it automatically when it is present.

BaseballCommand never disables certificate verification.

Stats are empty for the current season

In January and February the current season has not started, so base defaults to the season that just finished. During spring training the regular-season stats are genuinely empty; pass --season for a specific year.

Could not reach the MLB Stats API

Check your network. If you are behind a proxy, urllib honors the standard HTTP_PROXY and HTTPS_PROXY environment variables.

Data source and terms of use

All data comes from the MLB Stats API at https://statsapi.mlb.com. That API is publicly reachable but not officially documented or supported for third-party use, and its responses carry this notice from MLB Advanced Media:

Only individual, non-commercial, non-bulk use of the Materials is permitted and any other use of the Materials is prohibited without prior written authorization from MLBAM. — gdx.mlb.com/components/copyright.txt

BaseballCommand is a personal-use tool and is built to stay inside that: it queries only what you ask for, and it caches responses to avoid redundant requests. If you intend to use this data commercially or to bulk-download it, contact MLBAM for authorization first.

BaseballCommand is an independent project. It is not affiliated with, endorsed by, or sponsored by Major League Baseball, MLB Advanced Media, or any club. All trademarks belong to their respective owners.

More detail on which endpoints are used and how, in docs/data-source.md.

Development

git clone https://github.com/opowell28/BaseballCommand.git
cd BaseballCommand
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

pytest          # the full suite, entirely offline
ruff check .    # lint

The test suite makes no network calls — the API client is replaced with a fake serving canned payloads — so it is fast and works offline.

See CONTRIBUTING.md for the layout of the codebase and how to add a command.

License

MIT © Owen Powell.

The license covers this software. It does not cover the data, which remains the property of MLB Advanced Media under the terms linked above.