Skip to content

helix create

Scaffold a new Helix project: full directory layout, prompt templates, example agent/tool/pipeline YAML files, Starlang scripts, an HTML template, env configs, a .gitignore, and a README. The result is a runnable starting point — cd <name> && helix validate app.yaml works on the freshly created tree.

helix init is an alias for this command; both dispatch to the same cmdCreate function.

Usage

helix create [name]
helix init   [name]

If name is omitted, the project is created as my-helix-app. The target directory must not already exist.

Flags

This subcommand takes no flags. The single optional positional argument is the project name (used as the directory name).

What gets created

<name>/
├── app.yaml              # runnable entry point (chat-agent + MCP server)
├── README.md
├── .gitignore
├── agents/               # chat-agent.yaml, rag-agent.yaml
├── tools/                # search-kb.yaml
├── pipelines/            # doc-search.yaml, pdf-ingest.yaml
├── workflows/            # ws-echo.yaml
├── mcps/                 # public.yaml (MCP server config)
├── prompts/
│   ├── base/             # helpful, expert, concise
│   ├── roles/            # developer, analyst, support, researcher
│   ├── rag/              # retrieval, summarize, qa
│   └── safety/           # boundaries, hallucination, pii
├── scripts/              # uppercase.sl, json-to-csv.sl, normalize.sl
│   └── _lib/             # shared helpers (.gitkeep + README)
├── templates/            # report.html + README
├── config/               # dev.env, prod.env
├── data/docs/            # documents for RAG ingestion
└── tests/                # declarative tests

app.yaml references the first agent via ${file:prompts/...} includes and exposes it through an MCP server.

Behavior notes

  • Requires $HELIX_LICENSE. Verified at process start.
  • Fails immediately with directory %q already exists if the target path is already taken — create never overwrites.
  • All files are written with mode 0644; directories with mode 0755.
  • The MCP config interpolates ${MCP_API_KEY:-dev-key-change-in-prod} so the project is runnable out of the box, with a clear marker to change before deploy.
  • Prints a colorised summary of the layout and a "Get started" block with the next three commands (cd, export OPENAI_API_KEY=..., helix start app.yaml).

Examples

Create the default project:

helix create
cd my-helix-app
export OPENAI_API_KEY=...
helix validate app.yaml
helix start app.yaml

Pick a name:

helix init customer-support-bot

Source

cmd/helix/main.go lines 1653-2285 (cmdCreate).

See also