cutechess-cli(6)

CUTECHESS-CLI(6)

Games Manual

CUTECHESS-CLI(6)

NAME

cutechess-cli — Automate chess engine tournaments

SYNOPSIS

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

DESCRIPTION

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.

Engine Options

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

EXAMPLES

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.

AUTHORS

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

RESOURCES

Project page: http://github.com/cutechess/cutechess

June 28, 2020

Linux 6.12.85-6.12-alt1