Ballarr

Sports media manager — like Sonarr, but for sports. Self-hosted, open-source, eventually offered as a hosted SaaS.

What it does

Ballarr lets you follow sports teams and track their schedules. Point it at a league, pick your teams, and it manages the rest — pulling upcoming games and recent results from TheSportsDB.

Requirements

• Python 3.13+
• uv
• A TheSportsDB V2 API key

Setup

git clone <repo-url>
cd ballarr
uv sync
echo "THESPORTSDB_API_KEY=your_key_here" > .env

Usage

# List all teams in a league (default: NBA)
ballarr teams
ballarr teams --league-id 4387

# Upcoming games for a team
ballarr schedule warriors
ballarr schedule GSW

# Recent results
ballarr schedule lakers --previous

Team names are matched by case-insensitive substring or exact abbreviation.

Development

uv run pytest                          # run tests
uv run ruff check . && uv run ruff format .   # lint + format

Stack

• Python 3.13+ — managed with uv
• CLI — Click + Rich
• HTTP client — httpx
• Data models — Pydantic
• Data source — TheSportsDB V2 API

Roadmap

1. Pydantic models for API responses ✓
2. SQLModel + PostgreSQL for persistence (watched teams, tracked events)
3. Scheduler/daemon layer — monitor watched teams, trigger on new content

Contributing

This project is written collaboratively with Claude Code. The design and all review decisions are made by the project author.

License

TBD