Commandline Options

The -a/--append Option

The -a option takes a single string argument which specifies the name of the output PGN file that CQLi will write matching games to. If the specified file already exists, output will be appended to the end of the file. In all other respects the option behaves the same as the –output option.

The --binaryoutput Option

The --binaryoutput option causes CQLi to open output PGN files in binary mode rather than text mode. On Windows, lines are terminated by a carriage-return/line-feed sequence when writing in text mode (the default). When binary mode is enabled, lines are terminated with a single line-feed character which matches the behavior on macOS and Linux systems (in both text and binary modes). This option can be used to produce files that are identical across platforms.

This option applies to all output PGN files including those specified with –output, –append, and Dynamic Output File Specifiers.

The --cql Option

While CQL queries are typically contained in text files with a .cql extension, it is sometimes convenient to specify short queries on the commandline. The --cql option accepts a single string argument representing the query to execute. Multiple --cql options may be specified in which case the evaluated query is formed from the combination of the strings provided to each option instance.

For example, the command:

cqli -i in.pgn -o out.pgn --cql 'stalemate [Aa] == 3 flipcolor { K Q k }'

will find stalemate positions in a KQ vs K endgame. The same query may be specified using multiple --cql options as in:

cqli -i in.pgn -o out.pgn --cql stalemate --cql '[Aa] == 3' --cql 'flipcolor { K Q k }'

The single quotes surrounding the arguments to the --cql options in the above examples are used to force the commandline shell to consider the entire string as one argument. This is often necessary when the argument contains spaces or other characters with special meaning to the shell such as $ or |.

One or more --cql options may also appear before a .cql file is specified in which case the specified query strings are prepended to the query appearing in the .cql file. This can be useful to add criteria to an existing .cql file without modifying its contents.

The --createdirectories Option

If the --createdirectories option is specified, CQLi will attempt to create missing directory hierarchy components for the specified output file(s). For example, the option -o x/y/z/test.pgn will usually fail if the directory hierarchy x/y/z/ does not exist in the directory from which CQLi is invoked. When --createdirectories is used, CQLi will attempt to create the directory components that do not exist before attempting to open the specified file. This can be useful when directory names are specified using Dynamic Output File Specifiers. This option does not affect the behavior of the writefile filter.

The --dryrun Option

When the --dryrun option is used, the names of the output file(s), along with the number of games that would be written to each file, is emitted at the end of processing as usual but the files are not actually created or written to. The primary purpose of this option is to ensure expected results when using Dynamic Output File Specifiers.

The -g/--gamenumber Option

The -g option takes one or two numeric arguments. If one argument is provided, only the game with the provided game number is processed, otherwise only the games with a game number between the provided numbers are processed. For example -g 10 specifies that only game number 10 should be processed while -g 10 20 specifies that only games 10 through 20 (inclusive) should be processed. Game numbers begin at 1 and represent the ordinal position of the game within the processed PGN file. It is an error to provide a number less than 1 as an argument to -g or to provide two arguments where the first argument is larger than the second.

CQLi still needs to parse games appearing before those specified by a -g option but these games will not be further processed. CQLi will terminate immediately after processing the last game specified by the -g option, games appearing later in the PGN file will not be parsed.

The --help Option

If the --help option is specified, CQLi will print help information and terminate. This option does not accept any arguments.

The -i/--input Option

The -i option takes a single string argument specifying the input PGN file for CQLi to process. A -i option will override an existing input CQL header parameter. If the argument to the -i option is not an absolute path name, it will be searched for in the directories specified by the CL_PATH environment variable if it is not found in the current directory. If the specified file cannot be found or opened by CQLi an error will be emitted and CQLi will terminate. At most one input PGN file may be specified.

The --license Option

If the --license option is specified, CQLi will print license information and terminate. This option does not accept any arguments.

The --limit Option

The --limit option takes a single non-negative numeric argument specifying the maximum number of matching games to find. After finding the specified number of matching games, CQLi will write the games and terminate. This option is useful when searching a large database and only a relatively small number of matching games are desired or when testing a query. If CQLi is running in single-threaded mode, the option --limit n will always find the first n matching games. However, when running in multi-threaded mode (the default), the first n games that match may not necessarily represent the first n matching games in the PGN file and the results may be different between runs.

The --lineincrement Option

By default, CQLi displays a progress indicator consisting of a dot (.) for every 1000 games processed. After every 10,000 games, the total number of games processed is shown in brackets followed by a newline, e.g.:

.........[10000]
.........[20000]
.........[30000]

The --lineincrement option takes a single non-negative integer which specifies how often the bracketed game total and newline combination are emitted, the default value is 10000. A dot is emitted for every n / 10 games processed where n is the value provided for this option, 10 dots will be emitted before every newline if n is a multiple of 10. For example, the option --lineincrement 100000 will cause a dot to be printed after every 10,000 games processed and a newline after each 100,000 games producing output that looks like:

.........[100000]
.........[200000]
.........[300000]

The option --lineincrement 0 may be used to completely suppress the progress indicator.

The --mainline Option

If this option is provided, CQLi will not process variation positions in a PGN file, even if a CQL header includes the variations parameter.

The --matchcount Option

By default, all games that contain at least one position matching the CQL query are written to the output file. The --matchcount option can be used to require a different number of matching positions in a game for it to be written to the output file. This option takes one or two non-negative numeric arguments. If one argument is provided, only games with exactly this number of matching positions are emitted. If two arguments are provided, only games whose number of matching positions are within the (inclusive) range specified by these arguments are emitted. It is an error to provide two arguments where the first argument is larger than the first.

If the first argument to the --matchcount option is 0 then games that do not match are included in the output (if 0 is the only argument, then only games that do not match are emitted). Emitted games that did not match will still contain Header Comments and Sort Comments as appropriate.

The --matchstring Option

By default, all matching positions in a game are commented with the string CQL when written to the output file. The --matchstring option takes a single string argument which overrides the string used to comment matching positions. An empty string argument (e.g. --matchstring '') can be used to indicate that matching positions are not automatically commented.

The --maxopenoutputfiles Option

The --maxopenoutputfiles option takes a single non-negative numeric argument specifying the maximum number of open output PGN files to keep open at a time when using Dynamic Output File Specifiers. Since closing a file that has been opened for writing is a relatively expensive operation on some systems (notably Windows), CQLi keeps output PGN file handles open as an optimization so that it does not have to keep opening and closing files every time the output filename changes. When opening a new output file fails due to operating system limits, CQLi will close the least-recently used output file so that the new one can be opened. The commandpipe and writefile filters also need to be able to open file handles and can fail if there are too many output PGN file handles open. This option allows an upper bound to be specified on the number of concurrently open output PGN files to prevent starving the commandpipe and writefile filters of available file handles.

For example --maxopenoutputfiles 100 will limit the number of file handles used for output PGN files to 100. On macOS, which has a default limit of 256 open file descriptors per process (the defaults are higher for other operating systems), this leaves over 150 file handles available for other purposes.

A value of zero indicates there is no maximum which is the default. A value of one effectively disables the multiple open PGN output file optimization.

The --nestedcomments Option

The PGN standard clearly states that “Brace comments do not nest” and, by default, CQLi will treat the first encountered right brace within a braced comment as the comment terminator. Some non-compliant chess software will produce PGN files where a left brace within a braced comment is treated as the start of a nested comment and a subsequent right brace is not intended to terminate the original comment. The resulting ill-formed PGN files produced by such software will produce parse errors when processed by CQLi. The --nestedcomments option will cause CQLi to treat left braces encountered within braced comments as the start of nested comments requiring an equal number of right braces to be seen before the comment is fully terminated. This option only affects the input PGN file, CQLi will never produce a PGN file with nested comments (braces appearing in a comment will be replaced with underscores before CQLi writes the result to the output PGN file).

The --nosort Option

By default, CQLi will store all matching games in memory until processing of the input PGN file has completed at which point the matching games will be sorted (according to any provided sort filter criteria and then by the game number) and written to the output file. If the --nosort option is specified, matching games are immediately written to the output file without performing any such sorting. This option is useful when the number of matching games is potentially very large and storing them in RAM could result in memory exhaustion.

If the sort filter is not used in the query (including via hhdb sort) and multiple threads are not enabled, the resulting output will be identical when using this option. If sort filters are used in the query, they will behave normally when evaluated but the order of matching games in the output file will not be influenced by the result of the sort filters. In single-threaded mode games will be emitted in game number order, in multi-threaded mode the order of games is unspecified and may differ between runs.

The --noclobber Option

This option will prevent CQLi from overwriting existing files specified with the -o option (including those specified with Dynamic Output File Specifiers) or the output parameter of a CQL header. When this option is specified, an attempt to open an output file that already exists will result in a fatal error. This option does not prevent existing files from being appended with the -a option nor does it prevent files from being overwritten with the writefile filter (the noclobber keyword can be used with the writefile filter for that purpose).

The -o/--output Option

The -o option takes a single string argument which specifies the name of the output PGN file that CQLi will write matching games to. The file will be overwritten if it exists. Note that there is no restriction on the name of the file specified by this parameter, e.g. CQLi will quietly overwrite existing files without a .pgn extension if requested.

If the specified name is not an absolute path, the file will be created in the current directory. At most one -o option may be specified. A -o option will override an existing output CQL header parameter. If no -o option is specified, and no output CQL header parameter is provided, a default output file name is constructed as follows:

• If a CQL query file name is provided, the output PGN file name consists of the base name of the query file with the extension replaced with -out.pgn. For example, if the query file is named C:/CQL/queries/loop.cql, the output file name will be loop-out.pgn.
• If no CQL query file is provided, the output file name will be cqldefault-out.pgn.

Default output files are always written to the current directory. If the argument to -o is stdout, matching games are written to standard output (to write output to a file named stdout use -o ./stdout).

Matching games may be split across multiple files by using one or more dynamic specifiers in the output filename string. See Dynamic Output File Specifiers for more information.

The --showmatches Option

The --showmatches option causes the game number of each game that will be written to the output PGN file to be emitted during processing, this output is interspersed with the progress indicator, e.g.:

<323>....<4773>.<5053>..<7853>..[10000]
....<14192>.....[20000]
<20357>..<22736>.....<27039><27065>..<29839>[30000]

If the progress indicator is disabled using the option --lineincrement 0, the --showmatches option will still be effective but all matches will be emitted on a single line, e.g.:

<323><4773><5053><7853><14192><20357><22736><27039><27065><29839>

The -s/--singlethreaded Option

CQLi employs multi-threaded execution by default when supported by the host hardware, the --singlethreaded option causes CQLi to process games without launching separate worker threads. This is sometimes desirable in cases where results can be affected by the use of multiple threads, see Multi-threaded Execution for details.

The --skipunknownvariants Option

The --skipunknownvariants option causes CQLi to skip games that contain a Variant tag with a value that is unknown to CQLi, such games are otherwise treated as Standard chess games which can result in PGN parse errors for moves that CQLi does not recognize as valid. This is useful when processing PGN files that contain multiple variants, some of which are not supported by CQLi.

The --sortmatchcount Option

The --sortmatchcount option causes matching games to be sorted in descending order by the number of matching positions (the match count). Games with a higher match count will appear before games with a lower match count in the output file. If the query also contains sort filters, those filters take precedence with the match count serving as a tie-breaker between games that would otherwise have the same sort order.

This option is independent of the –matchcount option. When used alone, --sortmatchcount sorts all matching games by match count without imposing any filtering criteria on the number of matches. When used together with --matchcount, games are first filtered by the specified match count range and the remaining games are sorted by match count.

This option provides the same sorting behavior as the sort matchcount CQL header parameter.

The --threads Option

The --threads option takes a single non-negative numeric argument specifying how many concurrent query threads should be used to process the provided PGN file. An argument of 0 will cause CQLi to use as many query threads as the system hardware reports it can support, by default CQLi will utilize a number of threads equal to one less than this value. There are several limitations and caveats associated with multi-threaded analysis, see Multi-threaded Execution for details.

Note that the option --threads 1 is not equivalent to using –singlethreaded. When invoked with –singlethreaded, CQLi runs with a single thread and disables the thread-related machinery needed to support multiple threads. The --threads 1 option causes CQLi to employ the multi-threaded mechanisms but to only launch a single thread which will result in worse performance than using --singlethreaded due to the overhead incurred from the multi-threaded machinery, this option is primarily used for testing.

The --variantalias Option

CQLi uses the Variant PGN tag to determine the variant of a game. For each supported chess variant, there are several innately recognized values for the Variant tag. The --variantalias option allows new values for this tag to be recognized as corresponding to a supported variant.

The variantalias option takes two arguments, the first being the variant name and the second being the variant alias. The variant name is any variant name innately known to CQLi (see Chess Variants for builtin aliases). The variant alias is the new alias being registered. Games having a Variant tag with the value of the provided variant alias will then be recognized as the variant associated with the specified variant name. The values used for variant name and variant alias are case-insensitive.

For example, CQLi recognizes the Chess960 variant with a Variant tag of either Chess960 or Fischerandom. To cause CQLi to recognize games having a Variant tag of FRC as belonging to this variant, either of the following options would suffice:

--variantalias Chess960 FRC
--variantalias Fischerandom FRC

The --variations Option

By default, CQLi will not process variation positions in a PGN file. The output PGN for matching games will contain any variations from the original game but the variations will neither be visited during query evaluation nor accessible from filters such as child. If the --variations option is provided, variations will be visited and accessible from other positions. This option does not accept any arguments.

The --version Option

If the --version option is specified, CQLi will print version information and terminate. This option does not accept any arguments.

The --vi Option

The --vi option is a shorthand equivalent to -i HHdbVI.pgn which specifies the HHdbVI endgame study database as the input PGN file.

The --vii Option

The --vii option is a shorthand equivalent to -i HHdbVII.pgn which specifies the HHdbVII endgame study database as the input PGN file.

The -w/--warnlevel Option

CQLi supports three types of diagnostics: errors, warnings, and infos. Error diagnostics are used to report incorrect syntax or semantics in a CQL query, incorrect option usage, and runtime errors such as when the condition of an assert filter fails, the file specified by the readfile filter cannot be accessed, or a command-pipe program does not respond when using the commandpipe filter. Warnings are used to alert the user of suspicious CQL constructs which may not behave as intended, use of deprecated features, and situations having the potential to introduce performance issues. Infos are generally used to inform about the use of CQLi extensions and legacy (but not deprecated) features.

CQLi also supports three warning levels. At warning level 1 only errors are emitted. At warning level 2 errors and warnings are emitted. At warning level 3, all diagnostics are emitted. The default warning level is 2, the -w option can be used to override this default. The -w option requires a single argument which must be either 1, 2, or 3.

The --alwayscomment/--nosmartcomments Option

This option will disable the Smart Comments mechanism that normally prevents comments from being emitted in a variety of situations where such comments are typically undesired. This option is sometimes useful as a debugging tool such as differentiating the lack of a comment due to smart comments vs another cause.

The --keepallbest Option

This option affects how Smart Comments work with the line, sort, and consecutivemoves filters. By default, comments explicitly added by comment filters appearing within these filters or the auxiliary comments implicitly added by these filters are only kept for the best match. The best match for line is the longest matching sequence for any evaluation of the line filter, the ending position with the smallest position ID is used to break ties among multiple lines of the same length. The best match for a sort filter is the first instance of the greatest value (or least value if sort min is used) of the filter for all evaluations over an entire game. The best match for a consecutivemoves filter is the first instance of the longest sequence encountered across all evaluations over an entire game.

When the --keepallbest option is used, there may be multiple best matches for these filters, the specific effects on each filter are described below. Explicit and auxiliary comments will be preserved for each of the best matches.

The --noasyncmessages Option

By default, CQLi will immediately emit messages requested via the message filter. This option will instead cause such messages to be queued and emitted at the completion of each game. For troubleshooting purposes it is typically desired to have the requested information presented immediately but this option may be useful to prevent messages from different games from being interspersed in multi-threaded mode as the entire set of messages for each game are emitted as an atomic unit when this option is used.

The --nocommitlog Option

This option will disable the CQLi extensions to Smart Comments that cause smart comments to be applied in more situations. Using this option will approximate the behavior of smart comments as implemented in CQL 6.1.

The --noremovecomment Option

Neuters the effect of removecomment filter. removecomment filters are still evaluated and will match the position but their semantics (removing any original comments at the current position) will not be honored.

The --noremovetag Option

Neuters the effect of the removetag filter. removetag filters will be evaluated as normal but the specified tag will not actually be removed from the game. This option does not affect the –includetagpattern or –excludetagpattern options.

The --nosettag Option

Neuters the effect of the settag filter. settag filters will be evaluated as normal but the specified tag will not actually be set.

The --pipetimeout Option

This option can be used to override the default timeouts associated with command-pipe programs. See Timeouts for more information.

The --secure Option

If --secure is specified, the appearance of the commandpipe, readfile or writefile filters will elicit in a fatal query parse error. Additionally, the input and output CQL header parameters will be ignored when this option is used.

The --showdictionaries Option

The values of persistent variables not declared with the quiet keyword are emitted by CQLi after processing of all games is complete. While dictionary variables are always persistent, they are not included in this list by default because they may be arbitrarily large and are often used to maintain state information across games, the final results of which are not typically interesting. If the --showdictionaries option is used, dictionary variables not declared as quiet will be emitted along with other persistent variables. Emitted dictionaries include the keys and values of all dictionary members as described in String Portrayal of Types.

The --coalescecomments and --nocoalescecomments Options

These options control whether multiple comments in a single position are coalesced in the output PGN file. When multiple comments are coalesced, they appear as a single comment separated by spaces. For example, a position that contains the two comments X and Y will be rendered as the single comment:

1.e4 {X Y}

when comment coalescing is enabled and two comments when comment coalescing is disabled:

1.e4 {X} {Y}

CQLi does not coalesce comments by default.

The --compactcomments and --nocompactcomments Options

By default, CQLi does not place spaces between comments and the braces that enclose them, e.g.:

1.e4 {X}

The default behavior corresponds to the --compactcomments option. If --nocompactcomments is specified, all comments will be separated from their enclosing braces by a single space, e.g.:

1.e4 { X }

The --compactmoves and --nocompactmoves Options

By default, CQLi does not separate the move indicator from the move, e.g.:

1.e4

This behavior corresponds to the --compactmoves option. If --nocompactmoves is specified, CQLi will place a space between move indicators and the corresponding moves, e.g.:

1. e4

The --compactvariations and --nocompactvariations Options

By default, CQLi does not place spaces between variations and the parentheses that enclose them, e.g.:

d4 (d3)

The default behavior corresponds to the --compactvariations option. If --nocompactvariations is specified, variations will be separated from the enclosing parentheses by a single space, e.g.:

d4 ( d3 )

The --elidecomments and --noelidecomments Options

If the --elidecomments option is specified, no comments will appear in the output PGN file produced by CQLi. Unlike the –silent option which only prevents CQLi from adding new comments, this option will additionally suppress any comments originally appearing in games.

The default behavior corresponds to the --noelidecomments option.

The --elidenags and --noelidenags Options

By default, CQLi will preserve NAGs appearing in processed games. If the --elidenags option is specified, NAGs are not included in PGN output.

The --elidevariations and --noelidevariations Options

By default, CQLi will preserve variation lines appearing in processed games, even when processing of variations is not enabled. If the --elidevariations option is specified, variation lines will never be included in PGN output, even if there are matches that appear in variation lines.

The --includetagpattern and --excludetagpattern Options

These options may be used to control which PGN tags are emitted when writing matching games. If --includetagpattern is specified, only tags whose names match the provided regular expression argument will be emitted. If --excludetagpattern is specified, tags whose names match the provided regular expression argument will be omitted. If both options are specified, a tag will be emitted only if it matches the --includetagpattern pattern and does not match the --excludetagpattern pattern.

For example, to exclude all tags except for Event, Site, Date, Round, White, Black, and Result, the option --includetagpattern 'Event|Site|Date|Round|White|Black|Result' may be used.

Note that the provided pattern must match the entire tag name; wildcards may be used to accomplish non-anchored matching. For example, to specify any tag that ends with Date, use .*Date instead of Date. Patterns are case sensitive by default, see Regex Matching Flags for performing case-insensitive matches.

These options only control which tags are written out for matching games. In particular, excluded tags are still accessible within Dynamic Output File Specifiers. This means that new tags created via settag in the primary query can be used in a %T (or %Q) specifier to dictate the name of the output file while also being excluded from the emitted game using these options.

The FEN tag is always emitted regardless of these options, even if one of the provided patterns would otherwise exclude it. To remove a FEN tag, use the removetag filter directly.

The --movenumberaftercomment / --nomovenumberaftercomment Options

The PGN specification dictates that move number indicators should always appear before a move by White and should appear before a move by Black only when there is a comment or NAG appearing before the move. By default, CQLi follows this behavior. If the --nomovenumberaftercomment option is specified, a comment preceding a move by Black will not cause a move number indicator to appear before the move (a NAG still will unless --nomovenumberafternag is also specified).

The --movenumberafternag and --nomovenumberafternag Options

The PGN specification dictates that move number indicators should always appear before a move by White and should appear before a move by Black only when there is a comment or NAG appearing before the move. By default, CQLi follows this behavior. If the --nomovenumberafternag option is specified, a NAG preceding a move by Black will not cause a move number indicator to appear before the move (a comment still will unless --nomovenumberaftercomment is also specified).

The --movenumbers and --nomovenumbers Options

By default, CQLi will precede all moves by White with a move number indicator as well as moves by Black that are preceded by a comment or NAG. If the --nomovenumbers option is specified, move number indicators will never appear in the PGN output.

The --pgnlinewidth Option

This option takes a single numeric argument specifying the maximum line length (including the newline character) of content written to the output PGN file, the default is 79.

Note that the specified line length may be exceeded for tag lines (tags are never split across multiple lines) or words in a comment that are longer than the specified width (comments are only split on spaces). Note also that the line length is specified in bytes, not characters, so lines containing multibyte Unicode characters may appear to be much shorter than this limit.

The --splitmoves and --nosplitmoves Options

By default, CQLi will allow a line break to separate a move number indicator from its corresponding move. If the --nosplitmoves option is specified, a move number indicator will never appear on a separate line from its corresponding move, even if the --nocompactmoves option is used (which causes a space to separate the move number indicator from the move).

The --uniquecomments and --nouniquecomments Options

By default, CQLi suppresses multiple instances of the same comment at the same position. If --nouniquecomments is specified such comment deduplication will not occur.

Note that using this option may result in duplicate auxiliary and position ID comments being emitted at a position. This option is typically used only for debugging purposes.

Operation of Injected Filters

A CQL query may be provided to CQLi via a file, via the –cql commandline option, or formed from one or more of the above filter-injecting commandline options. These mechanisms may also be combined to form the resulting query.

Each of the --cql and filter-injecting options introduce query text relative to the order in which the option appears. A query file is optional if other options result in the creation of query text. If a query file is provided, it must be the last argument in the invocation of CQLi, consequently no more than one query file may be supplied.

A transform option (one of the options in the above table that has the same name as a transform filter) injects the corresponding transform keyword followed by an opening brace, a closing brace is injected at the end of the final composed query such that everything that comes after the transform option is subject to the effect of the corresponding transform filter.

Non-transform options in the table above inject an unbraced filter into the query stream. Query text injected via the --cql option is immediately enclosed by braces, i.e. the closing brace does not extend to the end of the query as it does for transform options.

The result is that transform options affect all subsequent filters and that query text from other sources does not interact in unexpected ways. Since query text provided by a --cql option is braced, the effect of a transform filter appearing in a --cql option is limited to the text injected by the option.

The following example will match games where the Event tag contains Tata Steel, one of the player tags contains Firouzja, and this player lost the game:

--event "Tata Steel" --flipcolor --white "Firouzja" --result "0-1"

The resulting query text created from these options is:

event "Tata Steel" flipcolor { player white "Firouzja" result 0-1 }

If a query file is provided, it is added (without braces) to the end of the injected text, before closing braces associated with the injected transform filters are added. For example, if the above options were combined with a query file that contained:

eco "C65"

the resulting query would be:

event "Tata Steel" flipcolor { player white "Firouzja" result 0-1 eco "C65" }

The --assign Option

The --assign option takes two arguments and injects an assignment to the variable specified by the first argument with the value specified by the second argument. If the second argument is a valid numeric value, the numeric value will be assigned, otherwise string assignment will be used. For example, the option:

--assign X 10

will inject the filter:

X = 10

while the option:

--assign X 10a

will inject the filter:

X = "10a"

The --black Option

The --black option takes a single argument and injects a corresponding player filter. For example, the option:

--black "Carlsen"

will inject the filter:

player black "Carlsen"

The --btm Option

Accepts no arguments. Injects a btm filter into the query.

The --event Option

The --event option takes a single argument and injects a corresponding event filter. For example, the option:

--event "Tata Steel"

will inject the filter:

event "Tata Steel"

The --fen Option

The --fen option takes a single argument and injects a corresponding fen filter. For example, the option:

--fen "2r5/2q2pk1/b2p1npb/p1nPp3/P3P2P/B4QP1/2BN4/1R3NK1"

will inject the filter:

fen "2r5/2q2pk1/b2p1npb/p1nPp3/P3P2P/B4QP1/2BN4/1R3NK1"

The --flip Option

Accepts no arguments. Injects a flip transform filter into the query.

The --flipcolor Option

Accepts no arguments. Injects a flipcolor transform filter into the query.

The --fliphorizontal Option

Accepts no arguments. Injects a fliphorizontal transform filter into the query.

The --flipvertical Option

Accepts no arguments. Injects a flipvertical transform filter into the query.

The --player Option

The --player option takes a single argument and injects a corresponding player filter. For example, the option:

--player "Carlsen"

will inject the filter:

player "Carlsen"

The --reversecolor Option

Accepts no arguments. Injects a reversecolor transform filter into the query.

The --result Option

The --result option takes a single argument and injects a corresponding result filter. For example, the option:

--result "0-1"

will inject the filter:

result 0-1

The --rotate45 Option

Accepts no arguments. Injects a rotate45 transform filter into the query.

The --rotate90 Option

Accepts no arguments. Injects a rotate90 transform filter into the query.

The --shift Option

Accepts no arguments. Injects a shift transform filter into the query.

The --shifthorizontal Option

Accepts no arguments. Injects a shifthorizontal transform filter into the query.

The --shiftvertical Option

Accepts no arguments. Injects a shiftvertical transform filter into the query.

The --site Option

The --site option takes a single argument and injects a corresponding site filter. For example, the option:

--site "Wijk aan Zee"

will inject the filter:

site "Wijk aan Zee"

The --virtualmainline Option

The --virtualmainline option does not accept any arguments and injects a virtualmainline filter into the query. The use of this option implies the --variations option.

The --white Option

The --white option takes a single argument and injects a corresponding player filter. For example, the option:

--white "Firouzja"

will inject the filter:

player white "Firouzja"

The --wtm Option

Accepts no arguments. Injects a wtm filter into the query.

The --year Option

The --year option takes one or two numeric arguments and injects a corresponding year filter that matches games played in the specified year or range of years. For example, the option:

--year 2020

will inject the filter:

{ year == 2020 }

and the option:

--year 2010 2020

will inject the filter:

{ 2010 <= year <= 2020 }