fastchess - a command-line tool for managing chess games with engines
fastchess [OPTIONS]
fastchess is a command-line tool designed to manage and orchestrate chess games between engines. It provides a range of options to configure game settings, engine parameters, concurrency, and output formats.
The following options are available:
-
-quick cmd=ENGINE1 cmd=ENGINE2 book=BOOK
Shortcut for predefined game settings involving two engines, time controls, rounds, and concurrency. -
-event NAME
Set the event name for the PGN header. -
-site NAME
Set the site name for the PGN header. -
-config [file=NAME] [discard=(true|false)] [outname=NAME] [stats=(true|false)]
Load engine configurations to resume games from previous sessions.- file - the file name to load the configuration from.
- discard - discard the loaded configuration after loading. Defaults to false. This lets you specify a filename to save the configuration to, while ignoring it for the current session.
- outname - the auto-generated file name of the config. Default is "config.json".
- stats - load the stats from the config file. Defaults to true.
-
-concurrency N
Play N games concurrently, limited by the number of hardware threads. Default value is 1. -
--compliance ENGINE [ARGS]
Check the UCI compliance of an engine by running it with the specified arguments. -
--force-concurrency
Ignore the hardware concurrency limit and force the specified concurrency. -
-rounds N
Play N rounds of games where each game within the round uses the same opening. Default value is 2. -
-games N
Play N games in each round. Default value is 2. Setting this higher than 2 does not provide meaningful results. -
-variant VARIANT
Choose between the following game variants:- standard - play Standard Chess (default)
- fischerandom - play Fischer Random Chess
-
-repeat
Set the number of games to 2. Equivalent to -games 2. -
-recover
Enables crash recovery to attempt to recover the engine after a crash and continue the tournament. -
-draw movenumber=NUMBER movecount=COUNT score=SCORE
Enables draw adjudication based on number of moves, move count, and score threshold.- NUMBER - number of moves before checking for a draw. Default is 0.
- COUNT - number of consecutive moves below the score threshold. Default is 1.
- SCORE - score threshold (in centipawns) for a draw. Default is 0.
-
-resign movecount=COUNT score=SCORE [twosided=(true|false)]
Configures engine resignation based on move count and score threshold.- twosided - if true, enables two-sided resignation. Defaults to false.
- COUNT - number of consecutive moves above the score threshold. Default is 1.
- SCORE - score threshold (in centipawns) to resign. Default is 0.
-
-maxmoves N
Enables draw adjudication if the game reaches N moves without a result. -
-openings file=NAME format=(epd|pgn) [order=ORDER] [plies=PLIES] [start=START]
Specifies an opening book file and its format for game starting positions.- format - file format, either epd or pgn.
- ORDER - order of openings (random or sequential). Default is sequential.
- PLIES - number of plies for pgn. Defaults to max available plies.
- START - starting index of the opening book. Default is 1.
-
-output format=FORMAT
Choose the output format for game results (cutechess or fastchess). Default is fastchess. -
-pgnout file=NAME notation=(san|lan|uci) [nodes=(true|false)] [seldepth=(true|false)] [nps=(true|false)] [hashfull=(true|false)] [tbhits=(true|false)] [timeleft=(true|false)] [min=(true|false)]
Export games in PGN format with specified notations and optional tracking of nodes, seldepth, and others.-
notation:
- san - Standard Algebraic Notation (default)
- lan - Long Algebraic Notation
- uci - Universal Chess Interface
-
nodes - Track node count. Default is false.
-
seldepth - Track seldepth. Default is false.
-
nps - Track nps. Default is false.
-
hashfull - Track hashfull. Default is false.
-
tbhits - Track tbhits. Default is false.
-
timeleft - Track time left at end of move. Default is false.
-
min - Minimal PGN format. Default is false.
-
-
-epdout file=NAME
Export the final position of each game in EPD format. -
-wait N
Wait N milliseconds between games. Default is 0. -
-noswap
Prevent swapping of colors. -
-reverse
Use a tournament schedule with reversed colors. -
-ratinginterval N
Set rating interval for the report. Default is 10. Set to 0 to disable. -
-scoreinterval N
For cutechess output, set interval for printing score results. Default is 1. -
-autosaveinterval N
Automatically saves the tournament state every N games. Default is 20. Set to 0 to disable. -
-sprt elo0=ELO0 elo1=ELO1 alpha=ALPHA beta=BETA model=MODEL
Set parameters for the Sequential Probability Ratio Test (SPRT).- MODEL:
- logistic - Uses regular/logistic Elo.
- bayesian - Uses BayesElo.
- normalized - Uses nElo (default).
- MODEL:
-
-srand SEED
Specify the seed for opening book randomization. -
-log file=NAME level=LEVEL compress=(true|false) realtime=(true|false)
Specify a log file with a specific log level. Set compress to true to gzip the file. Default is false.- LEVEL:
- trace
- warn (default)
- info
- err
- fatal
- LEVEL:
-
-use-affinity
Enable thread affinity for binding engines to CPU cores. -
-report penta=(true|false)
Reports pentanomial statistics (for fastchess output). Defaults to true. -
-version
Print version number and exit. -
-help
Print help message and exit. -
-each OPTIONS
Apply specified OPTIONS to both engines. -
-engine OPTIONS
Apply specified OPTIONS to the next engine.- cmd=COMMAND - Specify engine command.
- name=NAME - Set engine name (must be unique).
- args="ARGS" - Pass multiple arguments using args="ARG1 ARG2".
- tc=TC - Time control in Cute-Chess format (moves/minutes:seconds+increment).
- timemargin=N - Time margin for exceeding time limit.
- st=ST - Movetime in seconds.
- nodes=NODES - Max number of nodes to search.
- plies=PLIES - Max number of plies (depth) to search.
- proto=PROTOCOL - Specify the protocol (only supports uci).
- dir=DIRECTORY - Working directory for the engine.
- option.name=VALUE - Set engine-specific options. The value for a button option should be "true" or "false".
To start a match between two engines using random openings from book.epd:
$ fastchess -engine cmd=Engine1.exe name=Engine1 -engine cmd=Engine2.exe \
name=Engine2 -openings file=book.epd format=epd order=random \
-each tc=10+0.1 -rounds 200 -repeat -concurrency 4
fastchess was written by Disservin, Szil, PGG106, and contributors.
Report any bugs to https://github.com/Disservin/fastchess/issues.
This software is licensed under the MIT license. See the LICENSE file for details.