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

# Back Up, Export, and Restore Your Substrate Project

> How to snapshot a substrate in place with backup, export it to any path, and safely restore it with import on another machine or checkout.

Substrate gives you three ways to preserve and move task state: an in-place backup that writes a timestamped archive into your repo, an export that places that same archive wherever you choose, and an import that restores it somewhere new. Together they cover the common cases — local snapshots before a risky operation, handing a project to a collaborator, and migrating work between machines.

## Backup

Running `substrate backup` writes a timestamped `.tar.gz` into `.substrate/backups/` and prints the path so you know exactly what was created.

```sh theme={null}
substrate backup
```

<Note>
  Substrate v0.7.0 has no automatic retention or pruning. Backups accumulate in `.substrate/backups/` until you delete them manually.
</Note>

## Export

Export produces the same archive as `backup`, written to a path you control. Use it to move a project between machines or to hand a substrate to someone else in full — both the workflow definition and the runtime state travel together.

```sh theme={null}
substrate export /path/to/substrate.tar.gz
```

## Import

Import restores an archive into `.substrate/`. Two safeguards prevent you from accidentally overwriting live or existing data.

```sh theme={null}
substrate import /path/to/substrate.tar.gz
substrate import /path/to/substrate.tar.gz --force
```

<Steps>
  <Step title="Check for an existing project">
    If a `config.json` is already present in `.substrate/`, import refuses unless you pass `--force`. This prevents a silent overwrite of a project you did not mean to replace.
  </Step>

  <Step title="Check for a live server">
    If a running `substrate serve` holds the PID file, import refuses outright — writing over a live database would corrupt it. Stop the server before importing.
  </Step>

  <Step title="Extract safely">
    Archives are validated against path traversal before any files are extracted.
  </Step>
</Steps>

<Warning>
  You cannot import while a `substrate serve` process is running. Stop the server first, then import.
</Warning>

## What to Commit

Not everything in `.substrate/` belongs in version control. The table below shows the boundary.

| Action           | Files                                                                                      |
| ---------------- | ------------------------------------------------------------------------------------------ |
| **Commit**       | `config.json`, `boards/*.json`, `members/*.json`                                           |
| **Never commit** | `data.sqlite` (and `-wal`, `-shm`), `attachments/`, `logs/`, `substrate.pid`, `serve.json` |

Export and import are the supported way to move task state across that boundary — SQLite files are not safe to commit or diff directly.

<Tip>
  See [Worktrees and Clones](/agents/worktrees-and-clones) for a detailed explanation of why this boundary exists and how agents should handle it when working across checkouts.
</Tip>