> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudstic.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Restoring Files from Backups

> How to recover files and directories from Cloudstic snapshots as ZIP archives or directories

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

<Note>
  If `-format` is omitted, Cloudstic infers restore format from `-output`:

  * `.zip` output path -> ZIP restore
  * any other output path -> directory restore
</Note>

## Finding Snapshots to Restore

First, list available snapshots:

```bash theme={null}
cloudstic list
```

Output:

```
+-----+---------------------+------------------+--------+---------+------------+------+
| Seq | Created             | Snapshot Hash    | Source | Account | Path       | Tags |
+-----+---------------------+------------------+--------+---------+------------+------+
| 5   | 2026-03-03 22:00:00 | abc123def456...  | local  |         | /Documents |      |
| 4   | 2026-03-02 22:00:00 | def456abc789...  | local  |         | /Documents |      |
| 3   | 2026-03-01 22:00:00 | ghi789def012...  | gdrive | user    |            |      |
...
+-----+---------------------+------------------+--------+---------+------------+------+
```

Browse files within a snapshot:

```bash theme={null}
cloudstic ls abc123def456
```

### 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`](/commands/find) instead of guessing snapshots one at a time:

```bash theme={null}
cloudstic find "budget-2025.xlsx"
```

It searches every snapshot, groups the results by file, and prints the exact `restore` command for the newest version:

```
Documents/budget-2025.xlsx  (3 versions)
  v1 filemeta/9f86d081  1.2 MiB  2026-02-28 17:40  4 snapshots 4e5d5487..abc123de
  v2 filemeta/2c624232  1.1 MiB  2026-01-14 09:02  9 snapshots 1b645389..7d793037
  v3 filemeta/e3b0c442  980 KiB  2025-11-03 11:47  6 snapshots 5f9c3a11..a71e04bd

Restore the newest version of Documents/budget-2025.xlsx:
  cloudstic restore -path Documents/budget-2025.xlsx abc123de -output ./restored
```

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:

```bash theme={null}
cloudstic restore
```

By default, this creates `./restore.zip` containing all files from the latest snapshot.

Customize the output path:

```bash theme={null}
cloudstic restore -output ~/my-backup.zip
```

Restore directly to a directory:

```bash theme={null}
cloudstic restore -format dir -output ~/recovered-files
```

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:

```bash theme={null}
cloudstic restore abc123def456
```

You can use:

* Full hash: `abc123def456789...`
* Short hash: `abc123def456` (any unique prefix)
* The keyword `latest` for the most recent snapshot

<CodeGroup>
  ```bash Full Hash theme={null}
  cloudstic restore abc123def456789abc123def456789abc123def456789abc123de
  ```

  ```bash Short Hash theme={null}
  cloudstic restore abc123
  ```

  ```bash Latest theme={null}
  cloudstic restore latest -output latest-backup.zip
  ```
</CodeGroup>

## Restoring Specific Files or Directories

Use `-path` to restore only part of a snapshot.

### Restore a Single File

```bash theme={null}
cloudstic restore abc123 -path Documents/report.pdf
```

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

### Restore a Directory

Add a trailing slash to restore an entire directory:

```bash theme={null}
cloudstic restore abc123 -path Documents/
```

This restores `Documents/` and all its subdirectories.

<Warning>
  The trailing slash matters:

  * `Documents/report.pdf` → single file
  * `Documents/` → entire directory
  * `Documents` → no match (use the trailing slash)
</Warning>

### Restore a Subdirectory

```bash theme={null}
cloudstic restore abc123 -path Documents/Projects/Website/
```

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:

```bash theme={null}
cloudstic restore abc123 -dry-run
```

Output:

```
Restoring snapshot abc123def456...

Files to restore:
  Documents/
  Documents/report.pdf (2.3 MiB)
  Documents/notes.txt (15 KiB)
  Documents/Projects/
  Documents/Projects/Website/
  Documents/Projects/Website/index.html (4 KiB)
  ...

Dry run complete.
  Files:  847
  Dirs:   123
  Total:  2.34 GiB
```

Combine with `-path` to preview specific files:

```bash theme={null}
cloudstic restore abc123 -path Documents/ -dry-run
```

## Working With Restored Files

### Restore directly to a directory

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

```bash theme={null}
cloudstic restore abc123 -format dir -output ~/recovered-files
```

### Extracting from ZIP output

Once you have the ZIP archive, extract it:

### Linux / macOS

```bash theme={null}
# Extract to current directory
unzip restore.zip

# Extract to a specific directory
unzip restore.zip -d ~/recovered-files/

# List contents without extracting
unzip -l restore.zip
```

### Windows (PowerShell)

```powershell theme={null}
# Extract to current directory
Expand-Archive -Path restore.zip -DestinationPath .

# Extract to a specific directory
Expand-Archive -Path restore.zip -DestinationPath C:\RecoveredFiles\
```

### Windows (Command Prompt)

```cmd theme={null}
tar -xf restore.zip
```

<Tip>
  Modern Windows (10+) includes `tar` which can extract ZIP files.
</Tip>

## Common Restore Scenarios

### Scenario 1: Accidental File Deletion

You deleted a file and need to recover it:

<Steps>
  <Step title="Find the most recent snapshot">
    ```bash theme={null}
    cloudstic list
    ```
  </Step>

  <Step title="Verify the file exists in the snapshot">
    ```bash theme={null}
    cloudstic ls abc123 | grep "report.pdf"
    ```
  </Step>

  <Step title="Restore only that file">
    ```bash theme={null}
    cloudstic restore abc123 -path Documents/report.pdf -output report-recovery.zip
    ```
  </Step>

  <Step title="Extract and copy to original location">
    ```bash theme={null}
    unzip report-recovery.zip
    cp Documents/report.pdf ~/Documents/
    ```
  </Step>
</Steps>

### Scenario 2: Restore Entire System

Recover all files after data loss:

```bash theme={null}
# Restore the latest full snapshot
cloudstic restore -output full-recovery.zip

# Extract to a staging area
mkdir ~/recovery
unzip full-recovery.zip -d ~/recovery/

# Review and move files back
ls ~/recovery/
```

### Scenario 3: Compare File Versions

Restore the same file from multiple snapshots to compare versions:

```bash theme={null}
# Restore from today
cloudstic restore abc123 -path Documents/report.pdf -output report-today.zip

# Restore from last week
cloudstic restore def456 -path Documents/report.pdf -output report-lastweek.zip

# Extract and compare
unzip report-today.zip -d today/
unzip report-lastweek.zip -d lastweek/
diff today/Documents/report.pdf lastweek/Documents/report.pdf
```

### Scenario 4: Partial Disaster Recovery

Recover only critical directories:

```bash theme={null}
# Restore important directories separately
cloudstic restore latest -path Documents/ -output documents.zip
cloudstic restore latest -path Projects/ -output projects.zip
cloudstic restore latest -path Photos/ -output photos.zip

# Extract each to appropriate locations
unzip documents.zip -d /mnt/recovery/
unzip projects.zip -d /mnt/recovery/
unzip photos.zip -d /mnt/recovery/
```

## Verbose Output

See detailed progress during restore:

```bash theme={null}
cloudstic restore abc123 -verbose
```

Output:

```
Restoring snapshot abc123def456...
Dir: Documents/
File: Documents/report.pdf (2.3 MiB)
File: Documents/notes.txt (15 KiB)
Dir: Documents/Projects/
File: Documents/Projects/todo.md (2 KiB)
...

Restore complete.
  Files:  847
  Dirs:   123
  Bytes:  2.34 GiB
```

## Restoring to Different Machines

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

<Steps>
  <Step title="Install Cloudstic on the target machine">
    Follow the [installation guide](/installation).
  </Step>

  <Step title="Configure access to your repository">
    ```bash theme={null}
    export CLOUDSTIC_STORE=s3:my-backup-bucket
    export CLOUDSTIC_PASSWORD="your passphrase"
    export AWS_ACCESS_KEY_ID=your-key
    export AWS_SECRET_ACCESS_KEY=your-secret
    ```
  </Step>

  <Step title="List snapshots to verify access">
    ```bash theme={null}
    cloudstic list
    ```
  </Step>

  <Step title="Restore as usual">
    ```bash theme={null}
    cloudstic restore -output recovered-files.zip
    unzip recovered-files.zip
    ```
  </Step>
</Steps>

<Note>
  You need the same encryption credentials (password or recovery key) used during `init` to restore backups.
</Note>

## Using Recovery Keys

If you've lost your password but have your recovery key phrase:

```bash theme={null}
export CLOUDSTIC_RECOVERY_KEY="word1 word2 word3 ... word24"
cloudstic restore -output emergency-restore.zip
```

Or provide it directly:

```bash theme={null}
cloudstic restore -recovery-key "word1 word2 ... word24" -output emergency.zip
```

<Warning>
  Store your 24-word recovery key in a safe place. It's your last line of defense if you lose your password.
</Warning>

## Performance Tips

### Large Restores

For very large snapshots:

1. **Restore specific paths** instead of the entire snapshot:
   ```bash theme={null}
   cloudstic restore abc123 -path Documents/ -output documents.zip
   cloudstic restore abc123 -path Photos/ -output photos.zip
   ```

2. **Use dry-run first** to estimate size:
   ```bash theme={null}
   cloudstic restore abc123 -dry-run
   ```

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:

```bash theme={null}
cloudstic list | grep abc123
```

Use the correct hash from the "Snapshot Hash" column.

### "Permission denied" Writing ZIP

Ensure you have write access to the output directory:

```bash theme={null}
cloudstic restore -output ~/restore.zip
```

### "Failed to decrypt" Error

Your encryption password or key is incorrect. Double-check:

```bash theme={null}
echo $CLOUDSTIC_PASSWORD
```

Or use your recovery key:

```bash theme={null}
cloudstic restore -recovery-key "word1 word2 ... word24"
```

### Restore is Slow

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

```bash theme={null}
cloudstic restore abc123 -verbose
```

## Best Practices

<Steps>
  <Step title="Test restores regularly">
    Verify you can recover files before you need to:

    ```bash theme={null}
    cloudstic restore latest -path Documents/test.txt -output test-restore.zip
    unzip test-restore.zip
    ```
  </Step>

  <Step title="Document your restore procedure">
    Keep notes on how to restore backups, including:

    * Repository location and credentials
    * Common restore commands
    * Recovery key location
  </Step>

  <Step title="Use dry-run for large restores">
    Preview before committing:

    ```bash theme={null}
    cloudstic restore abc123 -dry-run
    ```
  </Step>

  <Step title="Extract to a staging directory">
    Never extract directly to production:

    ```bash theme={null}
    unzip restore.zip -d ~/staging/
    # Review contents
    cp -r ~/staging/Documents/* ~/Documents/
    ```
  </Step>

  <Step title="Keep recovery credentials accessible">
    Store your encryption password and recovery key in a password manager or safe location.
  </Step>
</Steps>

## Next Steps

<CardGroup cols={2}>
  <Card title="Encryption Keys" icon="key" href="/guides/encryption-keys">
    Manage passwords and recovery keys
  </Card>

  <Card title="Retention Policies" icon="clock" href="/guides/retention-policies">
    Decide which snapshots to keep
  </Card>

  <Card title="Diff Command" icon="code-compare" href="/commands/diff">
    Compare snapshots before restoring
  </Card>

  <Card title="Check Command" icon="check" href="/commands/check">
    Verify backup integrity before restore
  </Card>
</CardGroup>