Ecosystem

CLI

Generate projects, manage template metadata, configure the local Helix environment, and diagnose setup issues from the command line.

Overview

The helix CLI is the command-line entry point for template-driven project creation and local Helix setup. The current command surface includes:

init - shorthand for template init <template> <projectName>
template - template discovery, initialization, cache management, validation, and lock-file workflows
config - local configuration management
mcp - installation and lifecycle management for the Helix MCP server
project - inspect local Helix project metadata and Gradle wiring
doctor - global environment diagnostics
completion - shell completion script generation

One important first-run behavior is built into the CLI: if you invoke a normal working command without an existing config file, Helix automatically runs helix config init first. Help/version output, config, project, and completion are exempt from that bootstrap flow.

Install and Run

Install instructions live on the Installation page, but the two main entry points are:

brew tap helixframework/helix
brew install helix-cli

curl -fsSL https://raw.githubusercontent.com/helixframework/helix/main/helix-cli/install.sh | bash

Configuration Directory

The CLI stores local state in ~/.helix by default:

~/.helix/helix.properties - persisted CLI configuration
~/.helix/cache/template-index.json - cached template index
~/.helix/cache/templates/ - cached template archives

Use --config-dir to isolate state for local testing or CI:

helix --config-dir /tmp/helix-docs-demo config path

Global Options

These options are inherited by subcommands:

Option	Purpose
`--config-dir <path>`	Use a custom Helix config directory instead of `~/.helix`.
`--offline`	Use only local config and cache data. Network checks and downloads are skipped or fail fast.
`--debug`	Enable debug mode. Helpful for cache and download failures.
`--stacktrace`	Print stack traces on failures.
`--color <AUTO\|ALWAYS\|NEVER>`	Control ANSI color behavior explicitly.
`--no-color`	Shortcut for `--color=NEVER`.
`-h`, `--help`	Show command help.
`-V`, `--version`	Show CLI version.

Common discovery commands:

helix --help
helix template --help
helix config --help
helix mcp --help
helix project --help
helix doctor --help

Project Generation

The fastest way to create a project is the top-level alias:

helix init springboot my-service

That is equivalent to:

helix template init springboot my-service

template init does more than unzip a template:

refreshes or reuses the template index
resolves the requested template version
downloads the archive if needed
unpacks into <working-dir>/<projectName>
prompts for template replacement values when the template declares them
sets the Gradle rootProject.name
runs template initialization hooks
writes a template lock file into the generated project

Important safeguards:

the target path cannot already exist as a file
if the target directory already exists, it must be empty
unknown templates and unavailable versions fail with a clear error

Useful generation flags:

Option	Purpose
`--version <version>`	Use a specific published template version instead of the template's latest version.
`--no-cache`	Force refreshes instead of reusing cached index and archive data.
`--dry-run`	Resolve the template and show planned actions without writing files.

Example:

helix template init springboot payments-api --version 1.2.0 --dry-run

Template Commands

The template command group is the heart of the CLI.

Discover Templates

helix template list
helix template search spring
helix template info springboot
helix template versions springboot

What each command does:

template list prints every template plus its published versions, marking versions as local or remote and tagging the latest version
template search <query> matches against template names and descriptions
template info <name> shows the template description, group, artifact, packaging, and either all versions or one selected version
template versions <name> prints the available versions and whether each archive is already cached locally

Most read-oriented template commands support --no-cache to force an index refresh before reading.

Lock File Workflows

Helix writes template lock metadata so generated projects can remember where they came from.

helix template lock
helix template lock springboot --version 1.2.0 --project-dir ./my-service
helix template lock --json

Behavior:

with no template name, template lock reads the existing lock from the current project
if the lock file is missing, Helix tries to infer the template from .helix/template.yml
with a template name, Helix writes a new lock file
--force overwrites an existing lock
--json prints machine-readable lock metadata

Validate and Diagnose Template Metadata

helix template validate
helix template doctor

template validate checks template index structure and reports duplicate names, missing fields, or mismatched latest versions
template doctor reports config values, cache locations, cached index metadata, and template-registry network reachability

Manage the Template Cache

helix template cache list
helix template cache warm
helix template cache warm --all-versions
helix template cache clean
helix template cache clean --template springboot
helix template cache clean --template springboot --version 1.2.0
helix template cache clean --all

Cache behavior:

cache list shows the index cache file and any cached template archives
cache warm pre-downloads template archives for offline use
cache warm --all-versions downloads every published version instead of only latest versions
cache clean removes cached template data, either broadly or with template/version targeting

cache warm refuses to run in offline mode, because it needs network access to download archives.

Config Commands

Configuration is stored in helix.properties. Helix ships with built-in defaults and lets you override them locally.

helix config init
helix config list
helix config get helix.template.org.name
helix config set helix.template.org.name acme
helix config unset helix.template.org.name
helix config reset helix.template.org.name
helix config reset --all
helix config path
helix config edit
helix config doctor

Key behaviors:

config init is interactive and sets up organization, team, proxy, and Gradle-init-script preferences
config list prints all effective config keys
config get, set, and unset read and mutate individual keys
config reset restores a single key or the whole file back to defaults
config path prints the full path to helix.properties
config edit opens the config file in $VISUAL, then $EDITOR, and finally vi
config doctor validates the config and can emit JSON with --json

Common keys:

Key	Description
`helix.template.org.name`	Template registry organization or account segment. Defaults to `helixframework`.
`helix.template.team.name`	Template registry team or repository owner segment. Defaults to `helix`.
`helix.cli.template.snapshotCacheTtlMinutes`	Snapshot template cache TTL. Defaults to `60`.
`http.proxy.enabled`	Enables proxy-aware HTTP behavior. Defaults to `false`.
`http.proxy.host`	Proxy host value. Defaults to empty and is required when proxy support is enabled.
`http.proxy.port`	Proxy port value. Defaults to empty and is required when proxy support is enabled.
`helix.cli.colorMode`	Runtime color mode override. Unset unless you explicitly configure or pass it.
`helix.cli.offline`	Persisted offline-mode preference. Unset unless you explicitly configure or pass it.
`helix.cli.debug`	Persisted debug preference. Unset unless you explicitly configure or pass it.
`helix.cli.stacktrace`	Persisted stacktrace preference. Unset unless you explicitly configure or pass it.

MCP Commands

The mcp command group manages the Helix MCP server used by coding agents and other MCP-compatible clients.

Install and Configure

The lowest-level setup flow is:

helix mcp install
helix mcp config --format claude

For common agent clients, use the guided setup commands:

helix mcp setup codex
helix mcp setup claude

What this does:

mcp install downloads the published helix-agent-mcp distribution from Maven Central
the CLI stores versioned MCP installs under the Helix config directory
the CLI maintains a stable executable path at ~/.helix/tools/helix-agent-mcp/current/bin/helix-agent-mcp
mcp config prints a ready-to-copy MCP client configuration snippet that points at the stable path
mcp setup codex and mcp setup claude install or reuse the active version, print the stable executable path, and emit the correct client snippet for that target tool

That stable path is what you should configure in tools such as Codex or Claude. When you later update or switch versions, the client config can stay the same.

Version and Lifecycle Management

helix mcp list
helix mcp versions
helix mcp use <version>
helix mcp update
helix mcp uninstall
helix mcp uninstall --all

What each command does:

mcp list shows locally installed helix-agent-mcp versions and marks the active one
mcp versions lists published versions available from Maven Central
mcp use <version> switches the active installation to an already installed version
mcp update installs and activates the latest published version
mcp uninstall removes the current installation
mcp uninstall --all removes all installed versions and the launcher

Inspect and Run

helix mcp path
helix mcp doctor
helix mcp run --help

These commands help you inspect the active installation:

mcp path prints the current version plus install, executable, and stable-path locations
mcp doctor validates the launcher, executable, active version, and Java availability
mcp run launches the installed helix-agent-mcp executable and passes through additional arguments

Important notes:

mcp install, mcp update, and mcp versions require network access and fail in --offline mode
mcp install --version <version> installs a specific release instead of the latest one
mcp install --install-dir <path> and mcp install --bin-dir <path> override the default install locations
mcp config --format <format> prints the client snippet in the requested format

Project Commands

The project command group inspects an existing local project and reports the Helix-specific metadata Helix can infer from its files.

Inspect the Current Project

helix project info
helix project info --project-dir ./my-service
helix project info --project-dir ~/workspace/ironhive

Available flags:

Option	Purpose
`--project-dir <path>`	Inspect a project at the given path instead of the current working directory.
`-h`, `--help`	Show command help.
`-V`, `--version`	Show CLI version.

What project info inspects:

project root markers such as settings.gradle, .helix/template.lock.json, and .helix/template.yml
template metadata from the Helix lock file or template YAML
Gradle settings for rootProject.name and included modules
build files for Helix plugins and Helix dependencies
version-catalog presence at gradle/libs.versions.toml

Output includes:

resolved project directory
root project name
detected project type
template name, version, artifact, and source when available
settings file path and version-catalog presence
discovered modules
Helix plugins
Helix dependencies

Path handling notes:

with no --project-dir, Helix inspects the current working directory
--project-dir accepts absolute or relative paths
~ and ~/... are expanded to the current user’s home directory before inspection
relative paths are resolved from the CLI working directory

Exit behavior:

returns 0 for recognized Helix projects
returns non-zero for non-Helix projects, while still printing the detected metadata

Diagnostics

Use the global doctor command when the CLI itself is not behaving the way you expect:

helix doctor
helix doctor --json

Available flags:

Option	Purpose
`--json`	Emit machine-readable diagnostic output.
`-h`, `--help`	Show command help.
`-V`, `--version`	Show CLI version.

doctor reports:

CLI version, Java version, and OS details
effective runtime flags such as offline/debug/stacktrace/color mode
config file location and whether it exists
template org/team values
cached template index and archive state
network connectivity to the published template index and Maven metadata

Shell Completion

The current implementation generates native output for Bash and Fish, and the Zsh script bootstraps Bash completion compatibility for the same command tree.

helix completion bash
helix completion zsh
helix completion fish

Examples

Bootstrap a service from the latest published template:

helix init springboot billing-service

Preview generation without writing files:

helix template init springboot billing-service --dry-run

Inspect a template before generating:

helix template info springboot
helix template versions springboot

Prepare a laptop for travel or offline work:

helix template cache warm
helix --offline template list

Point the CLI at a custom config location in CI or a test harness:

helix --config-dir /tmp/helix-ci config set helix.template.org.name acme
helix --config-dir /tmp/helix-ci config doctor

Install the MCP server and print a client config snippet:

helix mcp setup claude

Inspect an existing project without changing directories:

helix project info --project-dir ~/workspace/ironhive

Search documentation

CLI

Overview

Install and Run

Install the CLI with Homebrew

Install the CLI with the install script

Configuration Directory

Print the config path from an isolated config directory

Global Options

Project Generation

Create a project with the init alias

Create a project with the full template command

Template Commands

Discover Templates

Lock File Workflows

Validate and Diagnose Template Metadata

Manage the Template Cache

Config Commands

MCP Commands

Install and Configure

Version and Lifecycle Management

Inspect and Run

Project Commands

Inspect the Current Project

Diagnostics

Shell Completion

Examples

Bootstrap a service from the latest template

Preview project generation without writing files

Inspect a template before generating

Prepare for travel or offline work

Use an isolated config directory in CI

Install and configure the Helix MCP server

Inspect a Helix project from another path