Pattern search
Find Arabian mates, pins against the king, batteries, or any other arrangement of pieces, squares, and attacks you can describe. One query can match every orientation and both colors.
Find chess positions that ordinary database searches can’t.
Describe a piece arrangement, move sequence, or tactical pattern in a short query and search millions of PGN games for it. CQLi can also try moves that were never played and detect composed positions that could not arise in a legal game.
Arabian mates, any corner, either color
mate
flipcolor flip { kh8 Nf6 Rh7 }
Rh2 and Nf3 mate the king on h1
What is CQLi?
CQLi is a free, BSD-licensed command-line program that implements the Chess Query Language (CQL). It reads standard PGN files, evaluates a query against every position of every game, and writes the matching games to a new PGN file with each matching position marked by a comment.
CQL was created by Gady Costeff and Lewis Stiller. CQLi is an independent implementation by Robert Gamble that runs most CQL 6.1 queries unchanged. About CQL in the Reference Manual covers the language's history, and CQL Fundamentals explains how queries work when you want to go deeper.
Get started
CQLi is a standalone executable with no installer or external dependencies. Download it for Windows, macOS, or Linux →
Then run your first query, using the executable for your platform in place of cqli
(cqli-arm64 or cqli-x86_64 on macOS, .\cqli\cqli.exe on Windows):
cqli -i games.pgn -o matches.pgn -cql 'mate and move previous enpassant'
The Quick Start walks through your first queries.
What you can do with CQLi
Tag & comment editing
Strip [%clk] and [%eval] comments from Lichess downloads, fill in ECO and Opening tags, rename or remove tags, or add comments of your own across a whole database.
Variant support
Search Chess960, Crazyhouse, Atomic, Horde, Racing Kings, and other variant games. The variant is read from each game’s Variant tag, so a single database can contain games from multiple variants.
Moves that weren’t played
Try every legal move in a position, or place and remove pieces, to find missed mates and stalemates or to solve chess problems.
Retrograde analysis
Generate the moves that could have led to a position, and detect composed positions that could never have arisen in a legal game.
External programs
Command Pipe sends data such as the current position’s FEN to a program you write in any language, and the query can use its reply. The manual’s example uses Stockfish to score each position.
Generate and solve various types of chess puzzles
The query that solves these mazes is explained in Chess Mazes in the Reference Manual.
CQLi finds unreachable positions in compositions
Why this position is unreachable
All of Black’s missing pieces were captured by White Pawns currently on the board, but the missing trapped c8 Bishop could not have been captured by one of these Pawns.CQLi is credited with discovering unreachable starting positions in dozens of compositions in the HHdbVII endgame study database.