yahtzee-li (yaht-CLI)

A professional-grade, colorful CLI Yahtzee game for 1–4 players, built in Python with rich.

Features

• Full Yahtzee rule set: upper-section bonus (35 pts at ≥63), Yahtzee bonus (+100 per extra Yahtzee), and the official joker rule
• Vivid terminal UI: ASCII-art dice panels, live multi-player scorecards, and a victory screen
• 1–4 human players per game
• "Play again" prompt after each game — keep the same players or start fresh

Requirements

• Python 3.12+
• uv (recommended) or any virtual-environment manager

Installation

From PyPI

pip install yahtzee-li

Or with uv:

uv tool install yahtzee-li

From source (development)

git clone https://github.com/carlmatt/yahtzee-li.git
cd yahtzee-li
uv sync

Running the game

# With uv / the project virtual environment
uv run yahtzee-li

# Or activate the venv first
source venv/bin/activate
yahtzee-li

Development

# Install dev dependencies
make install

# Run the game
make run

# Run the full test suite (unit + integration)
make test

# Run only one tier
make test-unit
make test-integration

# Run tests with coverage report
make test-cov

# Lint and format (combined)
make fix

# Lint only
make lint

# Format only
make format

# Type check (Astral's ty)
make typecheck

# Lint + typecheck + test
make check

# Remove cache and build artifacts
make clean

Tests

Tests are organised into two folders:

• tests/unit/ — fast unit tests that mock collaborators and cover individual modules.
• tests/integration/ — end-to-end tests that drive a real Game through full flows using a scripted Display double and a deterministic dice RNG. Tests in this folder are auto-marked with @pytest.mark.integration, so you can also run them via pytest -m integration.

Pre-commit hooks

This project uses pre-commit to enforce code quality on every commit. The hooks run ruff (lint) and ruff-format automatically.

# Install the git hooks (once, after cloning)
pre-commit install

# Run all hooks manually against every file
pre-commit run --all-files

How to Play

1. Enter the number of players (1–4) and each player's name.
2. On each turn, all five dice are rolled automatically.
3. After each roll you may hold any dice by entering their numbers (e.g. 1,3,5), press Enter to hold none, or enter d to skip straight to scoring.
4. After up to three rolls, choose a scoring category from the numbered list.
5. The game runs for 13 rounds; the player with the highest grand total wins.
6. Press Ctrl-C at any time to quit.

Scoring Reference