---
title: "Restore Snapshot"
description: "Documentation for Restore Snapshot Command in ZeyOS SDK CLI"
canonical_url: "https://www.zeyos.com/sdk/snapshot-management/zeysdk-snapshot-restore"
markdown_url: "https://www.zeyos.com/ai/guide/sdk/snapshot-management/zeysdk-snapshot-restore.md"
section: "sdk"
authority: "guide"
language: "en"
source_repository: "zeyos/sdk-v2"
source_path: "docs/snapshot-management/zeysdk-snapshot-restore.md"
source_revision: "a99897af74253b4dc5af6fecb9301cea0ae18e27"
---

# 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