clidoku

 ██████╗██╗     ██╗██████╗  ██████╗ ██╗  ██╗██╗   ██╗
██╔════╝██║     ██║██╔══██╗██╔═══██╗██║ ██╔╝██║   ██║
██║     ██║     ██║██║  ██║██║   ██║█████╔╝ ██║   ██║
██║     ██║     ██║██║  ██║██║   ██║██╔═██╗ ██║   ██║
╚██████╗███████╗██║██████╔╝╚██████╔╝██║  ██╗╚██████╔╝
 ╚═════╝╚══════╝╚═╝╚═════╝  ╚═════╝ ╚═╝  ╚═╝ ╚═════╝

    A simple command-line sudoku game

clidoku is a command-line sudoku game for your terminal. Not a sudoku solver!

Made completely for fun, so that you can waste time without leaving the comfort of your terminal.

Built by Barney Jackson using only Python's standard library, and finished with the help of Augment code agent.

Quick Start

Install

brew tap barneyjackson/clidoku
brew install clidoku

Play

# Start a new game
clidoku new

# Add a number to cell a0 (top-left corner)
clidoku add a0 5

# Show current game (games auto-save)
clidoku show

Usage

Games automatically save to ~/.clidoku/savegame.jsonl and resume when you return.

Supports 4x4 and 9x9 grids with Easy, Medium, and Hard difficulty levels.

Commands

# Start a new game
clidoku new                           # 9x9 medium difficulty
clidoku new --difficulty easy         # easier puzzle
clidoku new --grid-size 4             # 4x4 grid

# Playing (coordinates: rows a-i, columns 0-8)
clidoku add a0 5                      # add number 5 to cell a0
clidoku remove a0                     # remove number from cell a0
clidoku show                          # display current game
clidoku check                         # validate current grid

# Aliases
clidoku put a0 5                      # same as 'add'
clidoku rm a0                         # same as 'remove'
clidoku ls                            # same as 'show'
clidoku                               # same as 'show' when game exists

Installation

Homebrew

brew install clidoku

From Source

git clone https://github.com/barneyjackson/clidoku.git
cd clidoku
pip install -e .

Development

Setup

git clone https://github.com/barneyjackson/clidoku.git
cd clidoku

# Install rye (if not already installed)
curl -sSf https://rye-up.com/get | bash

# Sync dependencies
rye sync

# Run in development mode
rye run python -m clidoku.main --help

Testing

rye run pytest                        # run tests
rye run coverage run -m pytest        # with coverage
rye run coverage report               # coverage report

Code Quality

rye fmt                               # format code
rye lint                              # lint code
rye run mypy -p clidoku

Building

rye build                             # build package for distribution

Contributing

Though I don't plan to actively maintain this project, I'm open to pull requests. If you'd like to contribute, please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests and linting (rye run pytest && rye lint)
5. Submit a Pull Request

License

This project is licensed under the BSD 3-Clause License - see the LICENSE file for details.