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
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, andtag.
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:
-
With the instance running, run
helix doctor <instance>. Itsruntime.imagecheck reportspins an older server imageand names this CLI’s tag. -
Start on that tag and save it to
[local.dev], or edittagby hand and runhelix start dev:helix startreplaces 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
Related
- Scripting and CI: JSON output, exit codes, and non-interactive use.
helix start: one-off overrides and--persist.- Targets and resolution: how commands pick instances and Cloud resources.