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.
This page documents the configuration files the Helix CLI reads and writes:
  • helix.toml — per-project configuration in your project root.
  • ~/.helix/config — user-global state, currently the selected workspace.
  • ~/.helix/credentials — V2 Cloud credentials written by helix auth login.

​
helix.toml

helix init creates helix.toml in your project root. Everything the CLI knows about your project lives here. 
[project]
name = "my-helix-app"

[local.dev]
port = 8080
image = "ghcr.io/helixdb/database-dev"
tag = "latest"
# Optional; defaults to in-memory when omitted.
# storage = "disk"

[enterprise.production]
cluster_id = "ec_01HX..."
gateway_url = "https://gateway.example.com"
At least one [local.*] or [enterprise.*] instance is required. The CLI rejects an empty helix.toml.

​
[project]

KeyTypeRequiredDefaultDescription
nameStringYes—Project name. Used in the container name pattern helix-<project>-<instance>.
idStringNo—Linked V2 Cloud project ID. Set by helix project switch.
workspace_idStringNo—Linked V2 Cloud workspace ID. Set by helix project switch.
container_runtimedocker | podmanNodockerRuntime used to manage local containers.

​
[local.<instance>]

One block per local instance. The instance name is the table key (e.g. [local.dev]).
KeyTypeDefaultDescription
portNumber8080Host port published to container port 8080.
imageStringghcr.io/helixdb/database-devContainer image used by helix run.
tagStringlatestImage tag.
storagememory | diskmemoryLocal storage mode. disk uses a CLI-managed MinIO container and persistent volume.
You can define as many local instances as you want, each on a different port: 
[local.dev]
port = 8080

[local.staging]
port = 9090
storage = "disk"
You can also use helix run <instance> --disk as a one-off disk-mode run without changing helix.toml.

​
[enterprise.<instance>]

One block per V2 Cloud instance. Most fields here are populated automatically by helix sync.
KeyTypeRequiredDefaultDescription
cluster_idStringYes—V2 Cloud cluster ID. List clusters with helix cluster list.
workspace_idStringNo—Workspace the cluster belongs to.
project_idStringNo—Linked project ID.
gateway_urlURLNo (required at query time)—Runtime gateway base URL. Populated by helix sync when available.
query_auth_headerStringNoAuthorizationHTTP header name used for query auth.
query_auth_envStringNoHELIX_API_KEYEnvironment variable read by helix query for the auth header value.
availability_modeStringNo—Cluster availability mode, returned by helix sync.
gateway_node_typeStringNo—Gateway node type, returned by helix sync.
db_node_typeStringNo—DB node type, returned by helix sync.
If gateway_url is missing, helix query <instance> fails with: 
Enterprise gateway URL is not configured for '<instance>'.
Run 'helix sync <instance>' or set gateway_url in helix.toml.

​
~/.helix/config

User-global configuration written by helix workspace switch. 
workspace_id = "ws_01HX..."
This file is independent of any project directory and applies to every V2 Cloud command you run.

​
~/.helix/credentials

Written by helix auth login. Plain key=value format: 
helix_user_id=usr_01HX...
helix_user_key=hlxk_...
Remove with helix auth logout. Never commit this file.

​
Environment variables

VariableUsed byDescription
HELIX_API_KEY (default)helix queryPer-cluster V2 Cloud API key sent in the configured auth header. The variable name is configurable per-instance via query_auth_env.

​
Troubleshooting

  • Port conflict on helix run — change the port in [local.<instance>] port, or pass helix run <instance> --port <port> to override for a single run.
  • Missing instances — helix.toml has no [local.*] or [enterprise.*] blocks. Add one with helix add.
  • Authentication required — run helix auth login for V2 Cloud commands.
  • gateway_url is still missing after helix sync — the cloud-side configuration has not been published yet. Re-run helix sync later, or set gateway_url manually under [enterprise.<instance>].

​
Next Steps

Local workflow

The local init/run/query loop

Troubleshooting

Solve common CLI issues