Reference
Send one v3 query request to a local instance or a Helix Cloud database and print the JSON
response. Local and Cloud.
Usage
Request shape
A--file or --body request is one JSON object, the envelope POST /v2/query accepts.
helix init local writes this one, which counts User nodes, to examples/request.json:
The CLI checks only
request_type and that query exists; the server validates the rest. See the
request envelope for every field, and
Reading data and
Writing data for the operations. -e and
--ts-file build this JSON with the TypeScript SDK.
Arguments
Options
Input (pick one)
Connection (local only)
Output
Behavior
Target resolution
- A typed
tenant:<id>/cluster:<id>target works without ahelix.toml. - With no target, the CLI uses the
devinstance (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--warmare local options; Cloud targets reject them.- If nothing is listening, the error suggests
helix start <instance>.
Cloud queries
Cloud queries use your WorkOS session and go through the broker, the Helix Cloud backend service that forwards them to your database. The CLI never calls the gateway (the endpoint applications reach with an application key) directly.readposts to/v1/databases:query-readand needsdatabase.query.readon the database’s project;writeposts to/v1/databases:query-writeand needsdatabase.query.write.- The body is
{"database":{"tenantId":"<id>"},"queryJson":"<base64 request>"}(clusterIdfor a dedicated cluster); the CLI decodes the reply’sresponseJsonandstatusCode. This API accepts only WorkOS sessions, not service credentials or application keys; see Run in CI. - 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
-eand--ts-fileneed Node.js 20+ onPATH. The expression must evaluate to areadBatch()orwriteBatch()builder. No running instance is needed to build the request.- The first run
npm installs the pinned@helix-db/helix-db@3.1.0SDK intots-runtime/under the Helix cache directory (override withHELIX_CACHE_DIR), so it needs npm and npm registry access. Later runs reuse it. - Without Node.js the command fails with
Node.js is required to run TypeScript queries; without npm on the first run, withnpm is required to install the TypeScript query runtime. Use--fileor--bodyinstead.
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. --jsonprints only the compact JSON response.--quietstill prints the response but drops the footer.- An empty response prints nothing. A non-2xx response fails with the HTTP status and body.
Examples
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.