> ## 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. # Configuration Guide > Reference for helix.toml, ~/.helix/config, and credentials > For the complete documentation index optimized for AI agents, see [llms.txt](/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` — Helix 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. ```toml theme={"languages":{"custom":["languages/helixql.json"]}} [project] name = "my-helix-app" [local.dev] port = 6969 image = "ghcr.io/helixdb/enterprise-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]` | Key | Type | Required | Default | Description | | ------------------- | -------------------- | -------- | -------- | ------------------------------------------------------------------------------------------------- | | `name` | String | Yes | — | Project name. Used in the container name pattern `helix--`. | | `id` | String | No | — | Linked Helix Cloud project ID. Set by [`helix project switch`](/cli/command-reference/project). | | `workspace_id` | String | No | — | Linked Helix Cloud workspace ID. Set by [`helix project switch`](/cli/command-reference/project). | | `container_runtime` | `docker` \| `podman` | No | `docker` | Runtime used to manage local containers. | ### `[local.]` One block per local instance. The instance name is the table key (e.g. `[local.dev]`). | Key | Type | Default | Description | | --------- | ------------------ | -------------------------------- | ------------------------------------------------------------------------------------ | | `port` | Number | `6969` | Host port published to container port `8080`. | | `image` | String | `ghcr.io/helixdb/enterprise-dev` | Container image used by [`helix start`](/cli/command-reference/start). | | `tag` | String | `latest` | Image tag. | | `storage` | `memory` \| `disk` | `memory` | Local 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: ```toml theme={"languages":{"custom":["languages/helixql.json"]}} [local.dev] port = 6969 [local.staging] port = 9090 storage = "disk" ``` You can also use `helix start --disk` as a one-off disk-mode run without changing `helix.toml`. ### `[enterprise.]` One block per Helix Cloud instance. Most fields here are populated automatically by [`helix sync`](/cli/command-reference/sync). | Key | Type | Required | Default | Description | | ------------------- | ------ | --------------------------- | --------------- | ----------------------------------------------------------------------------------------------------- | | `cluster_id` | String | Yes | — | Helix Cloud cluster ID. List clusters with [`helix cluster list`](/cli/command-reference/cluster). | | `workspace_id` | String | No | — | Workspace the cluster belongs to. | | `project_id` | String | No | — | Linked project ID. | | `gateway_url` | URL | No (required at query time) | — | Runtime gateway base URL. Populated by `helix sync` when available. | | `query_auth_header` | String | No | `Authorization` | HTTP header name used for query auth. | | `query_auth_env` | String | No | `HELIX_API_KEY` | Environment variable read by [`helix query`](/cli/command-reference/query) for the auth header value. | | `availability_mode` | String | No | — | Cluster availability mode, returned by `helix sync`. | | `gateway_node_type` | String | No | — | Gateway node type, returned by `helix sync`. | | `db_node_type` | String | No | — | DB node type, returned by `helix sync`. | If `gateway_url` is missing, [`helix query `](/cli/command-reference/query) fails with: ``` Enterprise gateway URL is not configured for ''. Run 'helix sync ' or set gateway_url in helix.toml. ``` ## `~/.helix/config` User-global configuration written by [`helix workspace switch`](/cli/command-reference/workspace). ```toml theme={"languages":{"custom":["languages/helixql.json"]}} workspace_id = "ws_01HX..." ``` This file is independent of any project directory and applies to every Helix Cloud command you run. ## `~/.helix/credentials` Written by [`helix auth login`](/cli/command-reference/auth). Plain key=value format: ``` helix_user_id=usr_01HX... helix_user_key=hlxk_... ``` Remove with `helix auth logout`. Never commit this file. ## Environment variables | Variable | Used by | Description | | ------------------------- | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `HELIX_API_KEY` (default) | [`helix query`](/cli/command-reference/query) | Per-cluster Helix 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 start`** — change the port in `[local.] port`, or pass `helix start --port ` to override for a single run. * **`Missing instances`** — `helix.toml` has no `[local.*]` or `[enterprise.*]` blocks. Add one with [`helix add`](/cli/command-reference/add). * **`Authentication required`** — run `helix auth login` for Helix 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.]`. ## Next Steps The local init/run/query loop Solve common CLI issues