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.

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

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