chess-cli

chess-cli tracks a standard chess game while a human moves pieces on a physical board and an LLM supplies moves through an OpenAI-compatible API.

Requirements

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

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

Ollama is the default provider and the LLM 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 --llm-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

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 LLM color moves automatically after a human move. Model responses are checked against the legal moves; an invalid response is retried up to three times without changing the board.

Interactive commands:

• /move asks the LLM to make exactly one move for the current side, then returns to the prompt. This supports switching sides or manually advancing LLM-vs-LLM 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.
• /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 and saves the current provider's reasoning level.
• /help shows command help.
• /quit exits, confirming first if moves have not been saved.

Changes made with /provider, /model, /url, and /reasoning are persisted as per-provider profiles under the user's application-data directory at chess-cli/config.json. Startup arguments override those preferences for one run only.