CLI

CLI

cargo build --release
./target/release/qql 'Q:2:255'

Output is pretty-printed JSON. Exit code is 0 on "ok": true and 1 otherwise; the JSON goes to stdout either way, so it pipes into jq.

Options

Option	Meaning
--data <DIR>	Data directory. Default ./sources
--source <FILE>	Register sources from a manifest, relative to --data. Repeatable
--parse	Print the parsed query instead of resolving it — touches no files
--compact	Compact JSON instead of pretty-printed
--sources	List registered source codes
-h, --help	Usage
-V, --version	Version

Quoting — read this first

Your shell strips quotes before QQL sees them. Wrap the whole query in single quotes:

qql q:2:"book"      # WRONG — bash passes q:2:book → QQL_EXPECTED_NUMBER
qql 'q:2:"book"'    # right
qql "q:2:'book'"    # also right

The search markers * and ? are glob characters, so an unquoted *"book" can be rewritten by the shell. Always quote.

With cargo run, put -- before the query:

cargo run -- 'Q:2:255'

Examples

qql 'Q:2:255'
qql 'Q:2:1-5,255;Q:1;'
qql --data ./sources 'B:1:1-3'
qql --compact 'Q:1'
qql --sources
qql --parse 'Q:2:1-5,255;Q:1;'
qql 'q:2:"prayer"'
qql --data tests/fixtures/custom 'X:1:2'

--parse shows how a query was understood, without reading any data:

$ qql --parse --compact 'q:1:2,3,2:3'
{"ok":true,"query":"q:1:2,3,2:3","references":[
  {"all":false,"primary":1,"ranges":[[2,2],[3,3]],"search":null,"source":"Q"},
  {"all":false,"primary":2,"ranges":[[3,3]],"search":null,"source":"Q"}]}

That is the fastest way to check whether a query means what you think.

Optional search engines

Both are cargo features, off by default.

# ranked full text — build the indexes once
cargo run --features fulltext --bin qql-index
cargo run --features fulltext -- 'q:?"mercy"~5'

# vector similarity — indexes are committed, no build step
cargo run --features vector -- 'q:*"worship"~3'

For repeated use, build once and call the binary directly:

cargo build --release --features vector,fulltext
./target/release/qql 'q:?"mercy"~5'

qql-index

Builds the tantivy indexes the fulltext feature reads. Only available with that feature.

cargo run --features fulltext --bin qql-index                  # every source
cargo run --features fulltext --bin qql-index -- --source Q
cargo run --features fulltext --bin qql-index -- --data ./sources

Writes <DIR>/fulltext/<CODE>/. Rerun after changing text.