Usage
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 |
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.
What it does
- Fetches the backup from Capsule cloud storage using a short-lived presigned URL
- Decrypts it locally using the AES-256 key stored on your server
- 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
# 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:
capsule restore --file ./prod-snapshot.sql.gz
capsule restore --file ./prod-snapshot.sql.gz --connection staging-db
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)
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.
See also
