helix query

​

Usage

helix query [INSTANCE] --file <request.json>
helix query [INSTANCE] --body '<v3-json>'
helix query [INSTANCE] -e '<typescript-expression>'
helix query [INSTANCE] --ts-file <query.ts>

​

Arguments

​

Options

​

Input (pick one)

​

Connection (local only)

​

Output

​

Behavior

​

Target resolution

• A typed tenant:<id> / cluster:<id> target works without a helix.toml.
• With no target, the CLI uses the dev instance (local or Cloud), then the only instance, then a picker in a terminal.
• Otherwise it fails and lists the instances you can pass.

​

Local queries

• Local queries post to the auth-disabled local /v2/query.
• --host, --port, and read-only --warm are local options; Cloud targets reject them.
• If nothing is listening, the error suggests helix start <instance>.

​

Cloud queries

• read uses the backend read-query RPC and requires database.query.read.
• write uses the backend write-query RPC and requires database.query.write.
• The backend rejects an operation/envelope mismatch before gateway dispatch.
• No database key, custom auth header, or direct gateway URL is accepted.
• A mutation is never retried after dispatch, timeout, or ambiguous transport failure.
• Cloud query bodies, parameters, results, operational gateway authorization, and credentials are not logged by the broker.

​

TypeScript input

• -e and --ts-file need Node.js 20+. The expression must evaluate to a readBatch() or writeBatch() builder.
• On first use, the CLI installs the pinned @helix-db/helix-db SDK into the Helix cache directory (override with HELIX_CACHE_DIR). No running instance is needed to build the request.

​

Output

• The response goes to stdout as syntax-highlighted, pretty-printed JSON. A dim footer with the HTTP status, latency, and target (for example 200 OK · 12ms · dev) goes to stderr, so stdout stays pipeable.
• --json prints only the compact JSON response. --quiet still prints the response but drops the footer.
• An empty response prints nothing. A non-2xx response fails with the HTTP status and body.

​

Examples

# Send a request file to the default target
helix query --file examples/request.json

# Target a named local instance and print one line of JSON
helix query dev --file examples/request.json --json

# Build the request from a TypeScript DSL expression
helix query -e 'readBatch().varAs("c", g().nWithLabel("User").count()).returning(["c"])'

# Query an explicit Cloud database, no helix.toml needed
helix query tenant:<id> --file request.json

​

Related

• helix shell — send several requests interactively.
• helix start — start the local instance you query.
• Local workflow — iterate on queries locally.
• Helix Cloud workflow — query a Cloud database.