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.
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 an V2 Cloud project linked to a cluster.

​
Top-level flags

FlagTypeDescriptionDefault
-p, --pathPathProject directory to initialize.Current directory

​
helix init local

FlagTypeDescriptionDefault
-n, --nameStringLocal instance name.dev
--portNumberHost port for the local gateway. The container always listens on 8080 internally.8080
--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 enterprise

FlagTypeRequiredDescriptionDefault
-n, --nameStringNoV2 Cloud instance name.production
--cluster-idStringYesV2 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 enterprise requires V2 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

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

​
Next steps after helix init local

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

​
Next steps after helix init enterprise

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