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.
Prerequisites
  • Docker or Podman (for the local enterprise-dev runtime)
  • Git (recommended for version-controlling your project)
  • Node.js/npm if you use helix chef, which runs npx for agent skills and MCP setup
  • A V2 Cloud account is only required if you want to query a V2 Cloud cluster from the CLI.

​
Agent quickstart

If you are starting a new project inside a coding-agent environment, use helix chef: 
helix chef
helix chef asks what you want to build, then lets you choose automatic or manual setup. Automatic setup installs the Helix skills, connects the Helix docs MCP at https://docs.helix-db.com/mcp, creates ~/my-first-helix-project, starts dev, writes starter dynamic query files, seeds example data, and opens the dashboard. To skip prompts and run the automatic flow directly: 
helix chef --auto
The command writes HELIX_CHEF_PROMPT.md into the new project. This is a placeholder for the active coding agent to replace the starter JSON requests with app-specific Helix queries based on your build idea.

​
Local quickstart

1

Install the Helix CLI

curl -sSL "https://install.helix-db.com" | bash
If you already have the CLI installed, update it with helix update.
2

Create a new project

mkdir my-helix-app
cd my-helix-app
helix init
helix init scaffolds:
  • helix.toml with a single [local.dev] instance.
  • .helix/ workspace state (added to .gitignore).
  • examples/request.json — a runnable read request you can send straight away.
In a TTY, helix init prompts you to pick local or enterprise. Pass the subcommand directly to skip the prompt: helix init local.
3

Run the local dev runtime

helix run dev
helix run pulls ghcr.io/helixdb/database-dev:latest, starts a background container named helix-<project>-dev, publishes port 8080, and waits until the local gateway accepts POST /v1/query before returning.To stream logs in the foreground instead, use helix run dev --foreground and stop the container with Ctrl-C.For persistent local data, use helix run dev --disk. Disk mode starts a CLI-managed MinIO sidecar and keeps data across helix stop.
The default enterprise-dev storage mode is in-memory. Stopping or restarting an in-memory instance wipes all local data.
4

Send a dynamic query

helix query dev --file examples/request.json
The example request runs a read query that counts User nodes. Pass --compact to print on a single line, or --warm to populate caches without printing a response body.
5

Stop the instance when you are done

helix stop dev
helix stop is idempotent — it reports cleanly if the instance was not running.
Edit examples/request.json (or write your own JSON files) and run helix query dev --file … again to iterate. See the helix query reference for the request shape and validation rules.

​
V2 Cloud quickstart

To query a V2 Cloud cluster from the CLI:
1

Authenticate

helix auth login
Credentials are stored in ~/.helix/credentials.
2

Pick a workspace and project

helix workspace list
helix workspace switch <workspace>
helix project list
helix project switch <project>
helix cluster list
3

Initialize or add a V2 Cloud instance

helix init enterprise --cluster-id <cluster-id>
# or, in an existing project:
helix add enterprise --name production --cluster-id <cluster-id>
4

Sync metadata and query

helix sync production
export HELIX_API_KEY="..."   # or whatever query_auth_env resolves to
helix query production --file examples/request.json
helix sync writes the gateway URL and auth contract into helix.toml. If gateway_url is missing after sync, set it manually or re-run helix sync once your cluster is reachable.

​
Tips

  • Edit examples/request.json (or any other file) and run helix query dev --file … again.
  • Read requests can be replayed with --warm to pre-populate caches without printing output.
  • Every dynamic query must start with a source step (for example NWhere) before a terminal step like Count.
  • Pass subcommands explicitly (helix init local …, helix add enterprise …) — the CLI never prompts when stdin is not a TTY.
  • Use --yes for destructive operations in non-interactive contexts: helix delete <INSTANCE> --yes, helix prune --all --yes.
  • helix stop exits cleanly when the instance is not running, so it is safe to call unconditionally in teardown.
  • helix stop <instance> stops a running container.
  • helix prune removes Helix-owned containers, workspace state, and disk-mode volumes. It never runs a broad docker system prune.
  • helix delete <instance> removes the instance from helix.toml and cleans up local runtime state.
  • Commit helix.toml and any *.json request files you author.
  • .helix/, target/, and *.log are added to .gitignore by helix init.
  • Credentials in ~/.helix/credentials are user-global and should never be committed.

​
Next Steps

Local workflow

The full local init/run/query loop with iteration tips

V2 Cloud workflow

Authenticate, link a project, and query a V2 Cloud cluster

CLI Command Reference

Every command, subcommand, and flag

Troubleshooting

Solutions to common issues