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

# capsule download

> Download and decrypt a cloud backup to a local .sql.gz file.

## Usage

```bash theme={null}
capsule download <backup-id>
capsule download <backup-id> --output ./mybackup.sql.gz
```

## When to run this

| Situation                                        | Why                                                                                                                              |
| ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
| You need a readable copy of your data            | The `.enc` file from the dashboard is encrypted and cannot be opened directly — `capsule download` gives you the plain `.sql.gz` |
| Cross-environment restore                        | Download the backup on the source server, copy the `.sql.gz` to the target server, then restore                                  |
| Restoring on a machine without the Capsule agent | Produces a standard `.sql.gz` that any Postgres/MySQL/Mongo client can import                                                    |
| Importing into a local dev environment           | Lets you seed a local database from a production or staging snapshot                                                             |
| Archiving a specific snapshot externally         | Produces a portable file you can store in S3, a USB drive, or any other storage                                                  |
| Inspecting the SQL before applying it            | Unzip the `.sql.gz`, review the statements, then restore once you are satisfied                                                  |

<Info>
  The download button on the Backups dashboard page gives you the raw `.enc` (encrypted) file, which is not directly usable. `capsule download` is the command that decrypts it for you on the server that holds the key.
</Info>

## What it does

1. Fetches the backup from Capsule cloud storage using a short-lived presigned URL
2. Decrypts it locally using the AES-256 key stored on your server
3. Saves the result as a standard `.sql.gz` file

The decryption key never leaves your server — Capsule's infrastructure only ever sees the encrypted file.

## Example

```bash theme={null}
# Find the backup ID in the dashboard URL or on the Backups page
capsule download fd2849ca-c994-4ca0-b220-3979180272c6

# Output:
# Downloading fd2849ca-c994-4ca0-b220-3979180272c6...
# Decrypting...
# Saved: /home/you/fd2849ca-c994-4ca0-b220-3979180272c6.sql.gz
# Restore with: capsule restore --file "/home/you/fd2849ca-c994-4ca0-b220-3979180272c6.sql.gz"

# Custom output path
capsule download fd2849ca-c994-4ca0-b220-3979180272c6 --output ./prod-snapshot.sql.gz
```

## Flags

| Flag             | Description                                                                  |
| ---------------- | ---------------------------------------------------------------------------- |
| `--output`, `-o` | Output file path. Defaults to `<backup-id>.sql.gz` in the current directory. |

## After downloading

Restore the file to any connection with:

```bash theme={null}
capsule restore --file ./prod-snapshot.sql.gz
capsule restore --file ./prod-snapshot.sql.gz --connection staging-db
```

See [`capsule restore --file`](/cli/backup-restore#from-a-local-file-capsule-restore---file) for the full restore options.

## Requirements

* Must be run on the server that originally took the backup, **or** any server that has imported the same encryption key via `capsule auth --restore`
* Requires an active license key (`capsule auth` must have been run first)

<Warning>
  Running `capsule download` on a server with a different encryption key will fail at the decryption step with an error. Use `capsule auth --restore` to import the correct key first.
</Warning>

## See also

* [`capsule restore --file`](/cli/backup-restore#from-a-local-file-capsule-restore---file) — restore a database from a downloaded file
* [`capsule auth --restore`](/cli/auth#disaster-recovery) — import an encryption key on a new server