> ## 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 add — Apply a Template to an Existing Substrate

> substrate add imports a shared workflow template into an existing .substrate/ — dry run by default, transactional when applied with --yes.

Use `substrate add` to bring a shared workflow template into a project that already has a `.substrate/`. It imports the workflow — boards with their groups, field schemas, and policies — but never tasks, comments, or any database contents. Running without `--yes` is always safe: the command validates and previews but writes nothing.

## Usage

```shell theme={null}
substrate add <path>                 # preview — writes nothing
substrate add <path> --yes           # apply
substrate add <path> --yes --as <id> # apply, renaming a single-board template
```

## Arguments and Options

<ParamField path="path" type="string" required>
  A local directory. The CLI is network-free and never clones — your agent (or you) clones the repo first. Resolves via a `substrate-template.json` manifest at its root, or by convention if its boards live under `.substrate/boards/` or `boards/`.
</ParamField>

<ParamField path="--yes" type="flag">
  Apply the template. Without this flag, `add` validates and previews and **writes nothing**.
</ParamField>

<ParamField path="--as" type="string">
  Rename a single-board template's board on the way in. Use this when the template's board id collides with one you already have.
</ParamField>

<Note>
  Run without `--yes` first, always. The preview validates the template and shows exactly what would be written before you commit to it.
</Note>

## Applying Forks the Workflow

When you apply a template, Substrate forks its workflow into your `.substrate/`. You own the copy from that moment — there is no upstream link and no update path. Future changes to the original template do not propagate automatically.

## Collisions and Rollback

A board-id collision is refused by default — `add` will not overwrite a board you already have. Use `--as <id>` as the escape hatch when working with a single-board template.

An apply is transactional: if a write fails partway through, the files that apply created are removed in reverse order. Pre-existing boards are never touched.

## See Also

* [`substrate init --template`](/cli/init) for seeding a fresh project.
* [Publish a Template](/authoring/publish-a-template) for the manifest format.