GitHub - thomas-mauran/chess-tui: Play chess in the terminal. Rust TUI, Stockfish, Lichess.

Chess in the terminal. Free, cross-platform terminal chess game in Rust. Local play, Stockfish, Lichess. 🦀

Description · Quick Install · Features · Quick Start · Controls · Documentation · Platforms · FAQ · Contributing

Description

chess-tui is a free, open-source terminal chess game. Play with a friend locally, against any UCI chess engine (e.g. Stockfish), or online via Lichess. Runs on macOS, Linux, and Windows.

Quick Install

Homebrew:

brew install thomas-mauran/tap/chess-tui
chess-tui

Cargo:

cargo install chess-tui
chess-tui

Debian/Ubuntu:

DEB_URL=$(curl -s "https://api.github.com/repos/thomas-mauran/chess-tui/releases/latest" | jq -r '.assets[] | select(.name | endswith(".deb")) | .browser_download_url') && curl -LO "$DEB_URL" && sudo dpkg -i "$(basename "$DEB_URL")" && sudo apt-get install -f
chess-tui

Available on:

For installation via package managers or other methods, see the Installation Guide.

Features

Local 2 player mode

Chess TUI local two-player mode in terminal

Play against any UCI chess engine

Playing against UCI chess engine (e.g. Stockfish) in terminal

Lichess Integration

Play online on Lichess directly from your terminal!

See Lichess Features for details.

Online multiplayer

Helper menu

Custom skins

Quick Start

Connect a chess engine:

# Simple engine path
chess-tui -e /path/to/engine

# Engine with command-line arguments (e.g., GNU Chess with UCI mode)
chess-tui -e "/opt/homebrew/bin/gnuchess --uci"

# Stockfish example
chess-tui -e /opt/homebrew/bin/stockfish

See Bot Configuration for details.

Configure Lichess:

chess-tui -l YOUR_LICHESS_TOKEN_HERE

See Lichess Setup for details.

Other options: --depth 15 (engine depth), --difficulty easy|medium|hard|magnus, --no-sound. See Configuration for all flags and config file.

Controls

Key	Action
Arrow keys or h/j/k/l	Move cursor
Space	Select piece / move
Esc	Deselect or close popup
?	Help menu
s	Cycle skins
b	Back to menu
q	Quit

Press ? in-game for the full list.

Documentation

📚 Full Documentation (installation, configuration, Lichess, multiplayer).

Installation (Cargo, Homebrew, Debian/Ubuntu, Arch, NixOS, Docker, binary)
Configuration (config file, skins, bot, logging)
Lichess (seek game, join by code, ongoing games, puzzles)
Multiplayer (LAN and over the internet, e.g. with bore)

Platforms

Platform	Install
macOS	`brew install thomas-mauran/tap/chess-tui` or `cargo install chess-tui`
Linux	`cargo install chess-tui`, .deb, or binary
Arch	`pacman -S chess-tui`
NixOS	`nix-shell -p chess-tui` or install from nixpkgs
Windows	`cargo install chess-tui`

FAQ

Does it work with Stockfish? Yes. Run chess-tui -e /path/to/stockfish (see Bot Configuration).
Can I play on Lichess from the terminal? Yes. Get a Lichess API token and run chess-tui -l YOUR_TOKEN.
What is chess-tui built with? Rust, ratatui (TUI), shakmaty (chess), ruci (UCI engine support).
Where is the config? config.toml and skins.json in your config dir (e.g. ~/.config/chess-tui/ on Linux). See Configuration.

Troubleshooting

Run into issues? Check the docs: Lichess setup & troubleshooting, Bot configuration & troubleshooting. Otherwise open an issue.

Contributing

Contributions are welcome. See CONTRIBUTING.md for guidelines.