> ## 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.

# Getting started with HelixDB CLI

> Install the Helix CLI v2, bootstrap a first app, run a local instance, and send your first dynamic query

> For the complete documentation index optimized for AI agents, see [llms.txt](/llms.txt).

<Warning>
  **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`](/cli/command-reference/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.
</Warning>

## Agent quickstart

If you are starting a new project inside a coding-agent environment, use `helix chef`:

```bash theme={"languages":{"custom":["languages/helixql.json"]}}
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.

<Note>
  **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.
</Note>

## Local quickstart

<Steps>
  <Step title="Install the Helix CLI">
    ```bash theme={"languages":{"custom":["languages/helixql.json"]}}
    curl -sSL "https://install.helix-db.com" | bash
    ```

    If you already have the CLI installed, update it with [`helix update`](/cli/command-reference/update).
  </Step>

  <Step title="Create a new project">
    ```bash theme={"languages":{"custom":["languages/helixql.json"]}}
    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`.
  </Step>

  <Step title="Run the local dev runtime">
    ```bash theme={"languages":{"custom":["languages/helixql.json"]}}
    helix start dev
    ```

    `helix start` pulls `ghcr.io/helixdb/enterprise-dev:latest`, starts a background container named `helix-<project>-dev`, publishes port `6969`, and waits until the local gateway accepts `POST /v1/query` 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`.

    <Warning>
      The default `enterprise-dev` storage mode is in-memory. Stopping or restarting an in-memory instance wipes all local data.
    </Warning>
  </Step>

  <Step title="Send a dynamic query">
    ```bash theme={"languages":{"custom":["languages/helixql.json"]}}
    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.
  </Step>

  <Step title="Stop the instance when you are done">
    ```bash theme={"languages":{"custom":["languages/helixql.json"]}}
    helix stop dev
    ```

    `helix stop` is idempotent — it reports cleanly if the instance was not running.
  </Step>
</Steps>

Edit `examples/request.json` (or write your own JSON files) and run `helix query dev --file …` again to iterate. See the [`helix query`](/cli/command-reference/query) reference for the request shape and validation rules.

## Helix Cloud quickstart

To query a Helix Cloud cluster from the CLI:

<Steps>
  <Step title="Authenticate">
    ```bash theme={"languages":{"custom":["languages/helixql.json"]}}
    helix auth login
    ```

    Credentials are stored in `~/.helix/credentials`.
  </Step>

  <Step title="Pick a workspace and project">
    ```bash theme={"languages":{"custom":["languages/helixql.json"]}}
    helix workspace list
    helix workspace switch <workspace>
    helix project list
    helix project switch <project>
    helix cluster list
    ```
  </Step>

  <Step title="Initialize or add a Helix Cloud instance">
    ```bash theme={"languages":{"custom":["languages/helixql.json"]}}
    helix init cloud --cluster-id <cluster-id>
    # or, in an existing project:
    helix add cloud --name production --cluster-id <cluster-id>
    ```
  </Step>

  <Step title="Sync metadata and query">
    ```bash theme={"languages":{"custom":["languages/helixql.json"]}}
    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.
  </Step>
</Steps>

## Tips

<AccordionGroup>
  <Accordion title="Iterating on queries">
    * 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`.
  </Accordion>

  <Accordion title="Scripting and CI">
    * 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`](/cli/command-reference/delete), [`helix prune --all --yes`](/cli/command-reference/prune).
    * `helix stop` exits cleanly when the instance is not running, so it is safe to call unconditionally in teardown.
  </Accordion>

  <Accordion title="Cleaning up">
    * `helix stop <instance>` stops a running container.
    * [`helix prune`](/cli/command-reference/prune) removes Helix-owned containers, workspace state, and disk-mode volumes. It never runs a broad `docker system prune`.
    * [`helix delete <instance>`](/cli/command-reference/delete) removes the instance from `helix.toml` and cleans up local runtime state.
  </Accordion>

  <Accordion title="Version control">
    * 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.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Local workflow" icon="computer" href="/cli/workflows/local">
    The full local init/run/query loop with iteration tips
  </Card>

  <Card title="Helix Cloud workflow" icon="cloud" href="/cli/workflows/helix_cloud">
    Authenticate, link a project, and query a Helix Cloud cluster
  </Card>

  <Card title="CLI Command Reference" icon="terminal" href="/cli/command-reference">
    Every command, subcommand, and flag
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/cli/troubleshooting">
    Solutions to common issues
  </Card>
</CardGroup>