capsule download

Usage

capsule download <backup-id>
capsule download <backup-id> --output ./mybackup.sql.gz

<backup-id> can be the short 10-character ID shown by capsule backup list, or the full UUID from the dashboard.

Finding your backup ID

Run capsule backup list to see all available backups and their short IDs:

capsule backup list

  550e8400e2   my-postgres   1.2 MB   2026-07-01 02:00 UTC
  a3f91bc4d8   my-postgres   1.1 MB   2026-06-30 02:00 UTC

You can also copy a backup’s short ID from the Backups page in the dashboard using the copy icon next to each row.

When to run this

Situation	Why
You need a readable copy of your data	The `.enc` file from the dashboard is encrypted — `capsule download` gives you the plain `.sql.gz`
Cross-environment restore	Download on the source server, copy the `.sql.gz` to the target, then restore. The target server must have the same encryption key — run `capsule auth --restore` on it first if it does not.
Restoring on a machine without the Capsule agent	Produces a standard `.sql.gz` that any Postgres/MySQL/Mongo client can import. You must still run `capsule download` on a server that holds the key — the decryption happens there.
Importing into a local dev environment	Lets you seed a local database from a production or staging snapshot. Run `capsule download` on the server that has the key, then copy the `.sql.gz` to your local machine.
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

capsule download must be run on a server that holds the original encryption key. The downloaded .sql.gz file is already decrypted — if you move it to another machine to restore, that machine does not need the key. But if you try to run capsule download itself on a server with a different key, decryption will fail. Use capsule auth --restore to import the correct key onto any server that needs it.

The download button on the dashboard gives you the raw .enc (encrypted) file, which is not directly usable. capsule download decrypts it on the server that holds your key.

What it does

Resolves the short ID to the full UUID if needed
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

# List backups to find the ID
capsule backup list

# Download using the short ID
capsule download 550e8400e2

# Output:
# Downloading 550e8400-e29b-41d4-a716-446655440000...
# Decrypting...
# Saved: /home/you/550e8400-e29b-41d4-a716-446655440000.sql.gz
# Restore with: capsule restore --file "/home/you/550e8400-e29b-41d4-a716-446655440000.sql.gz"

# Custom output path
capsule download 550e8400e2 --output ./prod-snapshot.sql.gz

Flags

Flag	Description
`--output`, `-o`	Output file path. Defaults to `<full-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

See capsule restore for 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)

Getting Started

CLI Reference

Database Guides

Dashboard

Releases

Usage

Finding your backup ID

When to run this

What it does

Example

Flags

After downloading

Requirements

See also

​Usage

​Finding your backup ID

​When to run this

​What it does

​Example

​Flags

​After downloading

​Requirements

​See also

Usage

Finding your backup ID

When to run this

What it does

Example

Flags

After downloading

Requirements

See also