Skip to main content

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.

For the complete documentation index optimized for AI agents, see llms.txt.
The Helix CLI’s V2 Cloud surface covers authentication, workspace/project/cluster selection, instance metadata sync, log retrieval, and dynamic queries against a remote gateway. Cluster provisioning, scaling, and stored-procedure deployment happen in the Helix control plane — not in the CLI.

​
Prerequisites

  • A Helix Cloud account with at least one workspace and V2 Cloud cluster.
  • A local Helix project (helix init in any directory).

​
End-to-end flow

1

Authenticate

helix auth login
Opens a browser-based GitHub device flow. Credentials are stored in ~/.helix/credentials.To use the CLI from CI or another non-browser environment, rotate a cluster API key and export it as HELIX_API_KEY:
helix auth create-key <cluster-id>
export HELIX_API_KEY="..."
2

Pick a workspace

helix workspace list
helix workspace switch <workspace-slug>
The selection is persisted in ~/.helix/config and applies to all subsequent V2 Cloud commands.
3

Link a project

helix project list
helix project switch <project>
Linking writes [project] workspace_id and [project] id to your local helix.toml.
4

Discover clusters and add an instance

helix cluster list
helix add enterprise --name production --cluster-id <cluster-id>
Or scaffold a brand-new V2 Cloud-linked project with helix init enterprise --cluster-id <cluster-id>.
5

Sync gateway and auth metadata

helix sync production
helix sync writes the latest gateway_url, query_auth_header, query_auth_env, and node-type values from the cloud into [enterprise.production] in helix.toml. Re-run after any cluster change.If the cluster has not published a gateway_url yet, the CLI prints a warning. Set gateway_url manually under [enterprise.production] once you know it, or re-run helix sync later.
6

Send dynamic queries

export HELIX_API_KEY="..."   # value for the configured query_auth_env
helix query production --file examples/request.json
helix query posts to <gateway_url>/v1/query with the header named by query_auth_header (default Authorization).
7

Pull historical logs

helix logs production \
  --range \
  --start 2026-05-12T00:00:00Z \
  --end   2026-05-12T01:00:00Z
V2 Cloud logs are queried over a time range. Live --follow is not yet supported for V2 Cloud instances.

​
Reference: per-instance auth contract

Each [enterprise.<instance>] block stores the auth contract used by helix query:
FieldDefaultPurpose
query_auth_headerAuthorizationHTTP header name set on every query request.
query_auth_envHELIX_API_KEYEnvironment variable the CLI reads to populate the header value.
Override the variable name per-instance by setting query_auth_env under [enterprise.<instance>] and exporting whatever name you choose.

​
Common errors

ErrorResolution
Authentication required. Run 'helix auth login' first.Run helix auth login (or set up an API key via helix auth create-key).
Enterprise gateway URL is not configured for '<instance>'.Run helix sync <instance>, or set gateway_url manually under [enterprise.<instance>].
Environment variable HELIX_API_KEY is required for Enterprise query authExport the variable named by query_auth_env.
live Enterprise logs are not supported yetUse helix logs <instance> --range --start … --end … instead of --follow.

​
What next?

Local workflow

Run the local dev runtime and iterate on JSON requests

CLI Command Reference

Every command, subcommand, and flag