chess/doc/client.md

Chess CLI Client Documentation

The chess client is an interactive command-line debugging tool for the chess server API. It provides a rich terminal interface with colored output, command completion, and session management.

Features

• Interactive shell with readline support and command history
• Comprehensive command set for game operations and debugging
• User authentication with JWT token management
• Colored board visualization and game state display
• Session persistence across commands
• Verbose mode for detailed API request/response inspection
• Long-polling support for real-time game updates

Replay

The Go API client exposes GetGameHistory(gameID), GetGamePGN(gameID, ply), and GetMyGames(limit, cursor), including durable result, timestamps, player claims, move count, ordered UCI and SAN moves, and FEN after every move. The games, pgn and replay commands use them. A replay renders the stored FEN of each ply; the client never computes a move.

Building

go build ./cmd/chess-client-cli
# or with make: make build client

Running

# Connect to default server (localhost:8080)
./chess-client-cli
# if built with make: bin/chess-client-cli

# The client starts with an interactive prompt
chess > 

Prompt States

The prompt dynamically updates to show context:

• chess - Base prompt
• chess [username] - Authenticated user
• chess [username - gameId] - User in active game
• chess [username - gameId] White - Shows player color
• Turn indicator with player type (h=human, c=computer)
• chess [...] replay 12/40 - Replaying a stored game at ply 12 of 40

Command Reference

Authentication Commands

register / r

Register new user account.

chess > register
Username: alice
Password: ********
Email (optional): alice@example.com

login / l

Authenticate with existing account.

chess > login
Username or Email: alice
Password: ********

logout / o

Clear authentication token.

chess > logout

whoami / i

Display current authenticated user.

chess > whoami

user / e

Set user ID manually (for display only, doesn't authenticate).

chess > user 550e8400-e29b-41d4-a716-446655440000

Game Commands

new / n

Create new game interactively.

chess > new
White player type (h/c) [h]: h
Black player type (h/c) [h]: c
Computer level (0-20) [10]: 15
Search time (100-10000ms) [1000]: 2000
Starting position (FEN) [default]: 

join / j

Set current game context.

chess > join a1b2c3d4-e5f6-7890-1234-567890abcdef

move / m

Make chess move in UCI notation. Castling is the king's move (e1g1); a promotion appends the piece letter (q, r, b, or n).

chess > move e2e4
chess > move e7e5
chess > move g7g8q

computer / c

Trigger computer move calculation.

chess > computer

undo / u

Undo one or more moves. Refused when another user claimed a side (players cannot take back each other's moves) and after a resignation or agreed draw between two humans. Against the computer a resignation can be undone; the client notes that it stays on record.

chess > undo       # Undo last move
chess > undo 3     # Undo last 3 moves

show / h

Display board and game state with colored pieces, the result, and any pending draw offer.

chess > show

state / s

Show raw game JSON response.

chess > state

delete / d

Unload a live game from server memory. Durable history remains available.

chess > delete              # Unload current live game
chess > delete <gameId>      # Unload specific live game

poll / p

Long-poll for game updates (waits up to 30 seconds). Returns on a move, an undo, a result (a resignation or an accepted draw), or a draw offer, and prints the outcome or offer. In a two-player game, poll is how you learn that the opponent moved, offered a draw, or resigned.

chess > poll

resign

Resign the current game. The side may be omitted when you play one human side (or claimed one); name it in a hot-seat game.

chess > resign
chess > resign b

draw

Offer (the default), accept, or decline a draw. A computer answers an offer at once; a human opponent sees the offer in their next response, and it lapses if they move instead of answering.

chess > draw              # offer
chess > draw accept b
chess > draw decline w

Game outcomes print with how they were reached, e.g. DRAW by threefold repetition. or Black wins by resignation.; a pending offer is shown as White offers a draw.

games / g

List your stored games, newest first, 20 per page (requires login), numbered for replay <#>. The result column is the PGN token (1-0, 0-1, 1/2-1/2, *).

chess > games        # Newest games
chess > games more   # Next page

pgn

Print a stored game as PGN (SAN movetext, standard tags), or save it with save <path>. During a replay the default is the replayed game up to the current ply.

chess > pgn                        # Current game, every ply
chess > pgn 10                     # Current game, first 10 plies
chess > pgn <gameId> [ply]         # Another game
chess > pgn save game.pgn          # Write instead of print

In the browser build there is no file system: save prints the PGN to copy.

Replay Commands

A replay steps through a stored game's history: any game by ID (histories are public to holders of the ID), or one of your own by its number in the last games listing. The replay is separate from the live session: the current game, login and poll position are kept, and new, join, move, computer, undo, delete, poll, resign and draw are refused until live ends the replay.

replay

Load a stored game and show its initial position, the players, the result, and the whole move list.

chess > replay 2                                      # From the last 'games' page
chess > replay a1b2c3d4-e5f6-7890-1234-567890abcdef   # Any stored game

next / >, prev / <, first, last, goto

Move through the line; each prints the board, the ply, and the move that led to it (2... Nf6). next and prev take a count.

chess > next
chess > next 4
chess > prev
chess > goto 12
chess > last
chess > first

auto

Play forward from the current ply to the end of the line, one board per ply, with a delay in milliseconds (default 1000).

chess > auto        # one ply a second
chess > auto 250

fen

Print the FEN of the current position.

chess > fen

show / h while replaying

Shows the replayed position instead of the live game.

live

Leave the replay and return to the live session.

chess > live

Debug Commands

health / .

Check server health status.

chess > health

url / /

Get or set API base URL.

chess > url                           # Show current URL
chess > url http://localhost:9090     # Change server URL

raw / :

Send raw API request.

chess > raw GET /api/games/<id>
chess > raw POST /api/games '{"white":{"type":1},"black":{"type":2}}'

clear / -

Clear terminal screen.

chess > clear

help / ?

Display available commands or specific command usage.

chess > help          # Show all commands
chess > help move     # Show move command details

exit / x

Exit the client.

chess > exit

Verbose Mode

Append -v flag to any command for detailed output:

chess > move e2e4 -v

Shows full HTTP request/response with formatted JSON bodies.

Session Management

The client maintains session state including:

• API base URL
• Current game ID
• Authentication token
• Username and user ID
• Last move count (for polling)
• Current game state
• Player color assignment

Session state persists across commands within the same client instance.

Display Features

Colored Output

• Blue: White pieces, API requests, prompts
• Red: Black pieces, errors
• Green: Success messages
• Yellow: Warnings, input prompts
• Magenta: Computer moves, usernames
• Cyan: Information, file coordinates
• White: Game IDs

Board Visualization

ASCII board with colored pieces:

  a b c d e f g h
8 r n b q k b n r 8
7 p p p p p p p p 7
6 . . . . . . . . 6
5 . . . . . . . . 5
4 . . . . P . . . 4
3 . . . . . . . . 3
2 P P P P . P P P 2
1 R N B Q K B N R 1
  a b c d e f g h

Move History

The live game's history is displayed in UCI notation with move numbers:

History: 1.e2e4 e7e5 2.g1f3 b8c6 3.f1b5

A replay lists the stored game in SAN, with the current ply in brackets:

1. e4 c5 2. [Nf3] Nf6 3. Nc3 e6

Workflows

Authenticated Game Creation

1. Register or login to obtain token
2. Create game (human players automatically associated with user)
3. Make moves with authentication context
4. Games persist with user association

Computer vs Computer Observation

1. Create game with both players as computer
2. Use polling to watch moves in real-time
3. Board updates automatically as engines calculate

Debug Server Testing

1. Set verbose mode for request inspection
2. Use raw command for custom API calls
3. Health endpoint for connectivity verification
4. URL switching for multi-server testing

Configuration

Environment

• History file: .chess_history in working directory
• Default API URL: http://localhost:8080
• Timeout: 30 seconds for HTTP requests

Limitations

• No move validation in client (server validates)
• No algebraic notation input (UCI format only)
• Single game context at a time (plus one replay)
• No persistent authentication across restarts
• auto runs to the end of the line; it cannot be interrupted

Error Handling

The client displays server errors with color coding:

• Red text for error messages
• Error codes for specific failures
• Details when available

Common error codes:

• GAME_NOT_FOUND - Invalid game ID
• INVALID_MOVE - Illegal chess move
• NOT_HUMAN_TURN - Wrong player type
• GAME_OVER - Game already ended
• RATE_LIMIT_EXCEEDED - Too many requests

Development

The client architecture follows a command pattern with:

• Registry: Central command dispatcher
• Session: State management interface
• API Client: HTTP communication layer
• Display: Terminal formatting utilities
• Commands: Modular command handlers

Extensions can add new commands by registering handlers in the appropriate command group (game, auth, debug).