Get Started

Initialize HelixDB, start a local instance, run the generated query, and stop it

Tutorial

This is the canonical local HelixDB quickstart. You will create a project, start the generated dev instance, run the generated JSON request, and stop the instance.

Prerequisites

• Docker, or Podman configured as described below
• A terminal on macOS or Linux, or PowerShell on Windows

1. Install the CLI

   macOS and Linux:

   curl -sSL "https://install.helix-db.com" | bash
   

   Windows PowerShell:

   irm https://raw.githubusercontent.com/HelixDB/helix-db/main/crates/cli/install.ps1 | iex
   

   If the CLI is already installed, run helix update.

2. Create a local project

   Create and enter an empty directory, then initialize it:

   mkdir my-helix-app
   cd my-helix-app
   helix init local
   

   helix init local creates:

   • helix.toml with one local instance named dev on port 6969.
   • .helix/ for CLI-managed instance state.
   • .gitignore entries for .helix/, .env, target/, and *.log.
   • AGENTS.md with the current CLI workflow for coding agents.
   • examples/request.json with a runnable read request.

   It does not create a Rust, TypeScript, Go, or Python project. Choose an SDK after this CLI journey.

   If you use Podman, set container_runtime = "podman" under [project] in helix.toml before you start the generated instance. New projects otherwise default to Docker.

3. Start the generated instance

   helix start dev
   

   The CLI starts the local container, publishes it at http://localhost:6969, and waits for the database health check before it returns.

   The default storage mode is in-memory. Stopping the instance removes its data. Use helix start dev --disk when you need local persistence.

4. Run the generated query

   helix query dev --file examples/request.json
   

   The generated request counts nodes with the User label. A new database returns a node_count of zero. Edit the JSON file and run the same command again to iterate.

5. Stop the instance

   helix stop dev
   

   helix stop is idempotent, so it also exits successfully when the instance is already stopped.

Use an SDK

The SDKs build the same JSON operation tree that helix query sends to POST /v2/query. Initialize a normal language project and install one released SDK:

Rust

cargo add helix-db@3.0.0 tokio serde_json

Continue with the full setup guide for your language:

Rust SDK

Build and execute typed Rust queries.

TypeScript SDK

Build and execute TypeScript queries.

Go SDK

Build and execute Go queries.

Python SDK

Build and execute synchronous or asynchronous Python queries.

Next steps

Query walkthrough

Learn how SDK builders become the JSON request sent to HelixDB.

Data model

Learn how nodes, edges, labels, and properties fit together.

Writing data

Add, update, and remove graph data.

CLI reference

See every current CLI command and option.