chess-cli

chess-cli tracks a standard chess game while a human moves pieces on a physical board and an LLM or Stockfish supplies the opponent's moves.

Requirements

For the default LLM mode:

• Ollama, OpenAI, or another server exposing POST /v1/chat/completions
• A model name

For Stockfish mode:

• Install Stockfish separately and ensure the stockfish executable is available on PATH

The application does not download or bundle Stockfish.

For OpenAI, set the API key in the environment before starting the program:

$env:OPENAI_API_KEY = "your-key"

API keys are never stored in the application config file.

Run

LLM mode is the default. Ollama is the default provider and the opponent plays black by default:

chess-cli --model gemma4:31b

Use OpenAI and have the model open as white:

chess-cli --provider openai --model your-model --opponent-color white

Choose the model's reasoning level for this run (the default is medium):

chess-cli --reasoning-effort high

Print the model's raw reasoning and response before each move:

chess-cli --model gemma4:31b --debug

Use any OpenAI-compatible endpoint:

chess-cli --provider compatible --url http://localhost:8080/v1 --model local-model

Load a game and automatically save it when the game ends:

chess-cli --provider ollama --model gemma4:31b --load game.pgn --save finished.pgn

Use Stockfish at full skill with one second of search time per move:

chess-cli --mode stockfish

Choose either a Stockfish skill level from 0 through 20 or an Elo limit from 1320 through 3190:

chess-cli --mode stockfish --stockfish-skill 10 --stockfish-movetime 500
chess-cli --mode stockfish --stockfish-elo 1800 --opponent-color white

--stockfish-skill and --stockfish-elo select mutually exclusive strength modes and cannot be supplied together. Stockfish settings are invalid in LLM mode, and LLM provider options are invalid in Stockfish mode. The older --llm-color option remains available as an alias for --opponent-color but cannot be used at the same time.

Run chess-cli --help for all startup options.

Playing

Enter a legal move in Standard Algebraic Notation, such as e4, Nf3, O-O, or Qh4#. The configured opponent color moves automatically after a human move. LLM responses are checked against the legal moves; an invalid response is retried up to three times without changing the board. Stockfish moves are received through its UCI protocol and checked by the same chess rules before being applied.

Interactive commands:

• /move asks the configured opponent to make exactly one move for the current side, then returns to the prompt. This supports switching sides or manually advancing computer-vs-computer play.
• /board displays the current ASCII board.
• /save [path] saves the current game. .pgn writes PGN; .txt and extensionless paths write numbered SAN movetext.
• /new starts over after confirming any unsaved moves can be discarded.
• /help shows command help.
• /quit exits, confirming first if moves have not been saved.

LLM-mode commands:

• /provider ollama|openai|compatible switches provider.
• /model <id> changes the current provider's model.
• /url <uri> changes the current provider's API base URL.
• /reasoning <low|medium|high> changes the current provider's reasoning level.

Stockfish-mode commands:

• /skill <0-20> selects Stockfish skill mode and changes the skill level.
• /elo <1320-3190> selects Stockfish Elo-limited mode.
• /movetime <milliseconds> changes the positive search time per move.

Mode-specific commands are rejected in the other mode. Provider profiles and Stockfish settings changed by interactive commands are persisted under the user's application-data directory at chess-cli/config.json. Startup arguments override those preferences for one run only; --mode itself is never persisted and defaults to llm on every launch.