Skip to main content
This guide explains how to restore files from your Cloudstic backups. You can restore entire snapshots or individual files and directories.

​
Understanding Restore Operations

Cloudstic’s restore command:
  • Restores to either a ZIP archive or a directory
  • Preserves directory structure and file metadata
  • Decrypts and decompresses data automatically
  • Can restore entire snapshots or specific paths
If -format is omitted, Cloudstic infers restore format from -output:
  • .zip output path -> ZIP restore
  • any other output path -> directory restore

​
Finding Snapshots to Restore

First, list available snapshots:
Output:
Browse files within a snapshot:

​
When you do not know which snapshot has it

Listing and browsing works when you already know roughly where the file is. When you do not — the usual case, because the file you want back is often one that was deleted months ago — use cloudstic find instead of guessing snapshots one at a time:
It searches every snapshot, groups the results by file, and prints the exact restore command for the newest version:
To restore an older version, use the newest snapshot prefix shown for that version. Use find -json when you need the full reference.

​
Restoring the Latest Snapshot

Restore the most recent backup:
By default, this creates ./restore.zip containing all files from the latest snapshot. Customize the output path:
Restore directly to a directory:
In directory mode, Cloudstic creates parent directories automatically and, on macOS and Linux, replays captured metadata on a best-effort basis (for example mode bits, ownership, modification times, xattrs, and file flags where the destination filesystem allows it). If files already exist in the destination directory, Cloudstic skips them with warnings instead of overwriting them. This makes rerunning the same restore into the same directory safe.

​
Restoring a Specific Snapshot

Restore by snapshot hash:
You can use:
  • Full hash: abc123def456789...
  • Short hash: abc123def456 (any unique prefix)
  • The keyword latest for the most recent snapshot

​
Restoring Specific Files or Directories

Use -path to restore only part of a snapshot.

​
Restore a Single File

With ZIP output, this creates an archive containing only Documents/report.pdf.

​
Restore a Directory

Add a trailing slash to restore an entire directory:
This restores Documents/ and all its subdirectories.
The trailing slash matters:
  • Documents/report.pdf → single file
  • Documents/ → entire directory
  • Documents → no match (use the trailing slash)

​
Restore a Subdirectory

Restores Documents/Projects/Website/ and all files within it.

​
Previewing Without Writing

Use -dry-run to see what would be restored without creating a ZIP file:
Output:
Combine with -path to preview specific files:

​
Working With Restored Files

​
Restore directly to a directory

If you want files immediately on disk without extraction, restore in directory mode:

​
Extracting from ZIP output

Once you have the ZIP archive, extract it:

​
Linux / macOS

​
Windows (PowerShell)

​
Windows (Command Prompt)

Modern Windows (10+) includes tar which can extract ZIP files.

​
Common Restore Scenarios

​
Scenario 1: Accidental File Deletion

You deleted a file and need to recover it:
1

Find the most recent snapshot

2

Verify the file exists in the snapshot

3

Restore only that file

4

Extract and copy to original location

​
Scenario 2: Restore Entire System

Recover all files after data loss:

​
Scenario 3: Compare File Versions

Restore the same file from multiple snapshots to compare versions:

​
Scenario 4: Partial Disaster Recovery

Recover only critical directories:

​
Verbose Output

See detailed progress during restore:
Output:

​
Restoring to Different Machines

Cloudstic backups are portable. To restore on a different machine:
1

Install Cloudstic on the target machine

Follow the installation guide.
2

Configure access to your repository

3

List snapshots to verify access

4

Restore as usual

You need the same encryption credentials (password or recovery key) used during init to restore backups.

​
Using Recovery Keys

If you’ve lost your password but have your recovery key phrase:
Or provide it directly:
Store your 24-word recovery key in a safe place. It’s your last line of defense if you lose your password.

​
Performance Tips

​
Large Restores

For very large snapshots:
  1. Restore specific paths instead of the entire snapshot:
  2. Use dry-run first to estimate size:
  3. Ensure sufficient disk space for the ZIP file (roughly the same size as the original data).

​
Remote Storage

When restoring from S3/B2:
  • Restore runs faster in the same region as your bucket
  • Network speed affects restore time
  • Use AWS EC2 or similar for very large restores

​
Troubleshooting

​
”Snapshot not found” Error

Verify the snapshot exists:
Use the correct hash from the “Snapshot Hash” column.

​
”Permission denied” Writing ZIP

Ensure you have write access to the output directory:

​
“Failed to decrypt” Error

Your encryption password or key is incorrect. Double-check:
Or use your recovery key:

​
Restore is Slow

Large snapshots take time. Use -verbose to monitor progress:

​
Best Practices

1

Test restores regularly

Verify you can recover files before you need to:
2

Document your restore procedure

Keep notes on how to restore backups, including:
  • Repository location and credentials
  • Common restore commands
  • Recovery key location
3

Use dry-run for large restores

Preview before committing:
4

Extract to a staging directory

Never extract directly to production:
5

Keep recovery credentials accessible

Store your encryption password and recovery key in a password manager or safe location.

​
Next Steps

Encryption Keys

Manage passwords and recovery keys

Retention Policies

Decide which snapshots to keep

Diff Command

Compare snapshots before restoring

Check Command

Verify backup integrity before restore