Helios CLI

Command-line interface for scaffolding, rendering, and deploying Helios projects

The Helios CLI provides commands for initializing projects, rendering compositions, managing components, and deploying to cloud platforms.

Installation

npm install -g @helios-project/cli

Or use with npx without installation:

npx helios <command>

Commands

init

Initialize a new Helios project configuration.

helios init [target]

Options:

• -y, --yes - Skip prompts and use defaults (React)
• -f, --framework <framework> - Specify framework (react, vue, svelte, solid, vanilla)
• --example <name> - Initialize from an example
• --repo <repo> - Example repository (default: BintzGavin/helios/examples)

Examples:

# Interactive mode
helios init my-project

# Use React with defaults
helios init my-project -y

# Specify framework
helios init my-project --framework vue

# Initialize from example
helios init my-project --example basic-react

See /home/daytona/workspace/source/packages/cli/src/commands/init.ts:1

studio

Start the development server with Studio UI.

helios studio

Launches the Studio interface at http://localhost:5173 for the current directory.

render

Render a composition to video.

helios render <input> [options]

Options:

• -o, --output <path> - Output file path (default: output.mp4)
• --width <number> - Viewport width (default: 1920)
• --height <number> - Viewport height (default: 1080)
• --fps <number> - Frames per second (default: 30)
• --duration <number> - Duration in seconds (default: 1)
• --quality <number> - CRF quality (0-51)
• --mode <mode> - Render mode: canvas or dom (default: canvas)
• --start-frame <number> - Frame to start rendering from
• --frame-count <number> - Number of frames to render
• --concurrency <number> - Concurrent render jobs (default: 1)
• --no-headless - Run in visible browser window
• --emit-job <path> - Generate distributed render job spec (JSON)
• --base-url <url> - Base URL for remote asset resolution
• --audio-codec <codec> - Audio codec (e.g., aac, pcm_s16le)
• --video-codec <codec> - Video codec (e.g., libx264, libvpx)

Examples:

# Basic render
helios render composition.html -o output.mp4

# Custom resolution and FPS
helios render composition.html --width 3840 --height 2160 --fps 60

# Render specific frame range
helios render composition.html --start-frame 100 --frame-count 300

# Generate distributed render job
helios render composition.html --emit-job job.json --base-url https://cdn.example.com

# Render with visible browser (debug mode)
helios render composition.html --no-headless

# High quality render
helios render composition.html --quality 18 --video-codec libx264

See /home/daytona/workspace/source/packages/cli/src/commands/render.ts:1

build

Build the project for production.

helios build [dir]

Options:

• -o, --out-dir <dir> - Output directory (default: dist)

Example:

helios build --out-dir build

This creates a production build with composition.html and a player interface ready for deployment.

See /home/daytona/workspace/source/packages/cli/src/commands/build.ts:1

preview

Preview the production build.

helios preview

Serves the static build output using Vite preview mode.

add

Add a component from the registry to your project.

helios add <component>

Options:

• --no-install - Skip dependency installation

Example:

helios add button

Components are copied into your repository (Shadcn-style) and become part of your codebase.

See /home/daytona/workspace/source/packages/cli/src/commands/add.ts:1

components

List and search available components in the registry.

helios components [query]

Options:

• -f, --framework <name> - Filter by framework (react, vue, svelte, solid, vanilla)
• -a, --all - Show all components (ignore project framework)

Examples:

# List all components for your framework
helios components

# Search for specific components
helios components button

# List all React components
helios components --framework react

# Show all components regardless of framework
helios components --all

See /home/daytona/workspace/source/packages/cli/src/commands/components.ts:1

diff

Compare local component against registry version.

helios diff <component-name>

Highlights modifications you’ve made to a component after adding it from the registry.

remove

Remove a component from your project.

helios remove <component>

Also aliased as helios rm.

update

Update a component to the latest registry version.

helios update <component>

Merges the latest version from the registry with your local changes.

merge

Merge rendered video chunks into a final output.

helios merge <output> <chunk1> [chunk2...]

Options:

• --video-codec <codec> - Video codec for output
• --audio-codec <codec> - Audio codec for output
• --quality <number> - CRF quality

Example:

helios merge final.mp4 chunk-0.mp4 chunk-1.mp4 chunk-2.mp4

Used for distributed rendering workflows.

job

Execute a render job from a job spec.

helios job <job-file.json>

Options:

• --chunk <id> - Execute a specific chunk
• --merge-only - Only run the merge step

Examples:

# Run entire job locally
helios job render-job.json

# Execute specific chunk (for distributed workers)
helios job render-job.json --chunk 0

# Merge pre-rendered chunks
helios job render-job.json --merge-only

deploy

Manage deployment configuration.

deploy setup

Scaffold Docker configuration files.

helios deploy setup

Creates Dockerfile and docker-compose.yml for containerized deployment.

deploy gcp

Scaffold Google Cloud Run Job configuration.

helios deploy gcp

Creates cloud-run-job.yaml and README-GCP.md for GCP deployment.

deploy aws

Scaffold AWS Lambda deployment configuration.

helios deploy aws

Creates Dockerfile, template.yaml, lambda.js, and README-AWS.md for AWS Lambda deployment.

See /home/daytona/workspace/source/packages/cli/src/commands/deploy.ts:1

list

List installed components in the current project.

helios list

Also aliased as helios ls.

skills

Manage AI skills for the Studio assistant.

helios skills

Lists available skills for the Model Context Protocol (MCP) integration.

Environment variables

HELIOS_BROWSER_ARGS

Custom browser arguments for rendering:

HELIOS_BROWSER_ARGS="--disable-gpu --no-sandbox" helios render composition.html

PUPPETEER_EXECUTABLE_PATH

Custom browser executable path:

PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium helios render composition.html

Configuration file

The helios.config.json file stores project configuration:

{
  "framework": "react",
  "registry": "https://registry.helios.video",
  "directories": {
    "components": "src/components",
    "lib": "src/lib"
  }
}

Generated automatically by helios init.

Distributed rendering

The CLI supports distributed rendering through job specs:

1. Generate job spec:

helios render composition.html \
  --emit-job job.json \
  --base-url https://cdn.example.com \
  --concurrency 4

2. Execute chunks on workers:

# Worker 1
helios job job.json --chunk 0

# Worker 2
helios job job.json --chunk 1

3. Merge results:

helios job job.json --merge-only

See the distributed rendering guide for details.