> ## 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 export / import — Move a Substrate Archive

> substrate export writes a .tar.gz of the full substrate; substrate import restores it, with safeguards against overwriting a live project.

Use `substrate export` and `substrate import` together to move a complete substrate — workflow and runtime state — between machines or checkouts. Export writes a `.tar.gz` to any path you choose; import restores it with safeguards that prevent you from overwriting a live or running project by accident.

## Export

```shell theme={null}
substrate export <path>
```

Writes a `.tar.gz` of the substrate to any path. The archive includes both the workflow (boards, policies, members) and runtime state (the task database). Use it to move a project between machines or to hand someone a substrate in full.

<ParamField path="path" type="string" required>
  The destination path for the `.tar.gz` archive.
</ParamField>

## Import

```shell theme={null}
substrate import <path>
substrate import <path> --force
```

Restores an archive into `.substrate/`.

<ParamField path="path" type="string" required>
  The `.tar.gz` archive to restore.
</ParamField>

<ParamField path="--force" type="flag">
  Overwrite an existing project. Without this flag, `import` refuses when a `config.json` is already present.
</ParamField>

## Two Refusals

`import` stops in two situations, regardless of `--force`:

1. **An existing project** — a `config.json` in place means `import` stops unless you pass `--force`.
2. **A live server** — if a running `serve` holds `.substrate/substrate.pid`, `import` refuses outright. Writing over a live database would corrupt it. Stop the server first.

<Warning>
  `--force` replaces the substrate, including its task database. Run `substrate backup` first.
</Warning>

Archives are validated against path traversal before extraction.

## Moving State Between Checkouts

This is the supported way to get task state into a worktree or fresh clone:

```shell theme={null}
substrate export /tmp/substrate.tar.gz    # in the main checkout
substrate import /tmp/substrate.tar.gz    # in the other checkout
```

The transfer is explicit and one-directional — you decide which side is authoritative. See [Worktrees and Clones](/agents/worktrees-and-clones).