> ## 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.

# cloudstic restore

> Restore files from a backup snapshot to a ZIP archive or directory

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

```bash theme={null}
cloudstic restore [snapshot_id] [options]
```

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

## Options

<ParamField path="snapshot_id" type="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
</ParamField>

<ParamField path="-output" type="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
</ParamField>

<ParamField path="-format" type="string" default="auto">
  Restore format: `zip` or `dir`.

  When omitted, format is inferred from `-output`.
</ParamField>

<ParamField path="-path" type="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.
</ParamField>

<ParamField path="-dry-run" type="boolean" default="false">
  Show what would be restored without creating the archive.

  Displays file count, directory count, and estimated uncompressed size.
</ParamField>

### Global Options

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

## Examples

<CodeGroup>
  ```bash Latest Snapshot theme={null}
  cloudstic restore
  ```

  ```bash Restore To Directory theme={null}
  cloudstic restore -format dir -output ./restore-dir
  ```

  ```bash Specific Snapshot theme={null}
  cloudstic restore a3f8d2e1
  ```

  ```bash Custom Output Path theme={null}
  cloudstic restore abc123 -output ~/backups/restore-2024-03-15.zip
  ```

  ```bash Auto-Detect Directory Format theme={null}
  cloudstic restore abc123 -output ~/backups/restore-2024-03-15
  ```

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

  ```bash Directory Tree theme={null}
  cloudstic restore latest -path Photos/2024/
  ```

  ```bash Dry Run theme={null}
  cloudstic restore latest -path Documents/ -dry-run
  ```

  ```bash With Verbose Output theme={null}
  cloudstic restore -output full-restore.zip -verbose
  ```
</CodeGroup>

## Output

### Successful Restore

```plaintext theme={null}
Restore complete. Snapshot: snapshot/a3f8d2e1...
  Files: 127, Dirs: 18
  Output: ./restore.zip (45.3 MiB)
```

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

```plaintext theme={null}
Restore complete. Snapshot: snapshot/a3f8d2e1...
  Files: 0, Dirs: 18, Warnings: 1
  Output: ./restore-dir (45.3 MiB)
```

### Dry Run Output

```plaintext theme={null}
Restore dry run complete. Snapshot: snapshot/a3f8d2e1...
  Files: 127, Dirs: 18
  Estimated size: 45.3 MiB
```

## 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)

<Note>
  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.
</Note>

### 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

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

### By Short Prefix

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

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

### By "latest"

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

Restores the most recent snapshot based on creation time.

<Tip>
  Use `cloudstic list` to view all available snapshots with their IDs and creation times.
</Tip>

## Path Filtering

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

### File Path

Restore a single file:

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

### Directory Path

Restore an entire directory (note the trailing slash):

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

### Nested Path

Restore a subdirectory:

```bash theme={null}
cloudstic restore latest -path Photos/2024/January/
```

<Note>
  Paths are case-sensitive and must match the exact path structure in the snapshot. Use `cloudstic ls` to explore the snapshot's directory tree.
</Note>

## 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)

<Tip>
  Use `-verbose` to see per-file progress during restore. Use `-quiet` to suppress progress bars.
</Tip>

## 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.

<Warning>
  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.
</Warning>

## See Also

* [cloudstic list](/commands/list): List all backup snapshots
* [cloudstic ls](/commands/ls): Browse files within a snapshot
* [cloudstic find](/commands/find): Locate a file across every snapshot
* [cloudstic diff](/commands/diff): Compare snapshots to find changed files