Skip to main content
For the complete documentation index optimized for AI agents, see llms.txt.
Initialize a v2 Helix project. Creates helix.toml, a .helix/ workspace directory, a .gitignore entry, and — for local projects — an examples/request.json scaffold.

​
Usage

helix init [OPTIONS] [SUBCOMMAND]
If you omit the subcommand in a TTY, the CLI prompts you to choose between local and enterprise.

​
Available sub-commands

Sub-commandDescription
localInitialize a local v2 development project.
enterpriseInitialize a Helix Cloud project linked to a cluster.

​
Top-level flags

FlagTypeDescriptionDefault
-p, --pathPathProject directory to initialize.Current directory
--skillsBooleanInstall the Helix agent skills + docs MCP (the install you’d otherwise be prompted for).Prompted in a TTY
--no-skillsBooleanSkip installing the Helix agent skills + docs MCP.Prompted in a TTY
--skills / --no-skills are accepted either before or after the subcommand — both helix init --no-skills local and helix init local --no-skills work. They are mutually exclusive. When neither is given, an interactive run prompts you and a non-interactive run skips the install. To install or refresh the skills later, use helix skills.

​
helix init local

FlagTypeDescriptionDefault
-n, --nameStringLocal instance name.dev
--portNumberHost port for the local gateway. The container always listens on 8080 internally.6969
--diskBooleanPersist local data with on-disk storage backed by a CLI-managed MinIO volume.false
Interactive local init prompts for the storage mode and defaults to in-memory.

​
helix init cloud

FlagTypeRequiredDescriptionDefault
-n, --nameStringNoHelix Cloud instance name.production
--cluster-idStringYesHelix Cloud cluster ID. Find one with helix cluster list.—
--gateway-urlURLNoRuntime gateway URL for dynamic queries. If omitted, run helix sync after init to fetch it.—
helix init cloud requires Helix Cloud authentication. Run helix auth login first.

​
What helix init produces

  • helix.toml — project configuration with one [local.<name>] or [enterprise.<name>] instance.
  • .helix/ — CLI-managed workspace state (ignored from git).
  • .gitignore — entries appended for .helix/, target/, and *.log.
  • examples/request.json (local only) — a runnable read request you can send with helix query:
{
  "request_type": "read",
  "query": {
    "queries": [
      {
        "Query": {
          "name": "node_count",
          "steps": [
            { "NWhere": { "Eq": ["$label", { "String": "User" }] } },
            "Count"
          ],
          "condition": null
        }
      }
    ],
    "returns": ["node_count"]
  },
  "parameters": {}
}

​
Examples

# Interactive init in the current directory (prompts in a TTY)
helix init

# Initialize a local project in a new directory
helix init --path ./my-helix-app local

# Local with a custom instance name and port
helix init local --name staging --port 9090

# Local with persistent on-disk storage by default
helix init local --disk

# Helix Cloud project linked to an existing cluster
helix init cloud --cluster-id ec_01HX... --gateway-url https://gateway.example.com

​
Next steps after helix init local

helix start dev
helix query dev --file examples/request.json

​
Next steps after helix init cloud

helix sync <instance>
helix query <instance> --file <request.json>