Skip to main content
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.
Substrate v0.7.0 has no automatic retention or pruning. Backups accumulate in .substrate/backups/ until you delete them manually.

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

​
Import

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

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

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

Extract safely

Archives are validated against path traversal before any files are extracted.
You cannot import while a substrate serve process is running. Stop the server first, then import.

​
What to Commit

Not everything in .substrate/ belongs in version control. The table below shows the boundary. Export and import are the supported way to move task state across that boundary — SQLite files are not safe to commit or diff directly.
See Worktrees and Clones for a detailed explanation of why this boundary exists and how agents should handle it when working across checkouts.