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
-a cql -a greekgift.cql convert unicode characters in greekgift.cql to ASCII
-alwayscomment cql -alwayscomment foo.cql disable smart comments
-assign cql -assign Foo x.cqo variable Foo is assigned the string "x.cqo". If the second argument is a number its numeric value is used
-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-simple.cql flip the body of the CQL file
-flipcolor cql -flipcolor staircase-sort.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
-html cql -html x.cql create x-cql.html
-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-simple.cql change the comment inserted when a position is matched (default is "CQL")
-noheader cql -noheader staircase-sort.cql omit the CQL-generated header before every game
-noremovecomment cql -noremovetag c.cql ignore removecomment filters
-nosettag cql -nosettag ex.cql ignore settag filters
-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-simple.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
-similarposition cql -similarposition submission.cql check each position in submission.pgn to determine whether it matches current position
-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
-u cql -u turton.cql convert turton.cql to use Unicode where possible
-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 turton.cql Only consider virtualmainline positions
-white cql -white Kasparov White player must match next command line argument
-vi cql -vi staircase-sort.cql read from hhdbvi.pgn; equivalent to
cql -input hhdbvi.pgn ...
-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 persistent, readfile, writefile, or dictionary 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.