Metadata-Version: 2.5
Name: baseballcommand
Version: 0.1.0
Summary: Baseball scores and statistics in your terminal, from the free MLB Stats API.
Project-URL: Homepage, https://github.com/opowell28/BaseballCommand
Project-URL: Repository, https://github.com/opowell28/BaseballCommand
Project-URL: Issues, https://github.com/opowell28/BaseballCommand/issues
Author: Owen Powell
License: MIT License
        
        Copyright (c) 2026 Owen Powell
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: baseball,cli,mlb,scores,sports,statistics
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

# 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](#data-sources-and-dependencies)
- [Install](#install)
- [Quick start](#quick-start)
- [Commands](#commands)
- [Global options](#global-options)
- [Naming players and teams](#naming-players-and-teams)
- [JSON output and scripting](#json-output-and-scripting)
- [Caching](#caching)
- [Troubleshooting](#troubleshooting)
- [Data source and terms of use](#data-source-and-terms-of-use)
- [Development](#development)
- [License](#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](#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](https://pipx.pypa.io/), which installs the CLI into
its own environment and puts `base` on your PATH:

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

Or with pip:

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

From a local clone:

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

Check that it worked:

```bash
base --version
```

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

## Quick start

```bash
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

| Command | What it does |
| --- | --- |
| [`base scores [DATE]`](docs/commands.md#base-scores) | Scores and status for a day's games |
| [`base player NAME`](docs/commands.md#base-player) | One player's bio and stat lines |
| [`base team NAME`](docs/commands.md#base-team) | A club's record and season totals |
| [`base standings`](docs/commands.md#base-standings) | Division or wild card standings |
| [`base leaders CATEGORY`](docs/commands.md#base-leaders) | League leaderboards |
| [`base roster NAME`](docs/commands.md#base-roster) | A club's roster, optionally with everyone's stats |
| [`base compare A B`](docs/commands.md#base-compare) | Players side by side |
| [`base teams`](docs/commands.md#base-teams) | Every club and its abbreviation |
| [`base glossary`](docs/commands.md#base-glossary) | What the column headings mean |
| [`base cache`](docs/commands.md#base-cache) | Inspect or clear the response cache |

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

## Global options

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

| Option | Effect |
| --- | --- |
| `--json` | Print raw JSON instead of tables. Implies `--no-color`. |
| `--no-color` | Disable ANSI color. |
| `--no-cache` | Bypass the cache; always fetch fresh. |
| `--timeout SECONDS` | Network timeout per request (default 15). |
| `-V`, `--version` | Print the version. |

Color is enabled only when stdout is a terminal, and is disabled automatically
when you pipe or redirect output, or when [`NO_COLOR`](https://no-color.org/) 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:

```bash
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:

```bash
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:

```bash
# 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:

| Code | Meaning |
| --- | --- |
| `0` | Success |
| `1` | Lookup or network failure (unknown player, API unreachable) |
| `2` | Bad usage (unparseable date, unknown category, ambiguous input) |
| `130` | Interrupted with Ctrl-C |

## 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.

```bash
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](http://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](docs/data-source.md)**.

## Development

```bash
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](CONTRIBUTING.md)** for the layout of the codebase and how
to add a command.

## License

[MIT](LICENSE) © 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.
