CUTECHESS-CLI(6)

🌸 CUTECHESS-CLI(6) — Games Manual 🌸

💖 NAME 💖

cutechess-cli — Automate chess engine tournaments. That is literally the whole point, bestie. 💅

✨ SYNOPSIS ✨

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

🦋 DESCRIPTION 🦋

Okay so the cutechess-cli utility automates chess engine tournaments. No cap, that is its whole job. Its options are as follows — yes, every single one, we are going through them all:

• -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 these iconic picks:
  • 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 — redirects standard error output into the file arg 🫶 so your engine's messy lil tantrums go somewhere other than your terminal.
• proto=[uci | xboard] — sets the chess protocol, iykyk. Pick uci or xboard ✨
• tc=[tcformat | inf] — sets the time control 💅 The format is moves/time+increment, where:
  • moves is the number of moves per tc
  • time is the time per tc (either plain seconds, or minutes:seconds)
  • increment is the time increment per move, in seconds

You can also set an infinite time control with inf ♾️

• option.name=value — sets a custom engine option, no cap 🎀
• arg=arg — passes arg to the engine as a command line argument.
• initstr=arg — sends arg to the engine's standard input at startup 🌸
• restart=[auto | on | off] — sets the engine restart mode:
  • auto means the engine decides whether to restart (this is the default 👑)
  • on means the engine is always restarted between games
  • off means the engine is never restarted between games

Heads up bestie: setting this option does not prevent engines from being restarted between rounds in a tournament featuring more than two engines. That's just how it is, periodt.

• trust — trusts result claims from the engine without validation. By default all claims are validated, so this is you literally saying "yeah I believe you" to a machine 💀
• st=n — sets the time limit for each move to n seconds. This option cannot be used in combination with the tc option — pick one, bestie, you can't have both 🙈
• timemargin=n — lets engines go n milliseconds over the time limit. A little grace period, we love to see it 🧚
• book=file — uses file (a Polyglot book file) as the opening book 📖
• bookdepth=n — sets the maximum book depth (in fullmoves) to n.
• whitepov — inverts the engine's scores when it plays black. Use this one with engines that always report scores from white's perspective, k? ⭐
• ponder — enables pondering if the engine supports it 🤔
• depth=plies — sets the search depth limit, in plies.
• nodes=count — sets the node count limit 🔥
• tscale=factor — scales engine timeouts by factor. Only use this option if necessary, fr fr, don't just vibe with it.
• debug — activates 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

Let me break down the deets for you 💖

• Use the name=Atak parameter because it's a Xboard protocol 1 engine and doesn't tell its name. Rude of it, honestly.
• 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. Main character energy, it knows who it is 👑
• 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. Math ate, honestly 🔥
• 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) — go read it, bestie, it's giving essential companion doc 🫶

---

💜 AUTHORS 💜

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

---

🌸 RESOURCES 🌸

• Project page: http://github.com/cutechess/cutechess — go click, go stan 🎀

---

And that's the whole page, bestie! 🦋 This lil gem is from Debian, dated June 28, 2020, and lives at CUTECHESS-CLI(6) — go forth and run tournaments, and remember: no cap, read your options 💅✨