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:

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:

1. Validates configuration and queries
2. Compiles queries
3. Generates Docker configuration files
4. 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:

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

helix push [INSTANCE]

The instance to deploy.

helix pull

🚧 COMING SOON 🚧

---

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:

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

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

login

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: [e-mail]

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