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

# Create Snapshot

The `snapshot create` command creates a backup of the current project state.

```bash
zeysdk snapshot create [COMMENT]
```

**Parameters**

| Parameter | Description | Required | Example |
|-----------|-------------|----------|---------|
| `COMMENT` | Description of the snapshot | No | `"Initial setup"` |

**Process**

1. **Comment Collection**
   - Uses the provided `COMMENT` argument when present
   - Prompts for a comment when no argument is provided
   - Requires a non-empty comment
   - Press Escape at the comment prompt to cancel without creating an archive or metadata

2. **Archive Creation**
   - Creates the local snapshot directory when needed
   - Generates `YYYYMMDD-HHMMSS.zip`, adding a numeric suffix if that name already exists
   - Reserves the output filename exclusively instead of overwriting an existing snapshot
   - Creates a compressed `.zip` archive and waits for the output stream to close
   - Removes the partial ZIP if archive creation fails

3. **Metadata Update**
   - Updates metadata only after the ZIP has fully closed
   - Stores the unique snapshot ID
   - Stores the comment
   - Stores the creation timestamp

**Examples**

```bash
zeysdk snapshot create "Initial setup"
zeysdk snapshot create
zeysdk snapshot create "Release v2.1.0"
zeysdk snapshot create "Pre-update: Payment API"
```

**Error Handling**

| Error | Description | Resolution |
|-------|-------------|------------|
| Missing comment | No comment entered at prompt | Enter a non-empty comment |
| Snapshot write error | Archive could not be created | Check write permissions |
| Archive error | File compression failed | Check file access and disk space |
| Metadata error | Snapshot metadata could not be updated | Check snapshot storage permissions |

**Notes**

- Snapshot IDs are generated from local date and time; collision suffixes preserve both same-second snapshots
- The normal project glob includes dotfiles and excludes root `.git`, `node_modules`, and `.zeysdk/**`
- Both `.git` directories and worktree `.git` pointer files are excluded
- `.zeysdk/assets.json` and `.zeysdk/package.json` are added explicitly when present
- `settings/defaultsettings.json` is included once through the normal project glob
- Other hidden files and directories are included unless covered by the exclusions above
- Generated directories such as `dist` and `build` are included; root `node_modules` is excluded
- Restore preserves the destination's current root `.git` and `node_modules` by moving them into the restored tree without copying their contents. Git history, stashes, and worktree identity survive; dependencies may need updating for restored manifests
- Restore rejects archives containing reserved root `.git` or `node_modules` entries, including older archives containing a worktree pointer. These entries must not replace destination operational state
- Preservation and archive validation use existing dependencies only
- Snapshot archives are compressed as ZIP files

**Best Practices**

- Create a snapshot before large refactors to a current-format project
- Use comments that describe the reason for the snapshot
- Include release, task, or change names in comments when helpful
- Create a fresh snapshot after a stable milestone