UCI Protocol
The usage below was checked against official Pikafish commit 1c66b9b. For how commands start and end a search, see Engine Runtime and Communication.
A Complete Analysis Session
The GUI sends the commands below in sequence, waiting for uciok before setting options and for readyok before setting the position and starting analysis:
uci
setoption name Threads value 2
isready
position startpos moves b0c2 b9c7
go movetime 1000b0c2 and b9c7 move the Red and Black horses from their starting squares. The engine records both moves, searches with a one-second move limit, reports info, and ends with bestmove. The GUI plays that move and sends an updated position before the next analysis.
For go infinite, send stop and wait for bestmove, continuing to read standard output during the handoff. Change positions or options after this search has finished.
quit
Requests that search stop and the engine exit. If search is still running, the engine first waits for the workers to finish. Search results or bestmove may still be output during this time.
ucinewgame
When starting a new game, the GUI should send ucinewgame to clear the transposition table, search history, and related data. This command does not set up the initial position; position is still needed. Processing may take some time, so the GUI can follow it with isready to confirm that the preceding work is complete. If an earlier search is still running, send stop first and wait for bestmove.
setoption
Sets an engine option. Usage:
setoption name <id> [value <x>]Here <id> is the UCI option name and <x> is the value you want to set.
For example, for a GUI to set the engine's thread count to 16, it can send:
setoption name Threads value 16Some options, such as Clear Hash (clear the hash table), can omit value and be used directly, for example:
setoption name Clear HashFor UCI options, see the "UCI Options" page; they are not repeated here.
End search before changing options. Some settings output status messages such as info string; unknown options or invalid settings may also produce messages. Do not assume that the engine will output nothing.
isready
Checks that the engine can respond; it replies with readyok. It can also respond during search, so readyok does not mean search has finished. To end search, send stop and wait for bestmove.
uci
Used to get information about the engine (such as its name, author, UCI options, etc.). The following is an older example; check the engine you are using for its actual options, defaults, and ranges:
id name Pikafish 2024-02-18
id author the Pikafish developers (see AUTHORS file)
option name Debug Log File type string default
option name Threads type spin default 1 min 1 max 1024
option name Hash type spin default 16 min 1 max 33554432
option name Clear Hash type button
option name Ponder type check default false
option name MultiPV type spin default 1 min 1 max 128
...
uciokuciok is required. If, after the GUI sends uci, it does not receive uciok from the engine, the GUI will consider the program not to be a UCI engine.
position fen
Gives the engine a position as a FEN.
For example:
position fen 3k1a3/4a4/5n3/9/9/9/9/9/9/4KR3 wOr add a movelist (the move history) on top of that:
position fen 5a3/3ka4/5n3/9/9/9/9/9/9/4K1R2 w - - 0 1 moves g0f0 d8d9Note
The Pikafish version checked for this page requires the position prefix; a bare FEN cannot be sent directly. Coordinate moves use files a through i and ranks 0 through 9. Supplying move history helps the engine judge repetitions, perpetual check, and perpetual chase. The final FEN alone cannot restore the complete history.
A successful setup usually produces no direct reply. If the position or move history is invalid, the current implementation outputs CRITICAL ERROR and exits.
position startpos
Sets the current position to the starting position (rnbakabnr/9/1c5c1/p1p1p1p1p/9/9/P1P1P1P1P/1C5C1/9/RNBAKABNR w). You can append moves and the move history. The position prefix is required.
A successful setup usually produces no direct reply. Illegal moves in the history produce an error and cause the engine to exit.
go
Makes the engine analyze the current position (which can be set with the position command).
The following parameters can be added:
searchmoves <move1> <move2> ... <movei>: restricts the search to the specified moves (the GUI's "alternative move" feature needs this parameter). With the current parser, it must follow all other parameters on the line. The UCI protocol has nobanmovescommand (that one is from the UCCI protocol).infinite: analyze without limit (untilstopis sent).ponder: think in the background.wtime,btime: the time remaining for Red and Black (ms).winc,binc: the increment for Red and Black (ms).movestogo: for "so much time for so many moves" time controls; tells the engine how many moves remain until new time is granted. It is generally not used in Xiangqi.depth: search to the specified depth.nodes: search the specified number of nodes.mate: stop when a decisive result within the specified move distance is found; this is not limited to wins for the engine's side.movetime: the specified time per move (ms).perft: count legal move sequences to the specified depth. One ply is one move by one side. This does not run a normal scoring search.
After go is entered, the engine searches the current position and outputs the search results. The engine stops searching when the corresponding limit is reached or the user sends the stop command.
End go infinite with stop. If the predicted move is played during pondering, use ponderhit to switch to normal search. A normal search finishes by outputting bestmove, while go perft outputs path counts. See The Search Lifecycle.
d
Outputs the current position, its FEN, key information and check information. This command is for engine development and debugging.
eval
Outputs evaluation information for the current position. This command is for engine development and debugging.
export_net
Exports the network weights. A file name can be specified.
flip
Flips the board vertically and swaps Red and Black pieces and the side to move, mainly to check evaluation symmetry.
compiler
Outputs information about the compiler and the engine's instruction set.
bench
See What is bench? What do the bench results tell us?.
The current version also has a speedtest command. For the purposes and differences of these tools, see Runtime Diagnostics.
Implementation references: command dispatch and parameter parsing, position setup and error handling, flipping a position.
