Skip to main content
Reference
The CLI reads instances from the project’s helix.toml, keeps your Helix Cloud session and its own state in ~/.helix, and reads a few environment variables. There is no user-global workspace or project selection.

Project file

helix init writes helix.toml at the project root. Other commands find it by walking up from the current directory, so they work from any subdirectory; without one they fail with no helix.toml found. Two local instances, one on S3 storage, and a linked Cloud database:
Every command except helix add needs at least one local or Cloud instance.

Instance names

<name> is the instance name commands take, as in helix start dev or helix query production: 1 to 32 ASCII letters, digits, -, and _. helix add refuses a name either table already uses. Instance names exist only in helix.toml, apart from Cloud resource names and slugs: an instance named production can link a Cloud database named orders. See Targets and resolution.

[project]

Cloud commands in the project default to the project in id, or, without it, to the project_id that every [enterprise.*] table shares.

[local.<name>]

[local.<name>.s3]

Required when storage = "s3"; an error with any other storage mode. S3 credentials never go in helix.toml. helix start loads .env from the project root and passes the AWS_* environment variables into the container it creates. helix restart keeps the container’s original values; run helix start to apply new ones.

[enterprise.<name>]

Links a Helix Cloud database by stable ID. Gateway URLs, application keys, query auth headers or environment variables, sync metadata, and query bundles have no key here.

Unknown keys

A misspelled [local.<name>] key is ignored: storge = "disk" leaves the instance in memory, so its data is lost when it stops. Check the storage mode in the ENDPOINT column of helix status.

Commands that rewrite the file

helix add, helix delete, helix start --persist, helix project link, and helix project create --link rewrite the whole file from what the CLI parsed. A rewrite:
  • removes every comment;
  • writes keys in the CLI’s order, and may reorder the instance tables;
  • drops unknown keys in [local.*] tables;
  • writes defaults explicitly, including queries, container_runtime, image, and tag.
Keep notes outside helix.toml, and review the diff after these commands.

Image pinning

helix init local and helix add local write the CLI’s current default image and tag. An instance keeps that tag after helix update; only instances added later get the new default. An instance without a tag key follows the CLI’s default until a rewrite writes it. To move an instance to the image the current CLI ships with:
  1. With the instance running, run helix doctor <instance>. Its runtime.image check reports pins an older server image and names this CLI’s tag.
  2. Start on that tag and save it to [local.dev], or edit tag by hand and run helix start dev:
    helix start replaces the container, so an in-memory instance starts empty.

Helix home

CLI state lives in ~/.helix (%USERPROFILE%\.helix on Windows), or in $HELIX_HOME when set and not empty. In a project, .helix/<instance>/ holds per-instance state. helix init adds .helix/ and .env to .gitignore.

Environment variables