Table of contents

• 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

Play against any UCI chess engine

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.

Links

• 📦 Crates.io
• 📖 Documentation
• 📋 Releases (changelog)
• 🗺️ Roadmap
• 🐛 Report Issues
• ⭐ Star the repo if you find it useful; it helps others find it.

---

Terminal chess · Chess in the terminal · Chess CLI · Command line chess · Rust TUI · UCI engine · Lichess · Stockfish · ratatui