> ## Documentation Index
> Fetch the complete documentation index at: https://helix-isolate-failing-index-entities.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# helix init

> Create a local project or a WorkOS-authenticated Cloud link

<div className="flex flex-wrap gap-2"><Badge color="gray" size="sm">Reference</Badge></div>

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

```bash theme={null}
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](/cli/command-reference#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

```bash theme={null}
# 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`](/cli/command-reference/add) — add more instances later.
* [`helix start`](/cli/command-reference/start) — start the local instance.
* [`helix chef`](/cli/command-reference/chef) — initialize and hand off to a coding agent.
* [CLI configuration](/cli/configuration) — the `helix.toml` format.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.