Skip to main content
Tutorial
For the complete documentation index optimized for AI agents, see llms.txt.
Prerequisites
  • Docker or Podman (for the local helixdb 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 Helix Cloud account is only required if you want to query a Helix Cloud cluster from the CLI.

​
Agent quickstart

If you are starting a new project inside a coding-agent environment, use helix chef:
helix chef asks what you want to build, then lets you choose automatic or manual setup. It installs the Helix skills, connects the Helix docs MCP at https://docs.helix-db.com/mcp, scaffolds a local project (helix init local), starts the dev instance, seeds starter data, writes a HELIX_CHEF_PROMPT.md build prompt, and launches your coding agent (Claude Code, Codex, or OpenCode) to generate the app from your build intent.
Auth and non-interactive use. The first interactive run signs you in to Helix Cloud via a GitHub device-code flow (used only for an optional, anonymized setup snapshot). When stdin is not a TTY — agents, CI, sandboxes — helix chef skips this login automatically and proceeds without it; set HELIX_SKIP_CLOUD_AUTH=1 to opt out in an interactive shell too.For a fully scriptable setup with no Cloud auth, skip chef and scaffold by hand: helix init local → helix start dev → helix query dev --file … (see the Local quickstart below). This path never prompts and never logs in.

​
Local quickstart

1

Install the Helix CLI

If you already have the CLI installed, update it with helix update.
2

Create a new project

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 start pulls ghcr.io/helixdb/helixdb:v0.0.4, starts a background container named helix-<project>-dev, publishes port 6969, and waits for GET /healthz to report ready before returning.To stream logs in the foreground instead, use helix start dev --foreground and stop the container with Ctrl-C.For persistent local data, use helix start dev --disk. Disk mode starts a CLI-managed MinIO sidecar and keeps data across helix stop.
The default helixdb storage mode is in-memory. Stopping or restarting an in-memory instance wipes all local data.
4

Send a dynamic query

The example request runs a read query that counts User nodes. Pass --compact to print on a single line, or --warm to populate caches. A standalone local warm read prints its normal response; Helix Cloud fanout returns no body.
5

Stop the instance when you are done

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.

​
Helix Cloud quickstart

To query a Helix Cloud cluster from the CLI:
1

Authenticate

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

Pick a workspace and project

3

Initialize or add a Helix Cloud instance

4

Sync metadata and query

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. Helix Cloud fanout returns no response body; standalone local warming returns the normal body.
  • Every traversal must contain a source operation before a terminal operation such as count.
  • Pass subcommands explicitly (helix init local …, helix add cloud …) — 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

Helix Cloud workflow

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

CLI Command Reference

Every command, subcommand, and flag

Troubleshooting

Solutions to common issues