Skip to main content
Restore files from a backup snapshot to either a ZIP archive or a filesystem directory. You can restore the entire snapshot, a specific file, or a subdirectory tree.

​
Usage

If no snapshot ID is provided, the latest snapshot is restored.

​
Options

​
string
default:"latest"
Snapshot ID to restore from. Can be:
  • Full snapshot hash (e.g., a3f8d2e1...)
  • Short prefix (e.g., a3f8d2)
  • latest (default): restores the most recent snapshot
​
string
default:"./restore.zip"
Output path.
  • For -format zip, this is the ZIP file path.
  • For -format dir, this is the destination directory path.
If -format is omitted, Cloudstic auto-detects format from -output:
  • Output ending with .zip → ZIP restore
  • Any other output path → directory restore
​
string
default:"auto"
Restore format: zip or dir.When omitted, format is inferred from -output.
​
string
default:""
Restore only the given file or subtree.Examples:
  • Documents/report.pdf: restore a single file
  • Documents/: restore entire Documents directory
  • Photos/2024/: restore a subdirectory
If not specified, the entire snapshot is restored.
​
boolean
default:"false"
Show what would be restored without creating the archive.Displays file count, directory count, and estimated uncompressed size.

​
Global Options

Use -json to emit the command result as a single JSON document on stdout.

​
Examples

​
Output

​
Successful Restore

If Cloudstic skips existing files or cannot replay some best-effort metadata, the summary also shows a warning count:

​
Dry Run Output

​
Output Formats

​
ZIP (-format zip)

Restored files are packaged as a ZIP archive with the following properties:
  • Directory structure preserved: Files maintain their original paths
  • File metadata: Modification times are preserved
  • Compression: Standard ZIP deflate compression (data is already compressed in the repository, so additional compression gain is minimal)
  • Permissions: File permissions and ownership are NOT preserved (limitation of ZIP format)
The ZIP archive contains the full directory tree. If you restore a single file like Documents/report.pdf, the archive will contain a Documents/ folder with report.pdf inside.

​
Directory (-format dir)

Restored files are written directly into the destination directory, preserving the original relative paths from the snapshot.
  • Parent directories are created automatically.
  • Existing files are skipped with warnings instead of being overwritten.
  • Re-running the same restore into the same directory is safe. Already-restored files are skipped, while missing files continue to be restored.
  • On macOS and Linux, Cloudstic replays captured metadata on a best-effort basis, including mode bits, ownership, modification times, extended attributes, and file flags when supported by the destination filesystem.
  • This is useful for immediate local browsing without a ZIP extraction step.

​
Snapshot Selection

You can specify snapshots in multiple ways:

​
By Full Hash

​
By Short Prefix

Cloudstic accepts any prefix that identifies exactly one snapshot. If multiple snapshots match, the command fails instead of choosing one.

​
By “latest”

Restores the most recent snapshot based on creation time.
Use cloudstic list to view all available snapshots with their IDs and creation times.

​
Path Filtering

The -path flag filters files based on their path within the snapshot:

​
File Path

Restore a single file:

​
Directory Path

Restore an entire directory (note the trailing slash):

​
Nested Path

Restore a subdirectory:
Paths are case-sensitive and must match the exact path structure in the snapshot. Use cloudstic ls to explore the snapshot’s directory tree.

​
Performance

Restore performance depends on:
  • File size: Larger files take longer to download and write
  • File count: Many small files have more overhead than fewer large files
  • Network bandwidth: Download speed from your storage backend
  • Storage backend: Cloud storage (S3, B2) is slower than local storage
Typical restore speeds:
  • Local storage: 100-500 MB/s
  • Cloud storage (S3/B2): 10-50 MB/s (depends on your internet connection)
  • SFTP: 5-20 MB/s (depends on SSH overhead and network latency)
Use -verbose to see per-file progress during restore. Use -quiet to suppress progress bars.

​
Error Handling

If a restore fails:
  • The partially written output file is automatically deleted for ZIP restores
  • Non-zero exit code is returned
  • Error message indicates the cause (missing snapshot, network error, etc.)
Common errors:
  • Snapshot not found: The specified snapshot ID doesn’t exist. Use cloudstic list to view available snapshots.
  • Path not found: The specified -path doesn’t exist in the snapshot. Use cloudstic ls <snapshot> to explore the snapshot contents.
  • Disk full: Not enough space for the output file/directory.
  • Permission denied: Can’t write to the output path. Check file permissions.

​
Concurrent Restores

Multiple concurrent restore operations are safe:
  • Restores only read from the repository (no writes)
  • Multiple users can restore from the same repository simultaneously
  • Restores do not interfere with backups or other operations

​
Encryption

If your repository is encrypted, you must provide credentials via:
  • -password (or CLOUDSTIC_PASSWORD)
  • -encryption-key (or CLOUDSTIC_ENCRYPTION_KEY)
  • -recovery-key (or CLOUDSTIC_RECOVERY_KEY)
  • -kms-key-arn (for AWS KMS-encrypted repositories)
Without valid credentials, restore will fail with an authentication error.
Restored output is NOT encrypted by default. If you restore to a ZIP file or directory on local disk, store it securely or delete it after use.

​
See Also