> ## Documentation Index
> Fetch the complete documentation index at: https://helix-drop-improvements.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting started with HelixDB CLI

> Install the Helix CLI 3.x release, bootstrap a first app, run a local instance, and send your first dynamic query

<div className="flex flex-wrap gap-2"><Badge color="green" size="sm">Tutorial</Badge></div>

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

<Warning>
  **Prerequisites**

  * **Docker** or **Podman** (for the local `helixdb` 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 the first supported agent it finds: Claude Code → OpenAI Codex → OpenCode → Cursor Agent.

<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 follow the
  [canonical local quickstart](/database/helix-db/start-here/quickstart). This path
  never prompts and never logs in.
</Note>

## Local quickstart

Windows PowerShell installs the CLI with:

```powershell theme={"languages":{"custom":["languages/helixql.json"]}}
irm https://raw.githubusercontent.com/HelixDB/helix-db/main/crates/cli/install.ps1 | iex
```

Use the [canonical local quickstart](/database/helix-db/start-here/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:

<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="..."   # raw key; bearer mode adds the prefix
    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. 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`.
  </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>