Skip to main content
Reference
Send one v3 query request to a local instance or a Helix Cloud database and print the JSON response. Local and Cloud.

Usage

Exactly one input is required. Query bundles are not supported.

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 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

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.
  • read posts to /v1/databases:query-read and needs database.query.read on the database’s project; write posts to /v1/databases:query-write and needs database.query.write.
  • The body is {"database":{"tenantId":"<id>"},"queryJson":"<base64 request>"} (clusterId for a dedicated cluster); the CLI decodes the reply’s responseJson and statusCode. 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

  • -e and --ts-file need Node.js 20+ on PATH. The expression must evaluate to a readBatch() or writeBatch() builder. No running instance is needed to build the request.
  • The first run npm installs the pinned @helix-db/helix-db@3.1.0 SDK into ts-runtime/ under the Helix cache directory (override with HELIX_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, with npm is required to install the TypeScript query runtime. Use --file or --body instead.

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