The CQL command line

Normally CQL can be run from the command line (or shell) just by specifying the name of the CQL file. To run CQL on a CQL file named foo.cql, use

cql foo.cql

The basic operation of CQL can be modified from the command line by specifying various options. These options follow Unix conventions and consist either of a single letter preceded by a hyphen, or a word preceded by two hyphens (actually, you can use one hyphen instead of two). Some of the options take one or two arguments following the option name and separated by whitespace. These options override any options set in the CQL file itself. The options (and their arguments if any) always come after the name of the program cql but before the name of the CQL file.

The command line options are:

option name	examples	description
-alwayscomment	cql -alwayscomment foo.cql	disable smart comments
-black	cql -black Kasparov	Black player must match next command line argument
-cql	cql -cql "Ra3 Nb2 stalemate"	positions must match the specified CQL filters
-event	cql -event Championship	Limit games searched to the specified event
-fen	cql -fen    8/8/8/8/8/8/8/KNk5	only match positions with given FEN board
-flip	cql -flip puremate.cql	flip the body of the CQL file
-flipcolor	cql -flipcolor staircase.cql	allow color interchange in body of CQL file
-gamenumber -g	cql -gamenumber 1 100 foo.cql cql -gamenumber 43597 foo.cql	only consider games with game numbers in the range given by the next one or two numeric command line arguments.
-gui	cql -gui -i /a/x/b.pgn -o /a/x/c.pgn	output information for GUI developers
-help	cql -help	print a help message
-input -i	cql -input h.pgn foo.cql	read games from the PGN file specified in the next command line argument. The .cql extension may be omitted. Overrides the input parameter
-lineincrement	cql -lineincrement 500	print message every specified number of games
-mainline	cql -mainline foo.cql	Search only in the mainline.
-matchcount	cql -matchcount 0 foo.cql	only output games for which the number of matched positions lies within the range following -matchcount
-matchstring	cql -matchstring "pure mate" puremate.cql	change the comment inserted when a position is matched (default is "CQL")
-noheader	cql -noheader staircase.cql	omit the CQL-generated header before every game
-output -o	cql -output out.pgn foo.cql	write the output file to the PGN file specified in the next command line argument. Overrides the output parameter
-player	cql -player Reti foo.cql	Only consider games by player named in next command line argument
-reversecolor	cql -reversecolor puremate.cql	reverse the colors in the body of the CQL file
-result	cql -result 1-0 cql -result 0-1 cql -result 1/2-1/2	result must match specified argument
-shift	cql -shift foo.cql	shift the body of the file
-singlethreaded -s	cql -s foo.cql	run only one thread
-showmatches	cql -showmatches foo.cql	print the game number of each match as it occurs
-silent	cql -silent foo.cql	Suppress printing of automatically generated comments
-site	cql -site Paris	site should match specified argument
-threads	cql -threads 3 foo.cql	Run with the specified number of threading
-variations	cql -variations foo.cql	Search in the mainline and in variations
-version	cql -version	print version number of this CQL executable
-virtualmainline	cql -virtualmainline puremate.cql	Only consider virtualmainline positions
-white	cql -white Kasparov	White player must match next command line argument
-year	cql -year 2000 2010 foo.cql	only consider games whose year is in the range given by the following one or two numeric command line arguments

Combining options

The options can be combined. For example,

  cql -input input.pgn -output -output.pgn -gamenumber 100 1000 foo

will read the cql file foo.cql using games from input.pgn and writing the output to output.pgn, only examining games 100 through 1000 from input.pgn.

Syntax errors

When a syntax error occurs CQL sometimes attempts to give a useful error message, including the line number and character where it thinks the error occurs. Always check these error messages when tracking down a syntax error.

Missing CQL file

A default CQL is provided if:

• the CQL file is not specified, and
• an input file is specified (using -i or -input).

The contents of this default CQL file are:

cql().

That is, this file matches every position in every game.

When no CQL file is specified on the command line, the output pgn file is written to the file cqldefault-out.pgn, unless the user specifies another output pgn file explicitly using -o or -output.

Notes on threading

CQL can be run multithreaded or single-threaded. Multithreaded execution is the default, using a number of threads which CQL tries to guess based on the platform architecture.

To specify the number of threads directly, use the -threads option:

cql -threads 3 foo.cql

In this example, CQL runs with 3 threads.

To specify single-threaded execution, use one of the following equivalent forms:

    cql -threads 1 ...
    cql -singlethreaded ...
    cql -s ... 

Multithreaded mode is generally faster than single-threaded mode for systems with at least three cores. Single-threaded mode can be used in the following instances:

1. For extremely long games (thousands of moves) or for certain kinds of regular expression searches inside of a line filter, on certain platforms, single-threaded mode is required due to stack space limitations. Unfortunately, if CQL were to run out of stack space, it would fail without a useful error message. Please let us know if this occurs in practice; it has not occurred in our testing but it is a theoretical possibility.
2. single-threaded mode may be more robust if the input PGN file is not in standard export format. That is, if the PGN file is malformed in any way then single-threaded mode may be more reliable (we do not recommend running CQL unless the input PGN file is in standard export format however).
3. If a persistent variable is used in the input CQL file, then CQL forces execution to be single-threaded no matter what is specified on the command line.

Command line programming

CQL offers various features for modifying the behavior of the argument CQL file or even running without a CQL file at all. These are discussed in more detail command line programming.