HelixDB Docs

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`.

Without a subcommand, the CLI prompts for the target in a terminal and creates a local 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.toml already exists in the project directory.
Creates .helix/ for instance state and adds .helix/, .env, target/, and *.log to .gitignore when missing.
init local also writes examples/request.json and an AGENTS.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] id and workspace_id along 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

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.toml format.

Using the helix CLI

CLI Command Reference

helix init

Usage

Subcommands

Options

`helix init local`

`helix init cloud`

Behavior

Examples

​Usage

​Subcommands

​Options

​helix init local

​helix init cloud

​Behavior

​Examples

​Related

Usage

Subcommands

Options

`helix init local`

`helix init cloud`

Behavior

Examples

Related