Documentation Index
Fetch the complete documentation index at: /llms.txt
Use this file to discover all available pages before exploring further.
Skip to main content
Without a subcommand, the CLI prompts for the target in a terminal and creates a local
CLI Command Reference
helix init
Create a local project or a WorkOS-authenticated Cloud link
Reference
Create a new Helix project: helix init writes a helix.toml with either one local instance or one
Helix Cloud database link. Local or Cloud.
Usage
helix init local [--name dev] [--port 6969] [--disk | --storage-uri s3://bucket/prefix]
helix init cloud [--name production] [--database <database>] \
[--project <project>] [--workspace <workspace>]
Subcommands
| Subcommand | Description |
|---|---|
local | Create a project with a local instance. |
cloud | Create a project linked to a Helix Cloud database. Alias: enterprise. |
dev
instance in non-interactive shells.
Options
| Flag | Description | Default |
|---|---|---|
-p, --path <DIR> | Project directory. Created if missing. | Prompted in a terminal; otherwise the current directory |
--skills | Install the Helix agent skills and docs MCP without prompting. | Prompted in a terminal; skipped otherwise |
--no-skills | Skip installing the Helix agent skills and docs MCP. | — |
--json | Print the result as JSON on stdout and never prompt. | Off |
--path, --skills, and --no-skills can be passed before or after the subcommand.
helix init local
| Flag | Description | Default |
|---|---|---|
-n, --name <NAME> | Local instance name. | dev |
--port <PORT> | Host port for the instance. | 6969 |
--disk | Use on-disk storage backed by a CLI-managed SeaweedFS container. Cannot be combined with --storage-uri. | Off (in-memory) |
--storage-uri <URI> | Use an S3 or S3-compatible bucket and prefix, for example s3://bucket/prefix/. | — |
--s3-region <REGION> | Region for S3 storage. Requires --storage-uri. | — |
--s3-endpoint-url <URL> | Custom S3-compatible endpoint URL. Requires --storage-uri. | — |
--s3-allow-http | Allow plain HTTP for the S3 endpoint. Requires --storage-uri. | Off |
helix init cloud
| Flag | Description | Default |
|---|---|---|
-n, --name <NAME> | Cloud instance name. | production |
--database <DATABASE> | Database ID, slug, or name, or tenant:<id> / cluster:<id>. | The project’s only database, then a picker |
--project <PROJECT> | Owning project ID, slug, or name. Not needed with a tenant:<id> / cluster:<id> database, which must belong to it when both are given. | The workspace’s only project, then a picker |
--workspace <WORKSPACE> | Workspace ID, slug, or name to find the project in. | Your only workspace, then a picker |
Behavior
- Fails if
helix.tomlalready exists in the project directory. - Creates
.helix/for instance state and adds.helix/,.env,target/, and*.logto.gitignorewhen missing. init localalso writesexamples/request.jsonand anAGENTS.md(never overwriting an existing one), and warns if Docker or Podman is unavailable.- Cloud init authenticates through the WorkOS session and resolves workspace, then project, then database as described in Cloud resource resolution. It ignores the link of any enclosing project.
- Cloud init writes
[project] idandworkspace_idalong with the[enterprise.<name>]link, so later Cloud commands in the directory need no flags. - It stores stable linkage only. It has no gateway URL (database endpoint) or query-auth options.
- The skills install runs through
npx; if it fails, the project is still created and the CLI prints a warning.
Examples
# Local project with a 'dev' instance on port 6969
helix init local
# Local project with persistent on-disk storage, in a new directory
helix init local --disk --path my-app
# Pick a Cloud workspace, project, and database interactively
helix init cloud
# Link a specific Cloud database, skipping the skills install
helix init cloud --database tenant:<id> --no-skills
Related
helix add— add more instances later.helix start— start the local instance.helix chef— initialize and hand off to a coding agent.- CLI configuration — the
helix.tomlformat.
Was this page helpful?
Assistant
Responses are generated using AI and may contain mistakes.