Fastchess(7)

📦
version 1.8.2-alpha · 2 versions
, in nixpkgs unstable

💖 NAME 💖

okay so bestie, gather round — this is fastchess, the manual page (that's the Fastchess(7) one, miscellaneous information section, if you're keeping track 🎀). it's a command-line tool for managing chess games with engines. yes. engines. plural. it's giving chess matchmaker energy and honestly? obsessed. 👑

✨ SYNOPSIS ✨

like, the whole vibe in one line:

fastchess [OPTIONS]

that's it. that's the entrance. you show up with some [OPTIONS] and fastchess does the rest 💅

🦋 DESCRIPTION 🦋

so here's the tea, bestie: Fastchess is a command-line tool built to manage and orchestrate chess games between engines, and the way that it literally just handles all of that for you? iconic. it's not out here playing chess itself — it's the main character organizer, the group-chat admin of your engine matchups 🫶

and it comes stacked with a whole range of options so you can configure, like, everything:

  • 🎮 game settings — all the rules-of-play stuff, your call
  • 🧠 engine parameters — the knobs and dials for the engines themselves
  • ⚡ concurrency — more than one thing happening at once, no cap
  • 📄 output formats — how you want the results to come out looking
lowkey the important thing to remember: fastchess is the orchestrator, not the player. it sets the stage, you bring the engines 💀✨

and that's just the opening act — there's more coming, so don't go anywhere, the rest of this page is gonna eat 🔥

💅 OPTIONS 💅

okay bestie, here's the whole menu of options ✨ they're grouped by what they actually do so you're not scrolling forever, and just so you know — the default value is always the first value in the parentheses. iykyk 🫶

🎀 General & Help 🎀

  • -version — prints the fastchess version number and dips. that's it, that's the whole job 💅
  • -help — prints this help message and exits. your little safety net 🧚

🌸 Tournament Setup 🌸

  • -quick cmd=ENGINE1 cmd=ENGINE2 book=BOOK — the shortcut for a whole predefined setup: two engines, time controls, rounds, and concurrency. literally the "just make it work" button 🔥
  • -concurrency (1|N) — play N games at the same time, capped by how many hardware threads you've got. default is 1.
  • -force-concurrency — ignores that hardware concurrency limit and forces whatever concurrency you asked for. bold of you, but slay 💀
  • -rounds (2|N) — play N rounds, where every game inside a round uses the same opening. default is 2.
  • -games (2|N) — play N games in each round. default is 2. and ngl, setting this higher than 2 doesn't give you meaningful results — so like, don't 🫠
  • -repeat — sets the number of games to 2. it's literally equivalent to -games 2.
  • -sprt elo0=ELO0 elo1=ELO1 alpha=ALPHA beta=BETA model=(normalized|logistic|bayesian) — sets the parameters for a Sequential Probability Ratio Test (SPRT). the mathy main character energy ✨
    • model:
      • normalized — uses nElo (this is the default).
      • logistic — uses regular/logistic Elo.
      • bayesian — uses BayesElo.
  • -tournament (roundrobin|gauntlet) — picks the tournament type 👑
    • roundrobin — every engine plays every other engine (default).
    • gauntlet — the first -seeds engines play against all the other engines.
  • -seeds (1|N) — the first N engines are the ones playing the gauntlet. default is 1.
  • -variant (standard|fischerandom) — choose your chess variant, bestie:
    • standard — play Standard Chess (default).
    • fischerandom — play Fischer Random Chess. chaos, but chess 🦋
  • -noswap — prevents the swapping of colors.
  • -reverse — uses a tournament schedule with reversed colors.
  • -wait (0|N) — waits N milliseconds between games. default is 0.

💜 Engine Configuration 💜

  • -each OPTIONS — applies the OPTIONS you give it to both engines. equal love 🫶
  • -engine OPTIONS — applies the OPTIONS you give it to the next engine.
    • cmd=COMMAND — specify the engine command.
    • name=NAME — set the engine name. if you don't specify one, the executable's filename gets used.
    • args="ARGS" — pass multiple arguments using args="ARG1 ARG2".
    • tc=moves/minutes:seconds+increment — time control in Cute-Chess format.
    • timemargin=N — time margin for exceeding the time limit.
    • st=N — movetime in seconds.
    • nodes=N — max number of nodes to search.
    • restart=(off|on) — enable or disable engine restarts between games. default is off.
    • plies=N — max number of plies (depth) to search. the alias depth works too.
    • proto=uci — specify the engine protocol. only uci is supported, so yeah.
    • dir=DIRECTORY — working directory for the engine.
    • option.name=VALUE — set engine-specific options. for a button option, the value should be true or false 💅

🔥 Adjudication & Rules 🔥

  • -draw movenumber=(0|N) movecount=(1|N) score=(0|N) — turns on draw adjudication based on number of moves, move count, and the score threshold.
    • movenumber — number of moves before it starts checking for a draw. default is 0.
    • movecount — number of consecutive moves below the score threshold. default is 1.
    • score — the score threshold (in centipawns) for a draw. default is 0.
  • -resign movecount=(1|N) score=(0|N) [twosided=(false|true)] — configures engine resignation based on move count and score threshold.
    • movecount — number of consecutive moves above the score threshold. default is 1.
    • score — the score threshold (in centipawns) to resign. default is 0.
    • twosided — if true, enables two-sided resignation. defaults to false.
  • -maxmoves N — enables draw adjudication if the game reaches N moves without a result.
  • -tb PATHS — adjudicates games using Syzygy tablebases. PATHS has to be a semicolon-separated list (on Windows) or a colon-separated list (on other platforms) of paths to the tablebase directories. only the WDL tablebase files are required — you don't need the whole buffet 🍓
  • -tbpieces N — only uses tablebase adjudication for positions with N pieces or less.
  • -tbignore50 — disables the fifty move rule for tablebase adjudication. yeah, we're bending the rules, don't @ me.
  • -tbadjudicate (BOTH|WIN_LOSS|DRAW) — controls when tablebase adjudication gets applied. SETTING can be:
    • BOTH — adjudicate both wins and draws (default).
    • WIN_LOSS — only adjudicate won/lost positions.
    • DRAW — only adjudicate drawn positions.

🦋 Opening Book Management 🦋

  • -openings file=NAME format=(epd|pgn) [order=(sequential|random)] [plies=(Max plies|N)] [start=(1|N)] — specifies an opening book file and its format for the starting positions of games.
    • format — the file format, either epd or pgn.
    • order — the order of the openings, random or sequential. default is sequential.
    • plies — number of plies for pgn. defaults to the max available plies.
    • start — starting index of the opening book. default is 1.
  • -srand SEED — specifies the seed for opening book randomization. deterministic vibes only ✨

🎀 Output & Reporting 🎀

  • -output format=(fastchess|cutechess) — picks the output format for game results, fastchess or cutechess. default is fastchess.
  • -pgnout [file=NAME] [notation=(san|lan|uci)] [append=(true|false)] [nodes=(false|true)] [seldepth=(false|true)] [nps=(false|true)] [hashfull=(false|true)] [tbhits=(false|true)] [pv=(false|true)] [timeleft=(false|true)] [latency=(false|true)] [min=(false|true)] [match_line=REGEX] — exports games in PGN format with the notation you pick, plus optional tracking of nodes, seldepth, and the rest of the crew 👑
    • notation:
      • san — Standard Algebraic Notation (default).
      • lan — Long Algebraic Notation.
      • uci — Universal Chess Interface.
    • file — specify the filename. default is fastchess_(date)_(time).pgn.
    • append — append to the file. default is true.
    • nodes — track node count. default is false.
    • seldepth — track seldepth. default is false.
    • nps — track nps. default is false.
    • hashfull — track hashfull. default is false.
    • tbhits — track tbhits. default is false.
    • pv — track the full pv. default is false.
    • timeleft — track time left at the end of the move. default is false.
    • latency — track the difference between measured time and the engine-reported time at the end of the move. default is false.
    • min — minimal PGN format. default is false.
    • match_line — adds lines to the PGN that match the given regex.
  • -epdout [file=NAME] [append=(true|false)] — exports the final position of each game in EPD format.
    • file — specify the filename. default is fastchess_(date)_(time).epd.
    • append — append to the file. default is true.
  • -event NAME — sets the event name for the PGN header.
  • -site NAME — sets the site name for the PGN header.
  • -ratinginterval (10|N) — sets the rating interval for the report. default is 10. set it to 0 to disable it entirely.
  • -scoreinterval (1|N) — for cutechess output, sets the interval for printing score results. default is 1.
  • -report penta=(true|false) — reports pentanomial statistics (for Fastchess output). defaults to true.

🌈 Persistence & Recovery 🌈

  • -config [file=NAME] [discard=(false|true)] [outname=(config.json|NAME)] [stats=(true|false)] — loads engine configurations so you can resume games from previous sessions. your little save file 🫶
    • file — the file name to load the configuration from.
    • discard — discards the loaded configuration after loading. defaults to false. this lets you specify a filename to save the configuration to, while ignoring it for the current session.
    • outname — the auto-generated file name of the config. default is config.json.
    • stats — loads the stats from the config file, and ignores append=false for -pgnout and -epdout. defaults to true.
  • -recover — enables crash recovery, so it tries to recover the engine after a crash and keep the tournament going 💀➡️😌
  • -autosaveinterval (20|N) — automatically saves the tournament state every N games. default is 20. set it to 0 to disable.

⭐ Testing & Debugging ⭐

  • --compliance ENGINE_PATH [ARGS] — checks the UCI compliance of an engine by running it with the specified arguments.
  • -crc32 pgn=true — calculates the CRC32 checksum for the PGN file.
  • -check-mate-pvs — checks that PVs for mate scores have the correct length and end in checkmate.
  • -show-latency — shows the "think" latency (the difference between measured and reported time) for each engine. quick heads up bestie: a lot of engines add 1ms to the time they report, so the latency will be 1ms higher than the actual latency. it's also possible for the latency to be negative, thanks to different measurement methods or missing synchronization of the clocks between different threads 😭
  • -testEnv — specifies that the program is running in a test environment (OpenBench/Fishtest). this changes some outputs/settings.
  • -strict — makes fastchess exit and return 1 on any warning. zero tolerance, periodt 💅
  • -log file=NAME level=(warn|trace|info|err|fatal) append=(true|false) compress=(false|true) realtime=(true|false) engine=(false|true) — specifies a log file with a specific log level. set append to false to overwrite an existing file — default is true. set compress to true to write to a gzipped file with a timestamp (this ignores append) — default is false. by default engine logs are disabled, so set engine to true to enable them.
    • LEVEL:
      • trace
      • info
      • warn (default)
      • err
      • fatal
  • -use-affinity [CPUS] — enables thread affinity for binding engines to CPU cores.
    • CPUS — the cpus to use, as a list of the form "3,5,7-11,13".
  • -startup-ms N — sets the maximum time to wait for engine UCI initialization, in milliseconds. default is 10000.
  • -ucinewgame-ms N — sets the maximum time to wait for engine UCI new game initialization, in milliseconds. default is 60000.
  • -ping-ms N — sets the maximum time to wait for engine ping responses, in milliseconds. this is everything else which doesn't fit the above categories. default is 60000.

✨ EXAMPLES ✨

Okay so you wanna see this in action? Say less, bestie. These are the exact command lines from the page, no cap.

🎀 Example 1: match with random openings 🎀

To start a match between two engines using random openings from book.epd:

$ fastchess -engine cmd=Engine1.exe name=Engine1 -engine cmd=Engine2.exe \
  name=Engine2 -openings file=book.epd format=epd order=random \
  -each tc=60+0.6 option.Hash=64 -rounds 200 -repeat -concurrency 4

🧚 Example 2: big SPRT test 🧚

To start a SPRT test between two engines up to 100000 rounds (200000 games) with 3 concurrent games with one engine playing with 2 million nodes per move and 1 thread and the other playing with 1 million nodes per move and 2 threads, and both having a time control of 5 minutes plus 5 seconds increment per move, using random openings from UHO_Lichess_4852_v1.epd, Fishtest adjudication rules, and saving the games to a file in a specific folder with SAN notation and nodes count:

$ fastchess \
  -engine cmd=Engine1.exe name=Engine1 option.Threads=1 nodes=2000000 \
  -engine cmd=Engine2.exe name=Engine2 option.Threads=2 nodes=1000000 \
  -openings file=UHO_Lichess_4852_v1.epd format=epd order=random \
  -each tc=300+5 -resign movecount=3 score=600 -draw movenumber=34 movecount=8 score=20 \
  -sprt elo0=0 elo1=2 alpha=0.05 beta=0.05 \
  -rounds 100000 -concurrency 3 -pgnout notation=san nodes=true file=./games/sprt.pgn

👑 AUTHORS 👑

Fastchess was written by Disservin, Szil, PGG106, and contributors.

🫶 REPORTING BUGS 🫶

Report any bugs to https://github.com/Disservin/fastchess/issues.

This software is licensed under the MIT license. See the LICENSE file for details.

💖 That’s the whole page, bestie. The footer/source-version line says Fastchess(7), and there’s no date printed in that footer. Now go slay your engine testing era 💅✨

📦 where this page comes from