> ## Documentation Index
> Fetch the complete documentation index at: https://helix-isolate-failing-index-entities.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# helix query

> Execute a direct Helix v3 query against a local instance or a Cloud database

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

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

## Usage

```bash theme={null}
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>
```

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

## Arguments

| Argument | Description |
| - | - |
| `INSTANCE` | Instance name from `helix.toml`, or an explicit `tenant:<id>` / `cluster:<id>` Cloud database. See [Target resolution](#target-resolution) for the default. |

## Options

### Input (pick one)

| Flag | Description | Default |
| - | - | - |
| `-f`, `--file <REQUEST.json>` | Read the request from a JSON file. | — |
| `--body <JSON>` | Read the request from an inline JSON string. | — |
| `-e`, `--ts <TS>` | Build the request from a TypeScript DSL expression, like `mysql -e`. | — |
| `--ts-file <QUERY.ts>` | Build the request from a TypeScript DSL file. | — |

### Connection (local only)

| Flag | Description | Default |
| - | - | - |
| `--host <HOST>` | Override the host. | `localhost` |
| `--port <PORT>` | Override the port. | The instance's port in `helix.toml` |
| `--warm` | `read` requests only: pre-warm caches with the `X-Helix-Warm` header. | Off |

### Output

| Flag | Description | Default |
| - | - | - |
| `--json` | Print the response as compact JSON only, with no footer. | Off (highlighted, pretty-printed) |

## 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 the WorkOS session and go through the broker — the Helix Cloud backend service
that forwards CLI queries to your database. The CLI never calls the Cloud gateway (the database
endpoint that applications reach with an application key) directly.

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

```bash theme={null}
# 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`](/cli/command-reference/shell) — send several requests interactively.
* [`helix start`](/cli/command-reference/start) — start the local instance you query.
* [Local workflow](/cli/workflows/local) — iterate on queries locally.
* [Helix Cloud workflow](/cli/workflows/helix_cloud) — query a Cloud database.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.