QQL CLI reference

The qql binary is the operational interface to the same runtime used by the SDKs. It parses, plans, and executes QQL against a Qdrant instance, or against the in-process edge backend, from a terminal or a script.

Which page do I need?

Command-flag reference here; if you don't know which command you need, start at Operations.

Global flags

The flags below apply across all subcommands.

Flag	Purpose
--url <URL>	Qdrant endpoint. Overrides QDRANT_URL and ~/.qql/config.json; defaults to http://localhost:6333.
--api-key <KEY>	Qdrant API key. Overrides QDRANT_API_KEY and ~/.qql/config.json.
--edge	Execute supported commands against the configured in-process edge backend. Requires an edge-enabled build.

gRPC endpoint selection

A URL containing :6334 selects the gRPC transport when the CLI was built with the grpc feature. Otherwise the REST transport is used.

Configuration precedence

QQL resolves server endpoints and credentials using the following hierarchy (highest to lowest precedence):

1. CLI flags: --url <URL> and --api-key <KEY> passed directly on the command line.
2. Environment variables: QDRANT_URL and QDRANT_API_KEY.
3. User configuration: ~/.qql/config.json (managed via qql setup or qql config set).
4. Default fallback: http://localhost:6333 with no API key.

Three-tier mental model

CLI operations are organized into three distinct tiers:

Tier	Focus	Connectivity	Primary commands
Tier 1: Offline & CI	Source text, syntax, AST, formatting	100% offline (no backend needed)	qql lint, qql fmt, qql explain, qql convert
Tier 2: Live Query	Single statement execution and triage	Requires target backend	qql run, qql doctor "<query>" (check)
Tier 3: Cluster & Tooling	Cluster health, config, data migration, REPL	Requires target backend	qql setup, qql config, qql doctor, qql repl, qql dump, qql migrate

QQLExecutable inputTry in playground↗Copy

SHOW COLLECTIONS;

Everyday CLI usage across tiers

Copy

# Tier 1: Lint offline before committing

qql lint ./queries/ --fix qql explain "QUERY 'quantum' FROM papers USING dense LIMIT 5"

# Tier 2: Run inline queries or script files with smart detection

qql run "SHOW COLLECTIONS" qql run search.qql qql run "QUERY TEXT :q FROM docs LIMIT :lim" -p q=database -p lim=5 qql doctor "QUERY [0.1, 0.2, 0.3] FROM docs LIMIT 1"

# Tier 3: Setup, cluster diagnostics, and interactive shell

qql setup qql doctor qql repl

---

Tier 1: Offline & CI Tools

These commands perform static analysis, formatting, and AST transformations completely offline. They never initiate network connections.

qql lint

Static analysis and plan verification for QQL scripts. Scans a file or recursively walks a directory (defaults to current directory if omitted).

• Syntax Error Recovery: Parses all statements in a file, recovering past errors to report every syntax mistake in one run.
• Plan Validation: Compiles statements through the query planner to catch structural, naming, and clause conflicts.
• Parameter Binding: -p key=value / --params-file <path> bind :name / ? placeholders before the plan check, exactly as run would. Without flags, a leading -- qql-params: {...} (or [...]) header — single-line JSON in the first 10 lines — supplies the values instead.
• Idiom Rules: Flags anti-patterns such as redundant WITH PAYLOAD true clauses (payloads are included by default in QQL).
• Formatting Validation: Checks whether the file conforms to canonical QQL formatting.
• Codeframe Display: Renders terminal codeframes with file names, line numbers, and exact error locations.
• Autofix: --fix (or --write) automatically applies canonical formatting and removes redundant clauses in place.
• Machine Output: --json produces structured JSON reports for CI pipelines.

Lint files and autofix

Copy

# Lint current directory

qql lint

# Lint specific file or folder

qql lint queries/search.qql qql lint ./scripts/

# Automatically fix formatting and redundant clauses

qql lint --fix qql lint --write queries/

# Machine-readable JSON for CI

qql lint --json

qql fmt

Format QQL source into canonical style. Reads from a file or from stdin.

• --check: Exits with code 1 if the file requires formatting without writing changes.
• --write: Re-formats the file in place.

Format QQL source

Copy

# Format and print to stdout

qql fmt query.qql cat query.qql | qql fmt

# CI verification

qql fmt --check query.qql

# Format in place

qql fmt --write query.qql

qql explain

Inspect the hierarchical execution plan tree offline without sending requests to Qdrant.

• Accepts inline query strings.
• --param key=value (or -p): Binds named parameters (:key).
• --params-file <path>: Binds parameters from a JSON file.
• --json: Emits the plan tree as structured JSON.

Inspect execution plan

Copy

qql explain "QUERY 'quantum' FROM papers USING dense LIMIT 5" qql explain "QUERY TEXT :q FROM docs LIMIT :lim" -p q=search -p lim=10 qql explain --json "QUERY [0.1, 0.2, 0.3] FROM docs LIMIT 1"

qql convert & qql record

Convert Qdrant REST JSON payloads to idiomatic QQL statements.

• qql convert [file.json]: Reads JSON from a file or stdin and renders canonical QQL. Use --collection <name> for bare request bodies.
• qql record: Transparent proxy that records live application traffic to JSONL and produces converted QQL scripts (requires --features record).

Convert REST JSON

Copy

qql convert search.json cat payload.json | qql convert --collection docs

See Operations > Convert REST JSON for full details and examples.

---

Tier 2: Live Query Execution & Triage

These commands execute statements or troubleshoot individual query issues against a running backend.

qql run

Smart query runner that automatically detects whether the input argument is an inline query string or an existing .qql script file.

• Inline Query: If the argument does not exist as a file, qql run treats it as an inline QQL string.
• Script File: If the argument points to a .qql file, qql run executes the file statement-by-statement.
• Parameter Binding: Supports -p key=value / --param key=value and --params-file <path>.
• Output Options: --json outputs structured JSON results; -q/--quiet suppresses banners.
• Script Options: --stop-on-error halts execution on the first failing statement.

Run queries and scripts

Copy

# Run inline statement

qql run "SHOW COLLECTIONS"

# Run inline query with parameters

qql run "QUERY TEXT :q FROM docs LIMIT :lim" -p q=database -p lim=5

# Run a .qql script file

qql run migrations/seed.qql --stop-on-error

# Run with JSON output

qql run --json "COUNT docs"

qql doctor "<query>" (alias: qql check "<query>")

When a query fails or produces unexpected results, qql doctor "<query>" (or qql check "<query>") provides staged triage in 5 sequential steps:

1. Format Check: Verifies query syntax and canonical formatting.
2. Offline Explain: Validates planner AST lowering.
3. Embedder Probe: Tests embedder endpoint reachability and dimension when USING text embedding.
4. Vector Topology Check: Validates vector names and dimensions against the live collection schema.
5. Backend Doctor: Tests backend connectivity and authentication.

Offline lint vs. live query triage

qql lint is 100% offline and verifies syntax and plan structure without needing a backend. In contrast, qql doctor "<query>" / qql check "<query>" verifies live cluster and embedder state. If your Qdrant cluster is unreachable, qql doctor "<query>" will exit non-zero at the connectivity stage even for a syntactically valid query.

Triage a query

Copy

qql doctor "QUERY [0.1, 0.2, 0.3] FROM docs LIMIT 1" qql doctor "QUERY 'neural search' FROM docs USING dense LIMIT 5" qql check --json "QUERY [0.1, 0.2] FROM docs LIMIT 1"

---

Tier 3: Cluster Operations & Setup

These commands manage cluster configuration, cluster health, data migrations, and interactive sessions.

qql setup

Interactive onboarding wizard that configures connection endpoints and credentials.

• Prompts for Qdrant URL (defaults to http://localhost:6333).
• Prompts for optional Qdrant API key.
• Prompts for optional OpenAI-compatible text embedding URL and model.
• Writes persistent configuration to ~/.qql/config.json with secure permissions (0600).
• Supports non-interactive flags: --url <URL>, --api-key <KEY>, --yes (accept defaults).

Run setup wizard

Copy

# Interactive setup

qql setup

# Non-interactive script setup

qql setup --url http://localhost:6333 --yes

qql config

Inspect and update CLI settings stored in ~/.qql/config.json.

Subcommand	Purpose
qql config show	Print current configuration, config file location, and active URL resolution
qql config get <key>	Get a specific configuration value (e.g. url, api_key)
qql config set <key> <val>	Update a specific configuration value in ~/.qql/config.json
qql config path	Print the absolute path to ~/.qql/config.json
qql config edge	Manage persistent edge backend settings (<config_dir>/edge.json)

Manage configuration

Copy

qql config show qql config set url http://192.168.1.50:6333 qql config set api-key my-secret-key qql config get url qql config path

qql doctor

Run cluster-wide health diagnostics without requiring a query.

• Probes Qdrant reachability and authentication status.
• Probes configured text embedding endpoints (EMBED_URL).
• Inspects all collections and checks for dimension mismatches against the embedder.
• --json: Emits diagnostic results as machine-readable JSON.

Cluster health check

Copy

qql doctor qql doctor --json

qql repl (aliases: qql connect, or bare qql in a TTY)

Interactive REPL shell with multiline continuation prompts (qql...> ), live syntax completeness detection, and tabular formatting.

Built-in command	Purpose
help, \h, ?	Show available statements and built-in commands
fmt <qql>, \f <qql>	Format QQL into canonical syntax
doctor, \d	Run backend and embedder health diagnostics
explain <query>	Show the hierarchical ASCII execution plan tree
run <file>, \e <file>	Run a .qql script file statement-by-statement with timing
\param [key=value | clear], \p	Inspect, set, or clear session-scoped parameter bindings
dump <collection> <output.qql>	Dump collection schema and vectors to .qql
exit, quit, \q, :q	Leave the shell

Ctrl-D exits the shell; Ctrl-C cancels the current multiline buffer.

Start the REPL

Copy

qql repl qql> QUERY 'vector databases' qql...>   FROM docs qql...>   USING dense qql...>   LIMIT 5; qql> \f query text 'quantum' from papers limit 10 QUERY 'quantum' FROM papers LIMIT 10; qql> \q

qql dump & qql migrate

Data movement utilities for collections.

• qql dump <collection> <output.qql>: Exports collection schema and points into a portable .qql script (--batch-size N, default 100). See Dump and restore.
• qql migrate <collection>: Copies schema and points directly to another collection or remote cluster.

Preview, run, and resume a migration

Copy

qql migrate docs --to docs_copy --dry-run qql migrate docs --to docs_copy --recreate --workers 4 --batch-size 128 qql migrate docs --to docs_copy --resume

Flag	Purpose
--dry-run	Print the create plan and exit without writing
--recreate	Drop and recreate the target collection
--workers N, --batch-size N	Parallel upsert window
--where "<filter>"	Migrate only matching points
--shard-key-field <field>	Route each point by its payload value
--resume, --restart, --cutover <alias>	Resume recovery or point an alias at the target

Full migration details live at Cluster migration.

---

Edge Backend Commands

With the edge feature (cargo install qql-cli --locked --features edge), the CLI can execute queries and manage embedded local collections without a network server.

Configuring Edge (qql config edge)

qql config edge writes persistent settings to <config_dir>/edge.json (mode 0600). Updates merge cleanly with existing settings.

Flag	Purpose
--data-dir	Directory for persistent qdrant-edge data
--in-memory / --on-disk	Keep payloads in RAM / persist them to disk
--wal-segment-mb N	WAL segment capacity in MiB
--embedder fastembed|http	Embedding backend (default fastembed)
--model	Local FastEmbed dense model name or alias
--sparse-model	Offline sparse model for fastembed (e.g. splade, bge-m3)
--multi-model	Offline multivector model for fastembed (e.g. bge-m3)
--image-model	Offline CLIP vision model for fastembed (e.g. clip-vision)
--reranker-model	Offline cross-encoder model (e.g. bge-reranker-base)
--cache-dir	Directory for downloaded FastEmbed models
--show-download-progress / --no-show-download-progress	Show / hide model download progress
--embed-url	OpenAI-compatible embedding endpoint for HTTP embedder
--embed-key	API key for HTTP embedding backend
--embed-model	Model name sent to HTTP backend (default nomic-embed-text)
--embed-dim	Expected HTTP embedding dimension (default 768)

Configure edge backend

Copy

qql config edge --embedder http \
--embed-url http://localhost:11434/v1/embeddings \
--embed-model all-minilm:l6-v2 \
--embed-dim 384

Using Edge Operations

Once configured, add --edge to operational commands:

Edge commands

Copy

qql --edge run "QUERY 'local search' FROM docs USING dense LIMIT 10" qql --edge doctor qql --edge repl qql edge optimize docs qql edge bootstrap docs --from http://localhost:6333

See the edge backend overview and the edge CLI reference.

---

Environment Variables

Variable	Default	Purpose
QDRANT_URL	http://localhost:6333	REST or gRPC endpoint
QDRANT_API_KEY	unset	Qdrant API key
EMBED_URL	unset	OpenAI-compatible embedding endpoint
EMBED_KEY	unset	API key for the embedding endpoint
EMBED_MODEL	all-minilm:l6-v2	dense model ID
EMBED_DIM	384	dense output dimension
MULTI_EMBED_URL	unset	multi/ColBERT embedding endpoint
MULTI_EMBED_KEY	unset	API key for multi embeds
MULTI_EMBED_MODEL	unset	multi/ColBERT model ID
MULTI_EMBED_DIM	unset	per-token dimension for multi embeds
IMAGE_EMBED_URL	unset	image/CLIP vision embedding endpoint
IMAGE_EMBED_KEY	unset	API key for image embeds
IMAGE_EMBED_MODEL	unset	image/CLIP vision model ID
IMAGE_EMBED_DIM	unset	image output dimension
RERANK_URL	unset	cross-encoder rerank endpoint
RERANK_KEY	unset	API key for reranking
RERANK_MODEL	unset	reranker model ID
QQL_EDGE_DATA_DIR	<config_dir>/edge-data	edge data directory
QQL_EDGE_EMBEDDER	fastembed	edge embedding backend
QQL_EDGE_MODEL	unset	edge FastEmbed dense model
QQL_EDGE_SPARSE_MODEL	unset	edge sparse model
QQL_EDGE_MULTI_MODEL	unset	edge multivector model
QQL_EDGE_IMAGE_MODEL	unset	edge image/CLIP model
QQL_EDGE_RERANKER_MODEL	unset	edge reranker model
QQL_EDGE_CACHE_DIR	unset	edge FastEmbed model cache
QQL_EDGE_ON_DISK	true	persist payloads to disk (true/false)