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 Foundation

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 and pgn commands use them; step-by-step replay controls are still planned, see Replay Implementation Tasks.

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)

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). 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).

chess > pgn                  # Current game, every ply
chess > pgn 10               # Current game, first 10 plies
chess > pgn <gameId> [ply]   # Another game

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

Displayed in UCI notation with move numbers:

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

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
• No persistent authentication across restarts

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).