Skip to main content
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

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.
​
string
required
The destination path for the .tar.gz archive.

​
Import

Restores an archive into .substrate/.
​
string
required
The .tar.gz archive to restore.
​
flag
Overwrite an existing project. Without this flag, import refuses when a config.json is already present.

​
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.
--force replaces the substrate, including its task database. Run substrate backup first.
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:
The transfer is explicit and one-directional — you decide which side is authoritative. See Worktrees and Clones.