CUTECHESS-CLI(6) Games Manual CUTECHESS-CLI(6)

cutechess-cliAutomate chess engine tournaments

cutechess-cli -engine engine-options -engine engine-options [-engine engine-options ...] [options]

The cutechess-cli utility automates chess engine tournaments.

Its options are as follows:

engine-options
Add an engine defined by engine-options to the tournament. See Engine Options.
engine-options
Apply engine-options to each engine in the tournament. See Engine Options.
variant
Set the chess variant, where variant is one of:

3check
Three-check Chess
5check
Five-check Chess
ai-wok
Ai-Wok (Makruk variant)
almost
Almost Chess
amazon
Amazon Chess
andernach
Andernach Chess
antiandernach
Anti-Andernach Chess
antichess
Antichess / Losing Chess
asean
ASEAN-Chess
atomic
Atomic Chess
berolina
Berolina Chess
cambodian
Ouk Chatrang (Cambodian Chess)
capablanca
Capablanca Chess
caparandom
Capablanca Random Chess
cfour
Cfour (7x6, line up 4 to win)
chancellor
Chancellor Chess (9x9)
changeover
Change-Over Chess
checkless
Checkless Chess
chessgi
Chessgi / Drop Chess
chigorin
Chigorin Chess
circulargryphon
Circular Gryphon Chess
codrus
Game of Codrus (Losing Chess Variant)
coregal
Co-regal Chess
courier
Courier Chess (Medieval)
crazyhouse
Crazyhouse (Drop Chess Variant)
displacedgrid
Displaced Grid Chess
dobutsu
Dobutsu Shogi (3x4)
embassy
Embassy Chess
euroshogi
EuroShogi (8x8)
extinction
Extinction Chess
fischerandom
Fischer Random Chess / Chess 960
giveaway
Giveaway Chess (Losing Chess)
gomoku
Gomoku (15x15, exactly 5 in a row to win)
gomokufreestyle
Gomoku Free-Style (5 in a row to win)
gothic
Gothic Chess
grand
Grand Chess
grid
Grid Chess
gridolina
Berolina Grid Chess
gryphon
Gryphon Chess
gustav3
Gustav III's Chess
hoppelpoppel
Hoppel-Poppel (has N/B hybrids)
horde
Horde Chess (v2)
janus
Janus Chess
jesonmor
Jeson Mör
judkins
Judkins Shogi (6x6)
karouk
Kar Ouk (One-check Ouk)
kinglet
Kinglet Chess
kingofthehill
King of the Hill Chess
knightmate
Knightmate
knightrelay
Knight-Relay Chess
loop
Loop Chess (Drop Chess Variant)
losalamos
Los Alamos Chess
losers
Loser's Chess
makruk
Makruk (Thai Chess)
minishogi
Minishogi (5x5)
modern
Modern Chess (9x9)
newzealand
New Zealand Chess (has N/R hybrids)
placement
Placement Chess
pocketknight
Pocket Knight Chess
racingkings
Racing Kings Chess
rifle
Rifle Chess
seirawan
S-Chess (Seirawan Chess)
shatranj
Shatranj
shogi
Shogi
shoot
Shoot Chess
simplifiedgryphon
Simplified Gryphon Chess
sittuyin
Sittuyin (Myanmar Chess)
slippedgrid
Slipped Grid Chess
suicide
Suicide Chess (Losing Chess Variant)
superandernach
Super-Andernach Chess
threekings
Three Kings Chess
tictactoe
Tic-tac-toe
twokings
Two Kings Each Chess (Wild 9)
twokingssymmetric
Symmetrized Wild 9
standard
Standard Chess (default)
n
Set the maximum number of concurrent games to n.
movenumber=number movecount=count score=score
Adjudicate the game as draw if the score of both engines is within score centipawns from zero for at least count consecutive moves, and at least number full moves have been played. Captures and pawn moves will reset the counters.
movecount=count score=score [twosided=value]
Adjudicate the game as a loss if an engine's score is at least score centipawns below zero for at least count consecutive moves. If value is true (default: false) then activate two-sided resign adjudication. The winning side's scores must be at least score centipawns above zero for at least count consecutive moves
n
Adjudicate the game as a draw if at least n full moves have been played without result. Ignored if n equals zero (default).
paths
Adjudicate games using Syzygy tablebases. Paths should be semicolon-delimited list of paths to the compressed tablebase files. Only the WDL tablebase files are required.
N
Only use tablebase adjudication for positions with N pieces or less.
Disable the fifty move rule for tablebase adjudication.
type
Set the tournament type, where type is one of:

round-robin
Round-robin tournament (default)
gauntlet
First engine(s) against the rest
knockout
Single-elimination tournament
pyramid
Every engine plays against all of its predecessors
arg
Set the event name to arg.
n
Play n games per encounter. This value should be set to an even number in tournaments with more than two players to make sure that each player plays an equal number of games with white and black pieces.
n
Multiply the number of rounds to play by n. For two-player tournaments this option should be used to set the total number of games to play.
elo0=E0 elo1=E1 alpha=α beta=β
Use a Sequential Probability Ratio Test as a termination criterion for the match.

This option should only be used in matches between two players to test if engine P1 is stronger than engine P2. Hypothesis H1 is that P1 is stronger than P2 by at least E0 ELO points, and H0 (the null hypothesis) is that P1 is not stronger than P2 by at least E1 ELO points. The maximum probabilities for type I and type II errors outside the interval [ E0, E1 ] are α and β.

The match is stopped if either H0 or H1 is accepted or if the maximum number of games set by -rounds and / or -games is reached.

n
Set the interval for printing the ratings to n games.
n
Set the interval for printing outcomes to n games.
Display all engine input and output.
file=file format=[epd | pgn] order=[random | sequential] plies=plies start=start policy=[default | encounter | round]
Pick game openings from file. The file can be either in epd (Extended Position Description) or pgn (Portable Game Notation) format. The default format is pgn. Openings can be picked in random or sequential (default) order. The opening depth is limited to plies number of plies. If plies is not set the opening depth is unlimited. In sequential mode start is the number of the first opening that will be played. The minimum value for start is 1 (default).

The value of policy rules when to shift to a new opening. If set to encounter a new opening is used for any new pair of players, round shifts when a new round begins. The default shifts for any new pair of players and also when the specified number of opening repetitions is reached.

mode
Set Polyglot book access mode, where mode is either ram (the whole book is loaded into RAM) or disk (the book is accessed directly on disk). The default mode is ram.
file [min] [fi]
Save the games to file in PGN format. Use the min argument to save in a minimal PGN format. Only finished games will be saved if argument fi is given.
file
Save the games to file in FEN format.
Restart crashed engines instead of stopping the game.
[n]
Play each opening twice (or n times). Unless the -noswap option is used, the players swap sides after each game. So they get to play the opening on both sides. Please note that a new encounter will use a new opening.
Do not swap sides of paired engines.
Use schedule with reverse sides.
n
Set the first n engines as seeds in the tournament. The default is 0.
arg
Set the site / location to arg.
seed
Set the random seed for the book move selector.
n
Wait n milliseconds between games. The default is 0.
format
Specify the format of result lists. Format can either be a comma separated list of fields or a format name. Format help shows available named formats. The default format lists rank, name, elo, elo error, number of games, score percentage, and draw percentage of every player.
Display the version information.
Display help information.
Display a list of configured engines and exit.

=arg
Use an engine with the name arg from engine configuration file.
=arg
Set the name to arg.
=arg
Set the command to arg.
=arg
Set the working directory to arg.
=arg
Redirect standard error output to file arg.
=[uci | xboard]
Set the chess protocol.
=[tcformat | inf]
Set the time control. The format is moves/time+increment, where moves is the number of moves per tc, time is time per tc (either seconds or minutes:seconds), and increment is the time increment per move in seconds.

Infinite time control can be set with inf.

name=value
Set custom engine option.
=arg
Pass arg to the engine as a command line argument.
=arg
Send arg to the engine's standard input at startup.
=[auto | on | off]
Set the engine restart mode. auto means the engine decides whether to restart (default), on means the engine is always restarted between games and off means the engine is never restarted between games. Setting this option does not prevent engines from being restarted between rounds in a tournament featuring more than two engines.
Trust result claims from the engine without validation. By default all claims are validated.
=n
Set the time limit for each move to n seconds. This option cannot be used in combination with the tc option.
=n
Let engines go n milliseconds over the time limit.
=file
Use file (Polyglot book file) as the opening book.
=n
Set the maximum book depth (in fullmoves) to n.
Invert the engine's scores when it plays black. This option should be used with engines that always report scores from white's perspective.
Enable pondering if the engine supports it.
=plies
Set the search depth limit.
=count
Set the node count limit.
=factor
Scale engine timeouts by factor. Only use this option if necessary.
Activate debug mode (per protocol, UCI only).

Play ten games between two Sloppy engines with a time control of 40 moves in 60 seconds:

$ cutechess-cli -engine cmd=sloppy -engine cmd=sloppy -each proto=xboard tc=40/60 -rounds 10

Play a single game between Atak and Glaurung engines with a time control of 40 moves in one minute and 30 seconds with one second increment:

$ cutechess-cli -engine name=Atak cmd=Atak32.exe dir=C:\atak proto=xboard -engine cmd=glaurung proto=uci option.Threads=1 -each tc=40/1:30+1

Play a Round-Robin tournament between Fruit, Crafty, Stockfish and Sloppy:

$ cutechess-cli -engine conf=Fruit -engine conf=Crafty -engine conf=Stockfish -engine conf=Sloppy -each tc=4 book=book.bin -games 2 -rounds 10 -repeat

cutechess-engines.json(5)

The cutechess-cli utility was written by Ilari Pihlajisto,
Arto Jonsson and contributors. See the project page for more details.

June 28, 2020 Debian