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 the first supported agent it finds: Claude Code → OpenAI Codex → OpenCode → Cursor Agent.
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 follow the canonical local quickstart. This path never prompts and never logs in.

​
Local quickstart

Windows PowerShell installs the CLI with:
Use the canonical local quickstart for the executable helix init local → helix start dev → helix query dev → helix stop dev journey. It lists the exact generated files, instance name, and query file so this CLI guide does not maintain a second copy of the tutorial.

​
Version names

  • HelixDB v3 is the current product and SDK generation.
  • Helix CLI 3.x is the independently released command-line client. Run helix --version for the exact installed release.
  • POST /v2/query is the current HTTP wire endpoint. The endpoint version is independent of the product and CLI versions.

​
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