> ## Documentation Index
> Fetch the complete documentation index at: https://docs.helix-db.com/llms.txt
> Use this file to discover all available pages before exploring further.

# helix query

> Execute a direct Helix v3 query locally or through the Cloud broker

<div className="flex flex-wrap gap-2"><Badge color="gray" size="sm">Reference</Badge></div>

```bash theme={"languages":{"custom":["languages/helixql.json"]}}
helix query [INSTANCE] --file <request.json> [--compact]
helix query [INSTANCE] --json '<v3-json>' [--compact]
helix query [INSTANCE] -e '<typescript-expression>' [--compact]
helix query [INSTANCE] --ts-file <query.ts> [--compact]
```

Exactly one input is required. The envelope must include lowercase `request_type` (`read` or `write`)
and `query`. Query bundles are not supported.

Local queries post to the auth-disabled local `/v2/query`; `--host`, `--port`, and read-only `--warm`
are local options. With no target, the CLI uses local `dev` or the sole linked instance; ambiguous
projects must specify an instance or an explicit `tenant:<id>` / `cluster:<id>`. Cloud queries use the
WorkOS session:

* `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.