terminal-chess

Play chess in your terminal against the Stockfish Online REST API. No install, no config — one command and you're playing.

npx terminal-chess

Features

• Zero install — run it anywhere with npx
• Arrow-key menus for difficulty and color selection
• Three difficulty levels: Easy, Medium, Hard
• Standard algebraic notation input (e.g. e4, Nf3, Bxc6, O-O)
• Move validation with clear error messages (invalid move, illegal move, king in check, ambiguous move)
• Game-end detection: checkmate, stalemate, draw by insufficient material / fifty-move rule / repetition
• In-game commands: board, help, resign

Requirements

• Node.js 18 or newer (for built-in fetch)
• Internet connection (calls the Stockfish Online API)

Usage

npx terminal-chess

1. Select difficulty with ↑/↓ arrow keys and press Enter.
2. Select your color (White or Black) the same way.
3. Enter moves in standard notation when prompted.

Prefer a local install?

npm install -g terminal-chess
terminal-chess

In-game commands

| Command | Action | | -------- | ----------------------------------- | | board | Print the current board position | | help | Show notation and command reference | | resign | Forfeit the game |

Example session

  Choose difficulty: Hard
  Your color : White

  1. Player : e4
  1... Computer: e5
  2. Player : Nf3
  2... Computer: Nc6
  ...
  Checkmate! Game won by Player.

How it works

Moves are parsed and validated locally with chess.js; the engine's replies come from the free Stockfish Online API:

GET https://stockfish.online/api/s/v2.php?fen=<FEN>&depth=<1-15>

Search depth is controlled by difficulty: Easy = 5, Medium = 10, Hard = 15.

License

MIT