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

# Command Reference

> Complete reference for all Helix CLI v2 commands and options

This page provides a comprehensive reference for all commands available in Helix CLI v2.

## Global Options

These options are available for all commands:

```bash theme={null}
helix --help, -h      Show help information for the command
helix --version, -V   Display the CLI version
```

## Project Management

***

### `helix init`

Initialize a new Helix project with configuration and structure.

<ResponseField name="helix init [OPTIONS] [SUBCOMMAND]">
  <Expandable title="options">
    <ResponseField name="--path | -p [PATH]" type="String">
      The path to the project.
    </ResponseField>

    <ResponseField name="--template [TEMPLATE]" type="String">
      The template to use for the project.
    </ResponseField>

    <ResponseField name="--queries-path | -q [PATH]" type="String">
      The path to the query files.
    </ResponseField>
  </Expandable>

  <Expandable title="subcommands">
    <ResponseField name="helix init cloud" type="[Options]">
      <Expandable title="options">
        <ResponseField name="--region [REGION]" type="String">
          The region the instance is deployed to.
        </ResponseField>

        <ResponseField name="--name [NAME]" type="String">
          The name of the instance.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="helix init ecr" type="[Options]">
      <Expandable title="options">
        <ResponseField name="--name [NAME]" type="String">
          The name of the AWS ECR repository. Note this will create the repository if needed.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="helix init fly" type="[Options]">
      <Expandable title="options">
        <ResponseField name="--name [NAME]" type="String">
          The name of the Fly.io app.
        </ResponseField>

        <ResponseField name="--volume-size">
          The volume size in GB.
        </ResponseField>

        <ResponseField name="--vm-size [SIZE]" type="String">
          * `shared-cpu-1x` - 1 shared vCPU, 256MB RAM
          * `shared-cpu-2x` - 2 shared vCPUs, 512MB RAM
          * `shared-cpu-4x` - 4 shared vCPUs, 1GB RAM
          * `performance-4x` - 4 dedicated vCPUs, 8GB RAM
          * `performance-8x` - 8 dedicated vCPUs, 16GB RAM
        </ResponseField>

        <ResponseField name="--public">
          Make instance public.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="helix init local" type="[Options]">
      <Expandable title="options">
        <ResponseField name="--name [NAME]" type="String">
          The name of the local instance.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>

  Note that `helix init` with no arguments defaults to making a local instance called `dev`.
</ResponseField>

### `helix add`

Add a new instance to an existing Helix project.

<ResponseField name="helix add [SUBCOMMAND]">
  <Expandable title="subcommands">
    <ResponseField name="helix add cloud" type="[Options]">
      <Expandable title="options">
        <ResponseField name="--region [REGION]" type="String">
          The region the instance is deployed to.
        </ResponseField>

        <ResponseField name="--name [NAME]" type="String">
          The name of the instance.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="helix add ecr" type="[Options]">
      <Expandable title="options">
        <ResponseField name="--name [NAME]" type="String">
          The name of the AWS ECR repository. Note this will create the repository if needed.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="helix add fly" type="[Options]">
      <Expandable title="options">
        <ResponseField name="--name [NAME]" type="String">
          The name of the Fly.io app.
        </ResponseField>

        <ResponseField name="--volume-size">
          The volume size in GB.
        </ResponseField>

        <ResponseField name="--vm-size [SIZE]" type="String">
          * `shared-cpu-1x` - 1 shared vCPU, 256MB RAM
          * `shared-cpu-2x` - 2 shared vCPUs, 512MB RAM
          * `shared-cpu-4x` - 4 shared vCPUs, 1GB RAM
          * `performance-4x` - 4 dedicated vCPUs, 8GB RAM
          * `performance-8x` - 8 dedicated vCPUs, 16GB RAM
        </ResponseField>

        <ResponseField name="--public">
          Make instance public.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="helix add local" type="[Options]">
      <Expandable title="options">
        <ResponseField name="--name [NAME]" type="String">
          The name of the local instance.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

### `helix migrate`

Migrate a v1 Helix project to v2 format.

<ResponseField name="helix migrate [OPTIONS]">
  <Expandable title="options">
    <ResponseField name="--path | -p [PATH]" type="String">
      The path to the project to migrate.

      * Default: current directory
    </ResponseField>

    <ResponseField name="--queries-dir | -q [DIR]" type="String">
      The directory to move .hx files to.

      * Default: "./db/"
    </ResponseField>

    <ResponseField name="--instance-name | -i [NAME]" type="String">
      The name for the default local instance.

      * Default: "dev"
    </ResponseField>

    <ResponseField name="--port [PORT]" type="String">
      The port for the local instance.

      * Default: 6969
    </ResponseField>

    <ResponseField name="--dry-run">
      Show what would be migrated without making changes.
    </ResponseField>

    <ResponseField name="--no-backup">
      Skip creating backup of v1 files.
    </ResponseField>
  </Expandable>
</ResponseField>

## Validation & Compilation

### `helix check`

Validate project configuration and query syntax.

<ResponseField name="helix check [INSTANCE]">
  Name of the instance to check (defaults to all instances)
</ResponseField>

### `helix compile`

Compile project queries into executable format.

<ResponseField name="helix compile [OPTIONS]">
  <Expandable title="options">
    <ResponseField name="--path, -p [PATH]" type="String">
      The path to the project.
    </ResponseField>

    <ResponseField name="--output, -o [PATH]" type="String">
      The output path for compiled queries.
    </ResponseField>
  </Expandable>
</ResponseField>

### `helix build`

Build and prepare an instance for deployment.

<Note>
  **What it does:**

  1. Validates configuration and queries
  2. Compiles queries
  3. Generates Docker configuration files
  4. Prepares the instance workspace
</Note>

<ResponseField name="helix build [INSTANCE]">
  The instance to build.
</ResponseField>

## Deployment & Instance Management

### `helix push`

Deploy or update a running instance.

<Note>
  **What it does:**

  1. Builds the instance if needed
  2. Creates/updates Docker container for local instances
  3. Pushes to cloud provider for remote instances
  4. Starts the instance
</Note>

<ResponseField name="helix push [INSTANCE]">
  The instance to deploy.
</ResponseField>

### `helix pull`

<Info>
  🚧 COMING SOON 🚧
</Info>

***

### `helix start`

Start a stopped instance without rebuilding.

<ResponseField name="helix start [INSTANCE]">
  The instance to start.
</ResponseField>

### `helix stop`

Stop a running instance.

<ResponseField name="helix stop [INSTANCE]">
  The instance to stop.
</ResponseField>

### `helix status`

Show the status of all instances in the project.

## Backup & Maintenance

### `helix backup`

Create a backup of an instance's database files.

<Note>
  **What it does:**

  1. Creates an atomic snapshot of the LMDB database
  2. Copies `data.mdb` and `lock.mdb` to the backup directory
  3. Warns if backup size exceeds 10GB and prompts for confirmation
</Note>

<ResponseField name="helix backup [INSTANCE] [OPTIONS]">
  The instance to backup.

  <Expandable title="options">
    <ResponseField name="--output, -o [PATH]" type="String">
      Output directory for the backup. If omitted, creates `./backups/backup-<timestamp>/`.
    </ResponseField>
  </Expandable>
</ResponseField>

**Examples:**

```bash theme={null}
# Backup the 'dev' instance to default location
helix backup dev

# Backup to a specific directory
helix backup dev --output /path/to/backup
```

***

### `helix prune`

Remove unused containers, images, and workspace files.

<Note>
  **What it removes:**

  * Stopped containers
  * Unused Docker images
  * Workspace files
  * **Note:** Preserves data volumes
</Note>

<ResponseField name="helix prune [OPTIONS] [INSTANCE]">
  The instance to prune.

  <Expandable title="options">
    <ResponseField name="--all, -a" type="Boolean">
      Prune all instances in the project.
    </ResponseField>
  </Expandable>
</ResponseField>

### `helix delete`

Permanently delete an instance and all its data.

<Note>
  **What it removes:**

  * Container and images
  * All data volumes
  * Workspace files
  * Configuration entries
</Note>

<ResponseField name="helix delete [INSTANCE]">
  The instance to delete.
</ResponseField>

## Authentication & Cloud

### `helix auth`

Manage authentication for Helix Cloud.

<ResponseField name="helix auth [SUBCOMMAND]">
  The subcommand to run.

  <Expandable title="subcommands">
    <ResponseField name="login">
      Initiates browser-based authentication flow.
    </ResponseField>

    <ResponseField name="logout">
      Clears authentication tokens from `~/.helix/credentials`.
    </ResponseField>

    <ResponseField name="create-key">
      Generates a new API key for programmatic access.
    </ResponseField>
  </Expandable>
</ResponseField>

## Configuration & Settings

***

### `helix metrics`

Configure telemetry and usage metrics collection.

<ResponseField name="helix metrics [SUBCOMMAND]">
  The subcommand to run.

  <Expandable title="subcommands">
    <ResponseField name="full">
      Enable full metrics collection (requires email).
    </ResponseField>

    <ResponseField name="basic">
      Enable minimal anonymous metrics.
    </ResponseField>

    <ResponseField name="off">
      Disable all metrics collection.
    </ResponseField>

    <ResponseField name="status">
      Show current metrics configuration.
    </ResponseField>
  </Expandable>
</ResponseField>

### `helix update`

Update the Helix CLI to the latest version.

<ResponseField name="helix update [OPTIONS]">
  The options to run.

  <Expandable title="options">
    <ResponseField name="--force" type="Boolean">
      Force update even if already on latest version.
    </ResponseField>
  </Expandable>
</ResponseField>

## Logs

### `helix logs`

View logs for a running instance. Opens an interactive terminal UI by default, or use flags for non-interactive modes.

<Note>
  **Requirements:**

  * For local instances: Docker or Podman must be running
  * For cloud instances: Must be authenticated via `helix auth login`
</Note>

<ResponseField name="helix logs [INSTANCE] [OPTIONS]">
  The instance to view logs for. If omitted, an interactive selection prompt will appear.

  <Expandable title="options">
    <ResponseField name="--live, -l" type="Boolean">
      Stream live logs non-interactively to stdout. Useful for scripts and CI/CD pipelines. Press Ctrl+C to stop.
    </ResponseField>

    <ResponseField name="--range, -r" type="Boolean">
      Query historical logs within a time range. Requires `--start` and/or `--end`.
    </ResponseField>

    <ResponseField name="--start [DATETIME]" type="String">
      Start time for range query. Format: ISO 8601 (e.g., `2024-01-15T10:00:00Z`). Defaults to 15 minutes before end time.
    </ResponseField>

    <ResponseField name="--end [DATETIME]" type="String">
      End time for range query. Format: ISO 8601 (e.g., `2024-01-15T11:00:00Z`). Defaults to now.
    </ResponseField>
  </Expandable>
</ResponseField>

<Note>
  **Time Range Limits:**

  * Maximum range duration is 1 hour
  * Start time must be before end time
</Note>

#### Interactive TUI Mode

When run without flags, `helix logs` opens an interactive terminal UI with vim-style navigation:

**Navigation:**

| Key          | Action                 |
| ------------ | ---------------------- |
| `Down Arrow` | Scroll down one line   |
| `Up Arrow`   | Scroll up one line     |
| `j`          | Scroll down one page   |
| `k`          | Scroll up one page     |
| `zt`         | Jump to top of logs    |
| `zb`         | Jump to bottom of logs |

**Mode Switching:**

| Key   | Action                                                     |
| ----- | ---------------------------------------------------------- |
| `l`   | Switch to live streaming mode                              |
| `r`   | Switch to range mode (select time presets or custom range) |
| `Esc` | Quit                                                       |

**Range Mode Presets:**

* Last 15 minutes
* Last 30 minutes
* Last hour
* Custom range (date/time picker)

**Examples:**

```bash theme={null}
# Open interactive log viewer (will prompt for instance selection)
helix logs

# Open interactive log viewer for a specific instance
helix logs my-instance

# Stream live logs non-interactively
helix logs my-instance --live

# Query logs from a specific time range
helix logs my-instance --range --start 2024-01-15T10:00:00Z --end 2024-01-15T11:00:00Z

# Query last 15 minutes (end defaults to now)
helix logs my-instance --range --start 2024-01-15T10:45:00Z
```

***

## Dashboard

### `helix dashboard`

Launch the Helix Dashboard in a container to visualize and interact with your database.

<Note>
  **Requirements:**

  * Docker or Podman must be installed and running
  * `build_mode` must be set to `dev` in your `helix.toml` configuration
</Note>

<ResponseField name="helix dashboard [SUBCOMMAND]">
  The subcommand to run.

  <Expandable title="subcommands">
    <ResponseField name="start [INSTANCE] [OPTIONS]">
      Start the dashboard.

      <Expandable title="options">
        <ResponseField name="--port, -p [PORT]" type="Number">
          Port to run dashboard on. Default: 3000
        </ResponseField>

        <ResponseField name="--host [HOST]" type="String">
          Helix host to connect to (e.g., localhost). Bypasses project config.
        </ResponseField>

        <ResponseField name="--helix-port [PORT]" type="Number">
          Helix port to connect to. Used with --host. Default: 6969
        </ResponseField>

        <ResponseField name="--attach" type="Boolean">
          Run dashboard in foreground with logs.
        </ResponseField>

        <ResponseField name="--restart" type="Boolean">
          Restart if dashboard is already running.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="stop">
      Stop the running dashboard.
    </ResponseField>

    <ResponseField name="status">
      Show dashboard status and connection info.
    </ResponseField>
  </Expandable>
</ResponseField>

**Examples:**

```bash theme={null}
# Start dashboard for default instance
helix dashboard start

# Start dashboard on a specific port
helix dashboard start --port 8080

# Start dashboard for a specific instance
helix dashboard start my-instance

# Connect to a specific host directly
helix dashboard start --host localhost --helix-port 6969

# Check dashboard status
helix dashboard status

# Stop the dashboard
helix dashboard stop
```

For issues or questions:

* GitHub Issues: [https://github.com/HelixDB/helix-db/issues](https://github.com/HelixDB/helix-db/issues)
* Discord: [https://discord.gg/2stgMPr5BD](https://discord.gg/2stgMPr5BD)
* Email: [founders@helix-db.com](mailto:founders@helix-db.com)

## Next Steps

<CardGroup cols={2}>
  <Card title="Local Development" icon="computer" href="/documentation/cli-v2/workflows/local">
    Learn how to develop locally
  </Card>

  <Card title="Helix Cloud" icon="dna" href="/documentation/cli-v2/workflows/helix_cloud">
    Learn how to deploy to Helix Cloud
  </Card>

  <Card title="Fly.io" icon="fly" href="/documentation/cli-v2/workflows/fly">
    Learn how to deploy to Fly.io
  </Card>

  <Card title="AWS ECR" icon="aws" href="/documentation/cli-v2/workflows/ecr">
    Learn how to deploy to AWS ECR
  </Card>
</CardGroup>