HelixDB Docs

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

Global Options

These options are available for all commands:

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.

helix init [OPTIONS] [SUBCOMMAND]

Show options

--path | -p [PATH]

String

The path to the project.

--template [TEMPLATE]

String

The template to use for the project.

--queries-path | -q [PATH]

String

The path to the query files.

Show subcommands

helix init cloud

[Options]

Show options

--region [REGION]

String

The region the instance is deployed to.

--name [NAME]

String

The name of the instance.

helix init ecr

[Options]

Show options

--name [NAME]

String

The name of the AWS ECR repository. Note this will create the repository if needed.

helix init fly

[Options]

Show options

--name [NAME]

String

The name of the Fly.io app.

--volume-size

The volume size in GB.

--vm-size [SIZE]

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

--public

Make instance public.

helix init local

[Options]

Show options

--name [NAME]

String

The name of the local instance.

Note that helix init with no arguments defaults to making a local instance called dev.

`helix add`

Add a new instance to an existing Helix project.

helix add [SUBCOMMAND]

Show subcommands

helix add cloud

[Options]

Show options

--region [REGION]

String

The region the instance is deployed to.

--name [NAME]

String

The name of the instance.

helix add ecr

[Options]

Show options

--name [NAME]

String

The name of the AWS ECR repository. Note this will create the repository if needed.

helix add fly

[Options]

Show options

--name [NAME]

String

The name of the Fly.io app.

--volume-size

The volume size in GB.

--vm-size [SIZE]

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

--public

Make instance public.

helix add local

[Options]

Show options

--name [NAME]

String

The name of the local instance.

`helix migrate`

Migrate a v1 Helix project to v2 format.

helix migrate [OPTIONS]

Show options

--path | -p [PATH]

String

The path to the project to migrate.

Default: current directory

--queries-dir | -q [DIR]

String

The directory to move .hx files to.

Default: ”./db/”

--instance-name | -i [NAME]

String

The name for the default local instance.

Default: “dev”

--port [PORT]

String

The port for the local instance.

Default: 6969

--dry-run

Show what would be migrated without making changes.

--no-backup

Skip creating backup of v1 files.

Validation & Compilation

`helix check`

Validate project configuration and query syntax.

helix check [INSTANCE]

Name of the instance to check (defaults to all instances)

`helix compile`

Compile project queries into executable format.

helix compile [OPTIONS]

Show options

--path, -p [PATH]

String

The path to the project.

--output, -o [PATH]

String

The output path for compiled queries.

`helix build`

Build and prepare an instance for deployment.

What it does:

Validates configuration and queries
Compiles queries
Generates Docker configuration files
Prepares the instance workspace

helix build [INSTANCE]

The instance to build.

Deployment & Instance Management

`helix push`

Deploy or update a running instance.

What it does:

Builds the instance if needed
Creates/updates Docker container for local instances
Pushes to cloud provider for remote instances
Starts the instance

helix push [INSTANCE]

The instance to deploy.

`helix sync`

Sync .hx source files and helix.toml configuration from a deployed Helix Cloud instance back to your local project.

What it does:

Authenticates with Helix Cloud
Resolves your workspace and cluster (interactive prompts if needed)
Downloads .hx query files and helix.toml from the remote instance
Prompts before overwriting any local files that differ
Merges the remote helix.toml — updates [project] and the specific [cloud.<instance>] block while preserving [local.*] and other cloud entries

helix sync [INSTANCE] [OPTIONS]

Instance name to sync from. If omitted, an interactive selection prompt will appear.

Show options

--yes, -y

Boolean

Overwrite local files without confirmation prompts.

Requirements:

Only supported for Helix Cloud instances (standard and enterprise)
Requires authentication via helix auth login

Examples:

# Sync from a specific cloud instance
helix sync my-instance

# Interactive instance selection
helix sync

# Skip confirmation prompts
helix sync my-instance --yes

`helix start`

Start a stopped instance without rebuilding.

helix start [INSTANCE]

The instance to start.

`helix stop`

Stop a running instance.

helix stop [INSTANCE]

The instance to stop.

`helix status`

Show the status of all instances in the project.

Backup & Maintenance

`helix backup`

Create a backup of an instance’s database files.

What it does:

Creates an atomic snapshot of the LMDB database
Copies data.mdb and lock.mdb to the backup directory
Warns if backup size exceeds 10GB and prompts for confirmation

helix backup [INSTANCE] [OPTIONS]

The instance to backup.

Show options

--output, -o [PATH]

String

Output directory for the backup. If omitted, creates ./backups/backup-<timestamp>/.

Examples:

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

What it removes:

Stopped containers
Unused Docker images
Workspace files
Note: Preserves data volumes

helix prune [OPTIONS] [INSTANCE]

The instance to prune.

Show options

--all, -a

Boolean

Prune all instances in the project.

`helix delete`

Permanently delete an instance and all its data.

What it removes:

Container and images
All data volumes
Workspace files
Configuration entries

helix delete [INSTANCE]

The instance to delete.

Authentication & Cloud

`helix auth`

Manage authentication for Helix Cloud.

helix auth [SUBCOMMAND]

The subcommand to run.

Show subcommands

Initiates browser-based authentication flow.

logout

Clears authentication tokens from ~/.helix/credentials.

create-key

Generates a new API key for programmatic access.

Configuration & Settings

`helix metrics`

Configure telemetry and usage metrics collection.

helix metrics [SUBCOMMAND]

The subcommand to run.

Show subcommands

full

Enable full metrics collection (requires email).

basic

Enable minimal anonymous metrics.

off

Disable all metrics collection.

status

Show current metrics configuration.

`helix update`

Update the Helix CLI to the latest version.

helix update [OPTIONS]

The options to run.

Show options

--force

Boolean

Force update even if already on latest version.

Logs

`helix logs`

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

Requirements:

For local instances: Docker or Podman must be running
For cloud instances: Must be authenticated via helix auth login

helix logs [INSTANCE] [OPTIONS]

The instance to view logs for. If omitted, an interactive selection prompt will appear.

Show options

--live, -l

Boolean

Stream live logs non-interactively to stdout. Useful for scripts and CI/CD pipelines. Press Ctrl+C to stop.

--range, -r

Boolean

Query historical logs within a time range. Requires --start and/or --end.

--start [DATETIME]

String

Start time for range query. Format: ISO 8601 (e.g., 2024-01-15T10:00:00Z). Defaults to 15 minutes before end time.

--end [DATETIME]

String

End time for range query. Format: ISO 8601 (e.g., 2024-01-15T11:00:00Z). Defaults to now.

Time Range Limits:

Maximum range duration is 1 hour
Start time must be before end time

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:

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

Requirements:

Docker or Podman must be installed and running
build_mode must be set to dev in your helix.toml configuration

helix dashboard [SUBCOMMAND]

The subcommand to run.

Show subcommands

start [INSTANCE] [OPTIONS]

Start the dashboard.

Show options

--port, -p [PORT]

Number

Port to run dashboard on. Default: 3000

--host [HOST]

String

Helix host to connect to (e.g., localhost). Bypasses project config.

--helix-port [PORT]

Number

Helix port to connect to. Used with —host. Default: 6969

--attach

Boolean

Run dashboard in foreground with logs.

--restart

Boolean

Restart if dashboard is already running.

stop

Stop the running dashboard.

status

Show dashboard status and connection info.

Examples:

# 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
Discord: https://discord.gg/2stgMPr5BD
Email: founders@helix-db.com

Next Steps

Local Development

Learn how to develop locally

Helix Cloud

Learn how to deploy to Helix Cloud

Fly.io

Learn how to deploy to Fly.io

AWS ECR

Learn how to deploy to AWS ECR

Getting Started

CLI

SDKs

Other Features

Command Reference

Global Options

Project Management

`helix init`

`helix add`

`helix migrate`

Validation & Compilation

`helix check`

`helix compile`

`helix build`

Deployment & Instance Management

`helix push`

`helix sync`

`helix start`

`helix stop`

`helix status`

Backup & Maintenance

`helix backup`

`helix prune`

`helix delete`

Authentication & Cloud

`helix auth`

Configuration & Settings

`helix metrics`

`helix update`

Logs

`helix logs`

Interactive TUI Mode

Dashboard

`helix dashboard`

Next Steps

Local Development

Helix Cloud

Fly.io

AWS ECR

Getting Started

CLI

SDKs

Other Features

​Global Options

​Project Management

​helix init

​helix add

​helix migrate

​Validation & Compilation

​helix check

​helix compile

​helix build

​Deployment & Instance Management

​helix push

​helix sync

​helix start

​helix stop

​helix status

​Backup & Maintenance

​helix backup

​helix prune

​helix delete

​Authentication & Cloud

​helix auth

​Configuration & Settings

​helix metrics

​helix update

​Logs

​helix logs

​Interactive TUI Mode

​Dashboard

​helix dashboard

​Next Steps

Local Development

Helix Cloud

Fly.io

AWS ECR

Global Options

Project Management

`helix init`

`helix add`

`helix migrate`

Validation & Compilation

`helix check`

`helix compile`

`helix build`

Deployment & Instance Management

`helix push`

`helix sync`

`helix start`

`helix stop`

`helix status`

Backup & Maintenance

`helix backup`

`helix prune`

`helix delete`

Authentication & Cloud

`helix auth`

Configuration & Settings

`helix metrics`

`helix update`

Logs

`helix logs`

Interactive TUI Mode

Dashboard

`helix dashboard`

Next Steps