lucky-cli

A lottery CLI tool built with Python for fun. Installed command: lucky.

Supports Powerball (5 numbers 1–69 + special 1–26) and Mega Millions (5 numbers 1–70 + special 1–25).

Install (dev)

uv sync
uv run lucky --help

Usage

Command	Description
lucky pick <game> [--count N]	Generate N valid random tickets
lucky check <game> <n1..n5> --special <s>	Check a ticket against the latest draw
lucky show <game>	Show the latest draw (date, numbers, special, jackpot) — default view
lucky show <game> --history [--limit N]	Show the last N draws
lucky show <game> --stats	Show number frequency, hot/cold numbers, odd/even distribution
lucky --version	Show the installed version

Example:

lucky check powerball 12 18 33 44 61 --special 9

On every run, lucky checks for new draws and updates its local SQLite cache (~/.lucky-cli/lucky.db) before executing your command. If offline, it silently falls back to the cached data.

Project Structure

src/lucky/
├── cli.py            # Typer app entrypoint
├── commands/         # one module per subcommand
├── lottery/          # game rules + ticket generator
├── database/         # SQLAlchemy models/repository
├── updater/          # remote source + sync logic
└── console/          # Rich rendering helpers
tests/

See CLAUDE.md for the full architecture spec.

Development

uv sync              # install deps
uv run pytest        # run tests
uv run lucky <cmd>   # exercise the CLI locally

Contributing

• Commits follow Conventional Commits: feat:, fix:, docs:, refactor:, test:, chore:. Use feat!: or a BREAKING CHANGE: footer for breaking changes.
• Versioning is automated from git tags (setuptools-scm) — never hand-edit a version string.
• Route all CLI output through src/lucky/console/; avoid raw print().
• Add/update tests under tests/ for any change to generator, stats, checker, or database logic.
• CI publishes to PyPI on v* tags via .github/workflows/release.yml.

Releasing / Versioning

Version numbers are never hand-edited — they're derived from git tags via setuptools-scm. To cut a release:

1. Find the last release tag (skip if this is the first release):

   git describe --tags --abbrev=0

2. Review commits since that tag:

   git log <last-tag>..HEAD --oneline

3. Classify them by Conventional Commits prefix to decide the version bump:
   • feat: → MINOR
   • fix: → PATCH
   • feat!: or a BREAKING CHANGE: footer → MAJOR
   • (first release with no prior tag: start at v0.1.0)
4. Add a new section to CHANGELOG.md, grouped by category:

   ## v0.3.0
   
   ### Features
   - add stats command
   
   ### Fixes
   - fix check logic

5. Commit the changelog update, then create and push the tag:

   git add CHANGELOG.md
   git commit -m "chore: release v0.3.0"
   git tag v0.3.0
   git push origin main v0.3.0

6. Pushing the tag triggers .github/workflows/release.yml, which runs the test suite, builds the package, and publishes to PyPI using the PYPI_API_TOKEN secret — nothing else to do manually.

Development process

This project is built with Claude Code using the Superpowers plugin as its development framework — brainstorming a design spec, writing an implementation plan, then executing it task-by-task with subagent-driven TDD and code review before each merge.

License

MIT — see LICENSE.