CQLmatic command reference

This reference describes CQLmatic 0.1.0. Start with the documentation index, setup, and inventory. Machine callers should also read the contracts reference; query authors should use the query reference.

Commands below use cqlmatic as shorthand for your executable path or npx cqlmatic@0.1.0 (a supported, patched Node.js release, macOS Apple silicon or Linux x86_64). Run npx outside the CQLmatic source checkout. Windows x64 users can use the verified release ZIP. From a source build use ./target/release/cqlmatic; on Windows it is .\target\release\cqlmatic.exe. See development for the pinned Rust 1.99.1 build. Runtime use needs no Rust installation or model API key. CQLmatic makes no internal model calls. Relative file paths resolve from your current directory; save example inputs locally or extract the source release before using examples/ paths.

Help, version, and schemas

cqlmatic --help
cqlmatic --version
cqlmatic generate --help
cqlmatic env discover --help
cqlmatic --schema generate

-h/--help and -V/--version are parser-provided help/version options. Use command-specific --help for nested commands. A bare invocation is an input error (exit 2), not an interactive default.

--schema NAME prints a bundled JSON Schema and exits 0. Names are generate, check, pack, discovery, result, assess, setup, inventory, and status. It cannot accompany a command. Some exports contain request/result/state subschemas; do not send the whole schema wrapper as a request. See schema selection.

Input and output rules

The native framing and exit rules below describe the executable itself. npm can add its own stderr notices, and a signal sent only to the npm parent PID may leave the command running. Use npx in a foreground terminal for interactive setup; use the native executable directly when a supervisor requires reliable process cancellation or a machine caller requires native stderr framing.

• JSON and CQL inputs are UTF-8. Supply exactly one input mode for generate, check, or assess.
• - means stdin for JSON request files, generation plan/params files, raw check input (check - or --file -), and assessment query/result files. Environment JSON options --environment and discovery --request also use this convention. State, pack, credentials, import source/output, and MCP answer paths are filesystem paths. Do not select stdin for two file arguments in one invocation.
• generate, check, and assess support --jsonl on stdin. It implies structured output; no --json is needed. Setup, inventory, and status take one request, not JSONL.
• --json is available only where listed below. Catalog, environment inspection/import/discovery/identity/parser commands already emit JSON without it.
• Generation/checking JSON is an Analysis; assessment JSON is an AssessResult. Setup, inventory/status, and discovery have different contracts. Human output is for people, not a stable parser interface.
• Application-level global failures emit a standalone JSON diagnostic on stderr and exit 2, including with --json. Argument-parser failures can be plain text. Read stdout, stderr, and the exit code. A late output failure can occur after useful rows or file writes.

Contracts and streaming explains framing, IDs, blank records, record errors, and partial output.

Setup, status, and inventory

Use a dedicated private state directory. Default OS-specific locations and every action are described in setup and inventory. Setup actions use action.type; inventory actions use action.kind. Inventory has no caller id field.

cqlmatic setup --json
cqlmatic env inventory --json
cqlmatic status --json

These no-request invocations do not start native setup or a search. A setup request with action status passes through the state writer; it is different from no-request setup --json. Setup exits 1 until saved tool-discovery evidence qualifies. Inventory/status exit 0 when their command succeeds even if full_map_complete is false or an action records incomplete/failed work. Inspect the returned fields.

Native setup apply needs the exact reviewed confirmation hash. Interactive consent cannot run through unattended JSON apply: SETUP_INTERACTIVE_REQUIRED is a global error, exit 2. Successful native configuration is not authentication or tool availability. Parser API reads use a separate protected credential file and explicit budgets; MCP search uses the selected host client's OAuth. The lower-level --execute search switch does not gate every network-capable setup/inventory action.

Inventory's built-in scout always emits MCP repository:"search-all", even when its saved environment view differs. Relay it only with explicit authorization for that target/window. Otherwise leave scouting pending and use confirmed selected sources with lower-level discovery on the authorized view. Scout import does not automatically reject an unflagged empty or cap-sized census; scouting:done is not a completeness attestation. See scouting boundaries.

Generate

Choose exactly one input mode:

The source flags belong only to --intent. A structured English input requires source, even when it is {}.

cqlmatic generate --request examples/generate.request.json --json
cqlmatic generate --plan examples/process-count.plan.json --json
cqlmatic generate --recipe threshold --params examples/threshold.params.json --json
cqlmatic generate --intent 'count events where user equals "synthetic-user"' --json
cqlmatic generate --jsonl < examples/requests.jsonl

Shared generation and check flags

The two policy flags --require-observed and --accept-mixed-record-kinds are ORed with the corresponding request context values. Omitting a flag cannot disable a request's true value. No CLI flag supplies confirmed_fields or context.environment; use a full request for those fields.

Human generation prints the query only when ready; on other outcomes stdout can be empty. Diagnostics and grounding problems go to stderr. JSON includes the interpretation and evidence; generation withholds query on every nonready outcome. Inspect the returned plan before executing the exact query through an authorized client.

Bounded English

English is a deterministic adapter, not unrestricted intent interpretation. It does not infer fields, exclusions, source mapping, or time windows. See the full grammar and examples. For requests outside the grammar, use a recipe or typed plan. Matching, missing-field policy, exactness, and Boolean grouping remain explicit.

Check and lint CQL

Choose exactly one of positional QUERY, --file FILE, --request FILE, or --jsonl. Shared flags above apply.

cqlmatic check 'count()' --json
cqlmatic check --file .local/query.cql --pack .local/pack.json --json
cqlmatic check --request .local/check.request.json --json
cqlmatic check --jsonl < examples/checks.jsonl

Checking never executes or returns a copy of the input: Analysis.query is null, even for ready. Keep the exact input separately. Human check prints an assessment line on stdout plus diagnostics on stderr.

Empty/whitespace input and * are valid match-all checks. Static acceptance does not ensure restrictive scope. unsupported can mean valid platform syntax outside the local profile or a typo; invalid is a recognized checked-rule violation. See coverage and raw CQL checking.

groupBy(..., limit=max) emits informational CQL_GROUPBY_LIMIT; numeric or omitted grouping limits warn. Therefore --fail-on-warning does not reject the informational form. Group and memory ceilings still apply.

Assess saved results

Choose exactly one of --request FILE, --jsonl, or the pair --query-file FILE --result FILE. Optional flags are --pack FILE and --json; generation/check policy flags do not apply.

cqlmatic assess --request examples/assess.request.json --json
cqlmatic assess --query-file .local/query.cql --result .local/mcp-result.json --pack .local/pack.json --json

Save the entire unedited MCP result and the exact executed query bytes. The command is offline. Human output prints findings and a summary on stdout; structured output contains counts, column statistics, caps, and findings. Outcomes are no-findings (0), advisory or inconclusive (1), and error (2). no-findings does not prove correctness or completeness. See result assessment.

Look up syntax and fields

cqlmatic catalog cql:workflow:analyst --full --limit 1
cqlmatic catalog join --full --limit 3
cqlmatic catalog --functions regex
cqlmatic catalog --functions --limit 100
cqlmatic catalog --recipes
cqlmatic catalog --profile
cqlmatic catalog --standard cps event
cqlmatic catalog --standard ecs process.name

At most one of --functions, --recipes, --profile, and --standard may be selected. All modes are offline JSON output. Compact ordinary records include supported, which describes the associated local reference coverage; it is not execution proof. Broader knowledge can describe syntax outside the checker. See the function/catalog reference.

Environment commands

Identity

cqlmatic env identity --cloud us1 --view search-all --credentials-file PATH_TO_PROTECTED_CREDENTIALS

--cloud us1|us2|eu1 and --view NAME are required. --credentials-file FILE is optional; without it, the explicit Falcon environment variables are used. The command reads credentials but makes no network request. It prints an EnvironmentId with an API-client fingerprint, not a provider-verified CID. Keep the output protected. Identity and credential rules explain binding and rotation.

Inspect

cqlmatic env inspect .local/pack.json
cqlmatic env inspect .local/pack.json --source SOURCE_ID --field user --limit 20
cqlmatic env inspect .local/pack.json --full

FILE is required. --source TEXT matches an exact source ID, display name, or repository selector; it does not directly match a type selector. Prefer a source ID. --field TEXT is a case-sensitive path substring. --limit N defaults to 20 (range 1–100), independently bounding field and value records in compact filtered output.

Without filters the summary includes all source records, field/value counts, annotations, identity, digest, and date. With filters it returns environment, pack_id, selected fields and their sampled values. --full returns the pack-shaped view and ignores --limit; optional filters still apply, retaining only related records and provenance. A filtered full view retains the original digest and is not an importable replacement snapshot. Use the original unfiltered file for import. Inspection is offline and never reads credentials.

Import

cqlmatic env import --from snapshot.json --out .local/imported.json
cqlmatic env import --from examples/legacy-observation --environment examples/environment.json --out .local/example-pack.json

Required flags are --from FILE_OR_DIRECTORY and --out FILE. Native files must pass identity/integrity/profile/record validation. --environment FILE optionally asserts matching identity for native input and is required for legacy directory input. Choose a separate output path that does not alias the native input, environment file, or any legacy corpus component. Import reads inputs before writing the chosen destination but does not enforce that separation; --replace can overwrite an input selected as output, including a legacy sources.jsonl. Inputs stay unchanged only when output is separate. Replacement does not perform a refresh merge. The JSON report identifies the imported path/digest. A durability failure can report active_pack_updated:true with exit 2; inspect the output before retrying. See import mechanics.

Discover

--state and --answer require --mcp. Answer files are entire saved MCP tool results, not edited rows. needs-probes and activation-blocked exit 3; neither means complete. API execution and MCP relay have different lock, receipt, cleanup and recovery semantics. See environment discovery, MCP workflow, and failure recovery.

cqlmatic env discover --request examples/discover.request.json

The example above is a safe offline plan. Live searches require the operator's own explicit target, UTC bounds, authorization, permissions, and budgets. A pack's searchable view differs from a #repo selector.

Parsers

env parsers --environment FILE accepts optional --credentials-file FILE, --id ID, --template, --offset N, and --limit N. It performs authenticated read-only metadata access with a 30-second deadline and returns backend JSON, not an automatically bound parser contract.

Without --id, offset defaults to 0 (maximum 9999) and limit to 50 (range 1–100); pagination is explicit. With --id, retrieve that parser definition; --template retrieves its template and requires --id. IDs are bounded to 256 characters without controls. --offset/--limit are list options and do not page an ID lookup. Full inventory/review uses the inventory workflow.

Exit codes

Argument-parser errors also return 2; help/version return 0. JSONL returns the highest record exit, unless a global failure ends the stream. Always inspect returned evidence and diagnostics: an exit alone does not establish inventory completion, unchanged files, or correct/complete search results.

Environment and native configuration

Client configuration is version-sensitive. Setup checks installed capabilities and previews the exact native command; use official Codex MCP documentation and VS Code MCP configuration for the host's own options. CQLmatic's adapter coverage is narrower than every configuration the host might support.

Use it from an agent

Follow the analyst workflow and MCP companion guide. Use full requests for explicit context, retain query bytes, consume the documented output type for each command, select the pack explicitly, and inspect results after authorized execution. Packaged agent instructions are optional guidance; no skill installation is required for the CLI.