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 Mor
		  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=<alpha> beta=<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 <alpha> and
	     <beta>.

	     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

     o	 Use the name=Atak parameter because it's a Xboard protocol 1 engine
	 and doesn't tell its name.

     o	 Use the dir=C:\atak parameter to point the location of the
	 executable.

     o	 Glaurung can tell its name and is in the PATH variable so only the
	 command is needed.

     o	 Set Glaurung to use 1 thread.

     o	 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

     o	 Play two games per encounter, effectively multiplying the number of
	 games by 2.

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

     o	 In each two-game encounter colors are switched between games and the
	 same opening line is played in both games.

SEE ALSO
     cutechess-engines.json(5)

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

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

Debian				 June 28, 2020				Debian
