Documentation

Learn how to install, configure, and play chess in your terminal.

A minimal, elegant command-line tool that lets you solve Lichess puzzles, play full games against a local AI, or challenge a friend in multiplayer, directly in your terminal.

Built for developers and terminal power users who want a quick chess fix without leaving their command line. No account required, no configuration needed.

Features

  • Zero auth: No Lichess account required.
  • Multiplayer: Challenge a friend to a game over the internet.
  • Graphical Board: Optional high-fidelity Unicode rendering with colored squares for modern terminals.
  • Local-first: All user data (stats, history) lives on your machine.
  • Local AI: Play full games vs Stockfish (downloads on first use).
  • Game Resume: Automatically save your AI games and resume them later.
  • Self-updating: Includes a command to update to the latest version.
  • Single binary: Fast, self-contained executable.

Installation

macOS and Linux

Install chesshell using our quick installer script:

curl -fsSL https://chesshell.pages.dev/install.sh | bash

Windows

Open PowerShell as an Administrator and run the following command to automatically download and install chesshell and add it to your PATH:

iwr -useb https://chesshell.pages.dev/install.ps1 | iex

Usage

Play the Daily Puzzle

Fetch today's featured puzzle from Lichess and start an interactive session:

chesshell play --puzzle

Play against Local AI

Play a full chess game directly in your terminal against Stockfish. You can select your difficulty and your preferred color (White or Black).

chesshell play --ai

Play with a Friend

Challenge a friend to a multiplayer game. One player hosts and gets a game ID, and the other joins.

# Player 1 hosts the game
chesshell play --friend

# Player 2 joins using the ID from Player 1
chesshell play --join <game-id>

Resume a Game

If you close your terminal during an AI game, you can pick up exactly where you left off:

chesshell resume

Graphical Board (Unicode)

chesshell automatically detects if your terminal supports graphical pieces. You can manually override this or save your preference:

  • Force once: chesshell play --unicode
  • Save preference: chesshell config unicode on (or off)

View Stats and History

Check your aggregate stats or a table of your most recent attempts:

chesshell stats
chesshell history

Update the Tool

Check for a new release and automatically update the binary:

chesshell update

How It Works

chesshell interacts with the public, unauthenticated endpoints of the Lichess API to fetch puzzle data.

For AI games, it runs Stockfish locally via the UCI protocol. If Stockfish is not found on your system PATH, chesshell caches a downloaded copy under your OS config directory.

Multiplayer games are facilitated by a serverless backend running on Cloudflare, which relays moves between players.

Input Format

When playing, enter moves using UCI (Universal Chess Interface) notation.

  • Example: e2e4 (moves a piece from e2 to e4)
  • Captures: f3d5 (moves piece to capture on d5)
  • Promotion: e7e8q (promotes to queen)

Type hint (or h) in puzzles to see the starting square of the correct move. Type quit (or q) to abandon a session.

Uninstalling

To completely remove chesshell, its local data, and cached engine:

chesshell uninstall

License

This project is licensed under the MIT License - see the LICENSE file for details.

A minimal, high-performance chess tool for the terminal. chesshell is designed to provide a distraction-free environment for chess puzzles and AI games, prioritizing speed, local-first data persistence, and zero-configuration setup.

Architecture Overview

The project is structured into several modular packages within the internal/ directory, following standard Go project layouts. The multiplayer backend is a serverless Cloudflare Worker.

Go Application (internal/)

  • internal/board: The core state machine. It wraps the github.com/corentings/chess library to manage game logic and implements both graphical (Unicode) and classic (ASCII) terminal rendering pipelines.
  • internal/engine: Manages communication with the Stockfish chess engine via the UCI protocol. It handles the automatic downloading, caching, and execution of platform-specific Stockfish binaries.
  • internal/api: A thin client for the Lichess.org API's public, unauthenticated endpoints to fetch chess puzzles.
  • internal/store: The local-first persistence layer. All user data (stats, history, config, and game state) is stored in a single data.json file.
  • internal/update: The self-update system. It checks for new releases on GitHub, finds the correct binary for the user's OS/architecture, and replaces the current executable.
  • internal/relay: The client-side logic for the multiplayer feature. It communicates with the Cloudflare Worker via REST (to create/join games) and WebSockets (to exchange moves).

Serverless Backend (relay/)

The relay/ directory contains a Cloudflare Worker that acts as a simple, "dumb pipe" message broker for multiplayer games. It uses Durable Objects to manage game rooms and forward WebSocket messages between two clients without any server-side chess logic.

Project Structure

├── cmd/                # Cobra command definitions (entry points)
├── internal/
│   ├── api/            # Lichess API integration
│   ├── board/          # Board logic and ASCII/Unicode rendering
│   ├── engine/         # Stockfish process management & binary downloader
│   ├── puzzle/         # Session managers for Puzzles and AI Games
│   ├── relay/          # (v3) Multiplayer client for the relay server
│   ├── store/          # JSON persistence and data models
│   └── update/         # (v3) Self-update logic
├── relay/              # (v3) Cloudflare Worker for the multiplayer relay
├── main.go             # Application entry point
├── install.sh          # Installer script
└── data.json           # (Created at runtime) Local state & config

Development & Contribution

Prerequisites

  • Go: 1.22 or higher.
  • Git: For version control.
  • Node.js & Wrangler: Required for developing the multiplayer relay server.
  • Stockfish: (Optional) The tool will download it automatically, but you can use a system-installed version if available in your PATH.

Building from Source

git clone https://github.com/Killiivalavan/chesshell-cli.git
cd chesshell-cli
go build -o chesshell main.go

Testing the Full Stack (including Multiplayer)

To test all features, you need to run the Go application and the multiplayer relay server simultaneously.

  1. Run the relay server: 
    cd relay/
npm install
npm run dev

    This will start a local server on http://localhost:8787.

  2. Run the Go application:

    In a separate terminal, you can now run go run main.go play --friend or use the compiled binary to test multiplayer functionality against the local relay.

Core Principles for Contributors

When contributing, please adhere to these architectural constraints:

  • Minimalism: Avoid adding dependencies. Prefer the Go standard library or high-quality, lightweight packages.
  • Zero Config: Features should work immediately. If a feature requires configuration, provide sensible defaults and an interactive setup.
  • Local-First: Never require a network connection for features that don't strictly need it (like AI games or stats).
  • Non-Destructive Migrations: When updating data.json schemas, ensure old versions are migrated without data loss.

Code Style

  • Run go fmt ./... before committing.
  • Ensure all exported symbols have concise, descriptive comments.
  • Keep the cmd/ package thin; move business logic into internal/.

Data Schema (data.json)

The application persists data using the following schema:

  • config: User preferences (e.g., unicode mode).
  • stats: Aggregate win/loss and solve counts.
  • aiGames: Specific records for games against Stockfish.
  • multiplayerGames: (v3) Records for multiplayer matches.
  • currentGame: Mid-game state (FEN and difficulty) to support the Resume feature.
  • history: A rolling buffer of the last 200 puzzle attempts.

License

This project is licensed under the MIT License. See LICENSE for details.