> ## Documentation Index
> Fetch the complete documentation index at: https://docs.substrate.42.pe/llms.txt
> Use this file to discover all available pages before exploring further.

# substrate init — Initialize a New Substrate Project

> substrate init creates a .substrate/ directory in the current project, optionally seeded from the web-delivery starter or a local template.

Run `substrate init` once per project to create the `.substrate/` directory that all other commands operate on. It refuses if a `.substrate/` already exists in the current directory. If anything fails after the directory is created, `init` rolls back the partial `.substrate/` so you can retry cleanly.

## Usage

```shell theme={null}
substrate init
substrate init --template <name-or-path>
```

## Options

<ParamField path="--template" type="string">
  Seed with a starter board. Accepts either the bundled template name `web-delivery`, or a local directory holding a published workflow. Resolution order: a bundled name resolves bundled; otherwise an existing path is resolved by the network-free external loader. A template that resolves to neither fails **before** `.substrate/` is created.
</ParamField>

## What It Writes

`init` creates the following structure in your current directory:

```text theme={null}
.substrate/
├── config.json        project id (uuid), name, description, schema version
├── boards/            template boards, or empty for a bare init
├── members/           default members — bundled templates only
└── data.sqlite        a fresh, migrated, empty database
```

It also appends a managed block to your `.gitignore` (idempotent — safe to run again):

```gitignore theme={null}
.substrate/data.sqlite
.substrate/data.sqlite-wal
.substrate/data.sqlite-shm
.substrate/substrate.pid
.substrate/serve.json
.substrate/attachments/
.substrate/logs/
```

<Note>
  A bundled template ships default members; a path template carries boards only in v0.7.0. See [Publish a Template](/authoring/publish-a-template) for the full manifest format.
</Note>

## Output

A bare `init` (no template) prints no board line. With a template:

```text theme={null}
Substrate initialized in /path/to/project/.substrate
Starter boards added (web-delivery): delivery.

Next steps:
  1. Review the starter board(s): .substrate/boards/delivery.json
  2. Start the substrate UI:  substrate serve
  3. Configure your agent runtime to spawn:  substrate mcp
```

## See Also

* [`substrate add`](/cli/add) applies a template into a `.substrate/` that already exists.