nba-cli

Overview

nba-cli is a small, scriptable Python command-line tool for querying NBA data using the balldontlie OpenAPI (https://www.balldontlie.io/openapi.yml). It provides quick access to player information, season/game statistics, and game box scores via a simple CLI surface.

Key features

• Player search and profile lookup
• Season averages and per-game statistics
• Game listing and boxscore retrieval
• Machine-readable JSON output and human-friendly terminal formatting

Installation

Clone the repository and install in editable mode (recommended for development):

git clone https://github.com/ryanodonnell/NBA-CLI.git
cd NBA-CLI
python -m pip install -e .

Install runtime-only dependencies:

python -m pip install requests click

Quickstart / Usage

Basic usage pattern follows the nba-cli root command with subcommands described below.

Examples:

# search players by name
nba-cli player search "lebron"

# show player info
nba-cli player info 237

# get season averages for a player (player_id, year)
nba-cli stats season 237 2023

# get player stats for a specific date
nba-cli stats game 237 2024-03-10

# list games on a date
nba-cli game list --date 2024-03-10

# show boxscore for a game
nba-cli game boxscore 9001

# machine-readable output
nba-cli player search "lebron" --json

See the CLI help for details:

nba-cli --help
nba-cli player --help
nba-cli stats --help
nba-cli game --help

Configuration

The client should read any API keys or secrets from environment variables. Example environment variable:

export BALLDONTLIE_API_KEY="your_api_key_here"

No secrets should be committed to the repository.

Project layout (recommended)

• nba_cli/
  • cli.py — CLI entrypoint (click/typer)
  • api/
    • client.py — centralized HTTP client
    • models.py — pydantic models for API responses
  • commands/
    • player.py
    • stats.py
    • game.py
  • util/
    • formatters.py
    • errors.py
• tests/ — pytest test suite
• pyproject.toml
• LICENSE
• README.md

Development

Run tests locally:

python -m pytest -q

Linting & formatting (if configured):

black .
ruff .

Continuous integration is configured via GitHub Actions (.github/workflows/tests.yml).

Contributing

Contributions are welcome. Please:

• Follow PEP 8 and run Black/ruff before committing.
• Add unit tests for new features.
• Open small, focused pull requests with a descriptive title and changelog entry.

License

This project is provided under the MIT License — see the LICENSE file for details.