clisudoku

A fully-featured Sudoku game that lives entirely in your terminal.

About

Some programs just feel right when they run in a terminal — no mouse required, pure keyboard flow, instant response. Sudoku is one of them. This project grew out of a love for that kind of software: the kind where every key press does exactly what you expect, where the interface gets out of the way, and where you can sit down, focus, and think.

Features

• 6 difficulty levels — Easy · Medium · Hard · Extreme · Expert · Sparse
• Hint system — step-by-step hints with cause / elimination / target highlighting (20+ strategies)
• Notes mode — pencil marks per cell, auto-cleared on digit entry
• Undo / redo — full move history
• Auto-save & resume — every move is written to a local SQLite database; resume any game from the Continue menu
• Highscores — solve times ranked per difficulty, plus your own 0–9 puzzle rating
• Passive scan — highlights all cells with the same digit as the cursor
• Mouse support — click to select, hover highlights the cell
• 3 colour themes — Dark (default) · Light · High Contrast (colourblind-safe)
• 13 interface languages — EN · DE · ES · IT · FR · SL · EO · TP · Leet · SW · AF · PY · ID
• 2 digit styles — Retro · Awkward-Retro
• Boss key — disguises the game as a terminal session showing your home directory (B)
• Configurable keybindings — via ~/.config/clisudoku/config.toml
• Load a custom puzzle — paste an 81-char string or point to a file
• Custom cell patterns — generate puzzles from an 81-char pattern mask

Requirements

• Rust 1.70+
• A terminal with 16-colour ANSI support (xterm, iTerm2, Windows Terminal, …)
• Minimum terminal size: 117 × 39 characters

Installation

git clone https://github.com/DocAtPrompt/clisudoku.git
cd clisudoku
cargo build --release
# Binary: target/release/clisudoku

Or install globally:

cargo install --path .

Usage

clisudoku [OPTIONS]

Options:
  -s <PUZZLE>         Load puzzle from 81-char string (1-9 = given, 0/. = empty)
  -f <FILE>           Load puzzle from text file (same format as -s)
  -p, --pattern <81C> Generate puzzle from a custom cell-pattern mask
  -t <NAME>           Colour theme: dark (default) | light | high-contrast
  -l <CODE>           Language: en de es it fr sl eo tp leet sw af py id
  --difficulty <L>    Starting difficulty: easy medium hard extreme expert
                      (Sparse is only selectable from the in-game menu)
  --digit-style <S>   Digit style: retro (default) | awkward-retro
  --config <PATH>     Config file (default: ~/.config/clisudoku/config.toml)
  --db <PATH>         SQLite database file (default: ~/.config/clisudoku/clisudoku.db)

Examples

# Start with a specific puzzle
clisudoku -s 530070000600195000098000060800060003400803001700020006060000280000419005000080079

# Generate a puzzle using a custom cell pattern (1/* = given position, ./0 = empty)
clisudoku -p "1000100010001000100010001000100010001000100010001000100010001000100010001000100010001"

# Light theme, German interface
clisudoku -t light -l de

# High-contrast theme, start on Hard
clisudoku -t high-contrast --difficulty hard

# Use a config file from a custom path
clisudoku --config ~/dotfiles/clisudoku.toml

Controls

Key	Action
↑ ↓ ← →	Move cursor
1–9	Enter digit
0	Toggle notes / digit mode
-	Clear cell
U / R	Undo / Redo
/ *	Undo / Redo (numpad)
H	Request hint
S	Toggle passive scan
E	Toggle error highlighting
Space	Pause
M	Toggle mouse mode
B	Boss key — disguises game as a terminal session
?	Help screen (controls, rules, colour reference)
Q / Esc	Quit / Back

Quick navigation: press Enter + a numpad key to select a 3×3 box, then another numpad key to land on the exact cell — no arrow-key hammering needed.

Difficulty levels

Level	What it requires
Easy	Naked & hidden singles only
Medium	Naked pairs, box-line reduction
Hard	X-Wing
Extreme	Swordfish, Jellyfish
Expert	XY-Wing, XYZ-Wing, chains, unique rectangles, …
Sparse	As few clues as possible — near the theoretical minimum of 17

Saving & scores

clisudoku keeps your games in a local SQLite database — by default ~/.config/clisudoku/clisudoku.db. Nothing leaves your machine.

• Auto-save — the game is saved after every move, so you can quit any time and lose nothing.
• Continue — the start menu lists every saved game (newest first) with its difficulty and elapsed time; Enter resumes it, Del deletes it. The timer picks up exactly where you left off.
• Save & rate on quit — solving a puzzle (or leaving it) opens a dialog to store the result and rate the puzzle 0–9; Enter saves, N skips.
• Highscores — a start-menu screen with per-difficulty tabs (Easy · Medium · Hard · Extreme · Expert · Sparse · All), showing the top 10 solve times.

Point --db <PATH> (or [storage] db_path in the config file) at a different file to keep separate score sets or share one across machines.

# Keep a separate database for a second player
clisudoku --db ~/sudoku/alice.db

Configuration

~/.config/clisudoku/config.toml:

[appearance]
theme = "dark"          # dark | light | high-contrast
language = "en"         # en de es it fr sl eo tp leet sw af py id
digit_style = "retro"   # retro | awkward-retro

[storage]
# Override the SQLite database location (default: ~/.config/clisudoku/clisudoku.db).
# Use an absolute path — "~" is not expanded here.
db_path = "/home/you/sudoku/clisudoku.db"

[keys]
hint = "h"
pause = " "
scan = "s"
errors = "e"
undo = "z"
redo = "y"

# Override individual colours (applied on top of the chosen theme).
# Valid colour names: Black, DarkGrey, Red, DarkRed, Green, DarkGreen,
#   Yellow, DarkYellow, Blue, DarkBlue, Magenta, DarkMagenta,
#   Cyan, DarkCyan, White, Grey
[colors]
digit_user = "Cyan"           # colour for digits you entered
digit_given = "White"         # colour for pre-filled (given) digits
digit_error = "Red"           # colour for conflicting digits
digit_scan = "Magenta"        # colour for passive-scan highlights
ui_cursor_bg = "DarkBlue"     # cursor / selected-tab background
cell_active_box_bg = "DarkBlue"   # same-box highlight background
hint_cause_border = "Green"   # hint: cause cell border
hint_elim_border = "Red"      # hint: elimination cell border
hint_target_bg = "Yellow"     # hint: target cell background

Upcoming

Features planned for future releases:

• Network challenge — play head-to-head against others on the same puzzle in real time
• X-Sudoku — diagonal constraint variant (both main diagonals must also contain 1–9)
• Killer Sudoku — cage constraints with sum targets instead of given digits

License

MIT

---

Built with ❤️ and support from Claude.