Skip to main content
For the complete documentation index optimized for AI agents, see llms.txt.
The CLI handles authentication, workspace/project/cluster selection, metadata sync, log retrieval, and dynamic queries against a remote gateway. Cluster provisioning and scaling happen in the Helix control plane, not the CLI.

​
Prerequisites

  • A Helix Cloud account with at least one workspace and Helix 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 Helix 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 cloud --name production --cluster-id <cluster-id>
Or scaffold a brand-new Helix Cloud-linked project with helix init cloud --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
Helix Cloud logs are queried over a time range. Live --follow is not yet supported for Helix 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

For Helix Cloud auth, gateway, and logging errors, see Troubleshooting.

​
What next?

Local workflow

Run the local dev runtime and iterate on JSON requests

CLI Command Reference

Every command, subcommand, and flag