412 lines
10 KiB
Markdown
412 lines
10 KiB
Markdown
# 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
|
|
```bash
|
|
go build ./cmd/chess-client-cli
|
|
# or with make: make build client
|
|
```
|
|
|
|
## Running
|
|
```bash
|
|
# 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).
|