docs/cutechess-cli.6

   1 .Dd March 26, 2012
   2 .Dt CUTECHESS-CLI 6
   3 .Os
   4 .Sh NAME
   5 .Nm cutechess-cli
   6 .Nd Automate chess engine tournaments
   7 .Sh SYNOPSIS
   8 .Nm
   9 .Fl engine Ar engine-options
  10 .Fl engine Ar engine-options
  11 .Op Fl engine Ar engine-options ...
  12 .Op options
  13 .Sh DESCRIPTION
  14 The
  15 .Nm
  16 utility automates chess engine tournaments.
  17 .Pp
  18 Its options are as follows:
  19 .Bl -tag -width Ds
  20 .It Fl engine Ar engine-options
  21 Add an engine defined by
  22 .Ar engine-options
  23 to the tournament.
  24 See
  25 .Sx Engine Options .
  26 .It Fl each Ar engine-options
  27 Apply
  28 .Ar engine-options
  29 to each engine in the tournament.
  30 See
  31 .Sx Engine Options .
  32 .It Fl variant Ar variant
  33 Set the chess variant, where
  34 .Ar variant
  35 is one of:
  36 .Cm atomic ,
  37 .Cm capablanca ,
  38 .Cm caparandom ,
  39 .Cm crazyhouse ,
  40 .Cm fischerandom ,
  41 .Cm gothic ,
  42 .Cm loser
  43 or
  44 .Cm standard
  45 (default).
  46 .It Fl concurrency Ar n
  47 Set the maximum number of concurrent games to
  48 .Ar n .
  49 .It Fl draw Ar n Ar score
  50 Adjudicate the game as draw if the score of both engines is within
  51 .Ar score
  52 centipawns from zero after
  53 .Ar n
  54 full moves have been played.
  55 .It Fl resign Ar n Ar score
  56 Adjudicate the game as a loss if an engine's score is at least
  57 .Ar score
  58 centipawns below zero for at least
  59 .Ar n
  60 consecutive moves.
  61 .It Fl tournament Ar type
  62 Set the tournament type, where
  63 .Ar type
  64 is either
  65 .Cm round-robin
  66 (default) or
  67 .Cm gauntlet .
  68 .It Fl event Ar arg
  69 Set the event name to
  70 .Ar arg .
  71 .It Fl games Ar n
  72 Play
  73 .Ar n
  74 games per encounter.
  75 This value should be set to an even number in tournaments with more than two
  76 players to make sure that each player plays an equal number of games with white
  77 and black pieces.
  78 .It Fl rounds Ar n
  79 Multiply the number of rounds to play by
  80 .Ar n .
  81 For two-player tournaments this option should be used to set the total
  82 number of games to play.
  83 .It Fl ratinginterval Ar n
  84 Set the interval for printing the ratings to
  85 .Ar n
  86 games.
  87 .It Fl debug
  88 Display all engine input and output.
  89 .It Fl pgnin Ar file
  90 Use
  91 .Ar file
  92 as the opening book in PGN format.
  93 .It Fl pgndepth Ar plies
  94 Set the maximum depth for the PGN input.
  95 .It Fl pgnout Ar file Bq Cm min
  96 Save the games to
  97 .Ar file
  98 in PGN format. Use the
  99 .Cm min
 100 argument to save in a minimal PGN format.
 101 .It Fl recover
 102 Restart crashed engines instead of stopping the game.
 103 .It Fl repeat
 104 Play each opening twice so that both players get to play it on both
 105 sides.
 106 .It Fl site Ar arg
 107 Set the site / location to
 108 .Ar arg .
 109 .It Fl srand Ar seed
 110 Set the random seed for the book move selector.
 111 .It Fl wait Ar n
 112 Wait
 113 .Ar n
 114 milliseconds between games. The default is 0.
 115 .It Fl -version
 116 Display the version information.
 117 .It Fl -help
 118 Display help information.
 119 .It Fl -engines
 120 Display a list of configured engines and exit.
 121 .El
 122 .Ss Engine Options
 123 .Bl -tag -width Ds
 124 .It Ic conf Ns = Ns Ar arg
 125 Use an engine with the name
 126 .Ar arg
 127 from engine configuration file.
 128 .It Ic name Ns = Ns Ar arg
 129 Set the name to
 130 .Ar arg .
 131 .It Ic cmd Ns = Ns Ar arg
 132 Set the command to
 133 .Ar arg .
 134 .It Ic dir Ns = Ns Ar arg
 135 Set the working directory to
 136 .Ar arg .
 137 .It Ic proto Ns = Ns [ Cm uci | Cm xboard  Ns ]
 138 Set the chess protocol.
 139 .It Ic tc Ns = Ns [ Ns Ar tcformat | Cm inf Ns ]
 140 Set the time control.
 141 The format is moves/time+increment,
 142 where
 143 .Ar moves
 144 is the number of moves per tc,
 145 .Ar time
 146 is time per tc (either seconds or minutes:seconds),
 147 and
 148 .Ar increment
 149 is the time increment per move in seconds.
 150 .Pp
 151 Infinite time control can be set with
 152 .Cm inf .
 153 .It Ic option. Ns Ar name Ns = Ns Ar value
 154 Set custom engine option.
 155 .It Ic arg Ns = Ns Ar arg
 156 Pass
 157 .Ar arg
 158 to the engine as a command line argument.
 159 .It Ic initstr Ns = Ns Ar arg
 160 Send
 161 .Ar arg
 162 to the engine's standard input at startup.
 163 .It Ic restart Ns = Ns [ Cm auto | Cm on | Cm off Ns ]
 164 Set the engine restart mode.
 165 .Cm auto
 166 means the engine decides whether to restart (default),
 167 .Cm on
 168 means the engine is always restarted between games and
 169 .Cm off
 170 means the engine is never restarted between games.
 171 .It Ic st Ns = Ns Ar n
 172 Set the time limit for each move to
 173 .Ar n
 174 seconds.
 175 This option cannot be used in combination with the
 176 .Ic tc
 177 option.
 178 .It Ic timemargin Ns = Ns Ar n
 179 Let engines go
 180 .Ar n
 181 milliseconds over the time limit.
 182 .It Ic book Ns = Ns Ar file
 183 Use
 184 .Ar file
 185 (Polyglot book file) as the opening book.
 186 .It Ic bookdepth Ns = Ns Ar n
 187 Set the maximum book depth (in fullmoves) to
 188 .Ar n .
 189 .It Ic whitepov
 190 Invert the engine's scores when it plays black.
 191 This option should be used with engines that always report scores from white's
 192 perspective.
 193 .It Ic depth Ns = Ns Ar plies
 194 Set the search depth limit.
 195 .It Ic nodes Ns = Ns Ar count
 196 Set the node count limit.
 197 .El
 198 .Sh EXAMPLES
 199 Play ten games between two Sloppy engines with a time control of 40
 200 moves in 60 seconds:
 201 .Pp
 202 .Dl $ cutechess-cli \-engine name=Sloppy -engine name=Sloppy -each cmd=sloppy proto=xboard tc=40/60 -rounds 10
 203 .Pp
 204 Play a single game between Atak and Glaurung engines with a time
 205 control of 40 moves in one minute and 30 seconds with one second
 206 increment:
 207 .Pp
 208 .Dl $ cutechess-cli \-engine name=Atak cmd=Atak32.exe dir=C:\eatak proto=xboard -engine cmd=glaurung proto=uci option.Threads=1 -both tc=40/1:30+1
 209 .Bl -bullet
 210 .It
 211 Use the name=Atak parameter because it's a Xboard protocol 1 engine
 212 and doesn't tell its name.
 213 .It
 214 Use the dir=C:\eatak parameter to point the location of the executable.
 215 .It
 216 Glaurung can tell its name and is in the PATH variable so only the
 217 command is needed.
 218 .It
 219 Set Glaurung to use 1 thread.
 220 .It
 221 Set the time control to 40 moves in one minute and 30 seconds with
 222 one second increment.
 223 .El
 224 .Pp
 225 Play a Round-Robin tournament between Fruit, Crafty, Stockfish and
 226 Sloppy:
 227 .Pp
 228 .Dl $ 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
 229 .Bl -bullet
 230 .It
 231 Play two games per encounter,
 232 effectively multiplying the number of games by 2.
 233 .It
 234 Play 10 times the minimum amount of rounds (3). So the total number
 235 of rounds to play will be 30, and the total number of games 120.
 236 .It
 237 In each two-game encounter colors are switched between games and the
 238 same opening line is played in both games.
 239 .El
 240 .Sh SEE ALSO
 241 .Xr engines.json 5
 242 .Sh AUTHORS
 243 The
 244 .Nm
 245 utility was written by
 246 .An Ilari Pihlajisto ,
 247 .Mt ilari.pihlajisto@mbnet.fi ;
 248 and
 249 .An Arto Jonsson ,
 250 .Mt ajonsson@kapsi.fi .
 251 .Sh RESOURCES
 252 .Bl -bullet
 253 .It
 254 Project page:
 255 .Lk http://github.com/cutechess/cutechess
 256 .It
 257 Mailing list:
 258 .Lk https://list.kapsi.fi/listinfo/cutechess
 259 .El