Restore Snapshot

The snapshot restore command reverts a project to a previous snapshot state.

Bash

zeysdk snapshot restore [SNAPSHOT_ID] [options]

Parameters

Parameter	Description	Required	Example
SNAPSHOT_ID	ID of snapshot to restore	No	20231101-123456

Options

Option	Description
--dir <directory>	Target directory
-f, --force	Skip confirmation

Process

1. Snapshot Selection

   • Uses SNAPSHOT_ID when provided
   • Shows an interactive snapshot list when no ID is provided
   • Stops when no snapshot is selected
   • Press Escape in the picker to exit
   • Accepts the ID with or without .zip, but rejects paths, traversal segments, and unsafe filename characters

2. Confirmation

   • Asks before restoring by default
   • Skips the prompt with --force
   • Warns that current changes will be overwritten
   • Press Escape to return to the picker with the same snapshot selected, or to exit when an ID was supplied directly

3. Validation and Staging

   • Opens the ZIP and rejects absolute, parent-traversal, and out-of-target entries
   • Rejects archived root .git and node_modules entries so snapshots cannot replace destination operational state
   • Extracts the complete archive to a uniquely named sibling staging directory
   • Leaves the target untouched if validation or extraction fails

4. Root State Merge and Commit

   • Copies the target's existing root .zeysdk into the staged tree
   • Overlays snapshot copies of .zeysdk/assets.json and .zeysdk/package.json
   • Does not specially preserve nested .zeysdk directories elsewhere in the old project
   • Renames the original target to a temporary backup and the staged tree to the target
   • Moves the target's root .git and node_modules into the staged tree during the guarded swap, without copying their contents; preserves Git directories, worktree pointer files, and dependency symlinks
   • Restores the original target and its operational state if the staged rename fails; retains and reports recovery paths if rollback itself fails

Examples

Bash

zeysdk snapshot restore 20231101-123456
zeysdk snapshot restore 20231101-123456 -f
zeysdk snapshot restore 20231101-123456 --dir ./test-env
zeysdk snapshot restore

Error Handling

Error	Description	Resolution
Not found	Snapshot ID does not exist	Check zeysdk snapshot list
No selection	No snapshot selected interactively	Select a snapshot or pass SNAPSHOT_ID
Access denied	Target files cannot be replaced	Check file permissions
Extract failed	Snapshot archive could not be extracted	Verify the snapshot archive
Unsafe archive	ZIP contains a path outside the restore root	Do not restore the archive; recreate it from a trusted project
Unsafe target	Target is a filesystem root, symlink, or parent of the running CLI directory	Choose a normal project directory and run from a safe location
Cancelled	Restore prompt was declined	Re-run with confirmation or --force

Warning

Restore operation will:

• Overwrite existing files
• Remove additional files
• Cannot be undone

Notes

• --dir defaults to the current directory
• The snapshot archive is always read from .zeysdk/snapshots under the directory where the command was started, even when --dir points elsewhere
• Restore preserves the target's root .git, node_modules, and .zeysdk; archived supported manifest files take precedence over their current versions
• Git history, branches, index, and stashes remain current; snapshot restoration changes the working files, not the Git revision. Existing dependencies remain installed and may need updating if the restored dependency manifests differ
• Additional old target files, including nested .zeysdk directories, are removed by the successful directory swap
• Runtime extraction and commit errors are rollback-safe, but a completed restore intentionally replaces the old project tree
• If the snapshot does not exist, the command reports the missing ID and stops

Best Practices

• Run zeysdk snapshot list before restoring if you are unsure which snapshot to use
• Create a new snapshot before restoring when current work may still be needed
• Use --dir to inspect a restore in a separate folder
• Use --force only in scripted or fully verified workflows