This guide walks through common workflows and best practices for developing with Helix CLI v2.

​
Local Development Workflow

​
Initial Setup

1

Create project

mkdir my-app && cd my-app
helix init
Note that helix init with no arguments defaults to making a local instance called dev.
2

Define schema

Edit db/schema.hx:
N::User {
  name: String,
  INDEX email: String,
  created_at: Date DEFAULT NOW
}

N::Post {
  title: String,
  content: String,
  published: Boolean DEFAULT true,
  created_at: Date DEFAULT NOW
}
3

Create queries

Edit db/queries.hx:
QUERY createUser(name: String, email: String) =>
  user <- AddN<User({
    name: name,
    email: email,
  })
  RETURN user

QUERY getUserByEmail(email: String) =>
  user <- N<User>({email: email})
  RETURN user
4

Validate

helix check
5

Build and deploy

helix push dev
6

Test connection

curl http://localhost:6969/health

​
Development Iteration

When making changes during development: 
# Edit your .hx files
vim db/queries.hx

# Validate changes
helix check

# Deploy changes (rebuilds automatically if needed)
helix push dev

# Check status
helix status

# View logs
docker logs helix_my-app_dev

# Stop when done
helix stop dev

​
Working with Multiple Instances

Create different instances for different purposes: 
# Add a testing instance
helix add local --name testing

# Configure different port in helix.toml
# [local.testing]
# port = 7070

# Run both instances
helix push dev
helix push testing

# Status shows all instances
helix status

​
Multi-Environment Setup

​
Development → Staging → Production

# Initialize with local dev
helix init

# Add staging environment
helix add cloud --name staging --region us-east-1

# Add production environment
helix add cloud --name production --region us-east-1

​
Cloud Deployment Workflows

​
Helix Cloud Deployment

1

Authenticate

helix auth login
2

Initialize cloud instance

helix init cloud --region us-east-1 --name production
3

Configure production settings

Edit helix.toml:
[cloud.production]
type = "helix"
region = "us-east-1"
build_mode = "release"
mcp = true
bm25 = true

[cloud.production.vector_config]
m = 32
ef_construction = 256
ef_search = 1024
4

Deploy

helix build production
helix push production
5

Monitor

helix status

​
Fly.io Deployment

Prerequisites: Install and authenticate flyctl 
# Install flyctl
curl -L https://fly.io/install.sh | sh

# Authenticate
fly auth login
Deploy to Fly.io:
1

Add Fly.io instance

helix add fly \
  --name production \
  --vm-size performance-4x \
  --volume-size 20 \
  --public false
2

Build and deploy

helix build production
helix push production
3

Check deployment

fly status -a my-app-production
fly logs -a my-app-production
4

Scale if needed

fly scale vm performance-8x -a my-app-production
fly scale count 3 -a my-app-production

​
AWS ECR Deployment

Prerequisites: Configure AWS CLI 
# Configure AWS credentials
aws configure
Deploy to ECR:
1

Add ECR instance

helix add ecr --name staging
2

Build image

helix build staging
3

Push to ECR

helix push staging
This will:
  • Create ECR repository if needed
  • Authenticate Docker with ECR
  • Tag and push the image
4

Deploy to ECS/EKS

Use the pushed image in your container orchestration:
# ECS task definition
image: 123456789.dkr.ecr.us-west-2.amazonaws.com/my-app:latest

​
Best Practices

  • Always run helix check before deploying
  • Use descriptive instance names
  • Keep development and production configurations separate
  • Regularly clean up unused resources with helix prune
  • Version control your helix.toml file
  • Use build_mode = "release" for production
  • Configure appropriate vector parameters for your data scale
  • Enable monitoring and logging
  • Set up automated backups
  • Test migrations in staging first
  • Never commit credentials to version control
  • Use environment variables for sensitive data
  • Regularly rotate API keys
  • Keep CLI updated with helix update
  • Use private instances for production data

​
Next Steps

Troubleshooting

Solutions to common issues

Configuration Guide

Advanced configuration options