cutechess-cli —
Automate 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
engine-options- Add an engine defined by engine-options to the
tournament. See Engine
Options.
-each
engine-options- Apply engine-options to each engine in the
tournament. See Engine
Options.
-variant
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)
-concurrency
n- Set the maximum number of concurrent games to
n.
-draw
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.
-resign
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
-maxmoves
n- Adjudicate the game as a draw if at least n full
moves have been played without result. Ignored if n
equals zero (default).
-tb
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.
-tbpieces
N- Only use tablebase adjudication for positions with N
pieces or less.
-tbignore50- Disable the fifty move rule for tablebase adjudication.
-tournament
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
-event
arg- Set the event name to arg.
-games
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.
-rounds
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.
-sprt
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.
-ratinginterval
n- Set the interval for printing the ratings to n
games.
-outcomeinterval
n- Set the interval for printing outcomes to n
games.
-debug- Display all engine input and output.
-openings
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.
-bookmode
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.
-pgnout
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.
-epdout
file- Save the games to file in FEN format.
-recover- Restart crashed engines instead of stopping the game.
-repeat
[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.
-noswap- Do not swap sides of paired engines.
-reverse- Use schedule with reverse sides.
-seeds
n- Set the first n engines as seeds in the tournament.
The default is 0.
-site
arg- Set the site / location to arg.
-srand
seed- Set the random seed for the book move selector.
-wait
n- Wait n milliseconds between games. The default is
0.
-resultformat
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.
-version- Display the version information.
-help- Display help information.
-engines- Display a list of configured engines and exit.
conf=arg- Use an engine with the name arg from engine
configuration file.
name=arg- Set the name to arg.
cmd=arg- Set the command to arg.
dir=arg- Set the working directory to arg.
stderr=arg- Redirect standard error output to file arg.
proto=[uci
| xboard]- Set the chess protocol.
tc=[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.
option.name=value- Set custom engine option.
arg=arg- Pass arg to the engine as a command line
argument.
initstr=arg- Send arg to the engine's standard input at
startup.
restart=[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- Trust result claims from the engine without validation. By default all
claims are validated.
st=n- Set the time limit for each move to n seconds. This
option cannot be used in combination with the
tc
option.
timemargin=n- Let engines go n milliseconds over the time
limit.
book=file- Use file (Polyglot book file) as the opening
book.
bookdepth=n- Set the maximum book depth (in fullmoves) to n.
whitepov- Invert the engine's scores when it plays black. This option should be used
with engines that always report scores from white's perspective.
ponder- Enable pondering if the engine supports it.
depth=plies- Set the search depth limit.
nodes=count- Set the node count limit.
tscale=factor- Scale engine timeouts by factor. Only use this
option if necessary.
debug- 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
- Use the name=Atak parameter because it's a Xboard protocol 1 engine and
doesn't tell its name.
- Use the dir=C:\atak parameter to point the location of the
executable.
- Glaurung can tell its name and is in the PATH variable so only the command
is needed.
- Set Glaurung to use 1 thread.
- Set the time control to 40 moves in one minute and 30 seconds with one
second increment.
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
- Play two games per encounter, effectively multiplying the number of games
by 2.
- Play 10 times the minimum amount of rounds (3). So the total number of
rounds to play will be 30, and the total number of games 120.
- In each two-game encounter colors are switched between games and the same
opening line is played in both games.
The cutechess-cli utility was written by
Ilari Pihlajisto,
Arto Jonsson and contributors. See the project page
for more details.