Quick Start

Prerequisites

Before starting, make sure you have:

Cloudstic Installed

Follow the installation guide if you haven’t already

Storage Location

Choose where to store backups (local disk, S3, B2, or SFTP)

This quick start uses local storage for simplicity. For cloud storage (S3, B2), see the configuration examples at the end.

Your First Backup in 4 Steps

Initialize a Repository

Create an encrypted repository to store your backups. Cloudstic will prompt you to set a password:

cloudstic init

Command output

Enter new repository password: ********
Confirm repository password: ********
Created new encryption key slots.
Repository initialized (encrypted: true).

This creates a local repository at ./backup_store with AES-256-GCM encryption enabled.

Recommended: Add a recovery key during initialization for emergency access:

cloudstic init -add-recovery-key

Write down the 24-word recovery phrase and store it safely!

Create Your First Backup

Back up a local directory (e.g., your Documents folder):

cloudstic backup -source local:~/Documents

Cloudstic will:

Scan all files in the directory
Chunk and compress each file with zstd
Encrypt chunks with AES-256-GCM
Upload only new chunks (deduplication)
Create an immutable snapshot

Command output

Scanning source...
Found 1,247 files (2.3 GiB)

Uploading new chunks... ███████████████████ 100%

Backup complete.
  Files backed up:     1,247
  New chunks:          3,891
  Bytes uploaded:      2.3 GiB
  Deduplication saved: 0 B (first backup)
  Snapshot hash:       abc123def456...

Skip development artifacts with exclude patterns:

cloudstic backup -source local:~/project \
  -exclude "node_modules/" -exclude ".git/" -exclude "*.log"

List Your Snapshots

View all backups in your repository:

cloudstic list

Command output

+-----+---------------------+------------------+--------+---------+-------------+------+
| SEQ | CREATED             | SNAPSHOT HASH    | SOURCE | ACCOUNT | PATH        | TAGS |
+-----+---------------------+------------------+--------+---------+-------------+------+
| 1   | 2025-03-03 10:30:45 | abc123def456...  | local  |         | ~/Documents |      |
+-----+---------------------+------------------+--------+---------+-------------+------+

Restore Your Files

Restore the latest snapshot:

cloudstic restore

By default, this creates restore.zip in the current directory.

Restore specific files or folders

# Restore a single file
cloudstic restore -path Documents/report.pdf

# Restore an entire folder
cloudstic restore -path Documents/Projects/

# Restore to a custom location
cloudstic restore -output /path/to/my-backup.zip

# Restore directly to a directory
cloudstic restore -format dir -output /path/to/restored-files
 
# Restore a specific snapshot (not the latest)
cloudstic restore abc123def456...

Congratulations! You’ve successfully created and restored your first encrypted backup.

Next: Run an Incremental Backup

Cloudstic’s content-addressable storage makes incremental backups automatic. Just run the same backup command again:

cloudstic backup -source local:~/Documents

Only changed files will be processed, and deduplication will skip chunks that already exist:

Backup complete.
  Files backed up:     1,250 (+3 new)
  New chunks:          18
  Bytes uploaded:      4.7 MiB
  Deduplication saved: 2.29 GiB ⚡
  Snapshot hash:       def789abc012...

Deduplication works across all sources: If you back up the same file from different locations (e.g., a file synced between your local drive and Google Drive), it’s only stored once.

Preview Changes with Dry Run

Before creating a backup, preview what would be uploaded:

cloudstic backup -source local:~/Documents -dry-run

Dry run output

Scanning source...
Found 1,250 files (2.31 GiB)

Would upload:
  New files:      3
  Modified files: 2
  New chunks:     18
  Bytes:          4.7 MiB

Dry run complete (no data written).

Back Up Cloud Drives

Cloudstic works seamlessly with Google Drive and OneDrive using built-in OAuth:

Google Drive
OneDrive

Back up your entire Google Drive

cloudstic backup -source gdrive-changes

On first run, your browser opens automatically for authorization. The token is cached locally for future backups.

gdrive-changes vs gdrive:

gdrive-changes (recommended): Uses the Changes API for fast incremental backups
gdrive: Full scan of every file (use only for the first backup or to force a rescan)

Back up a specific folder

cloudstic backup -source "gdrive-changes:/path/to/folder"

Back up a Shared Drive

cloudstic backup -source "gdrive-changes://Shared Drive Name"

Back up your entire OneDrive

cloudstic backup -source onedrive-changes

On first run, your browser opens automatically for authorization. The token is cached locally for future backups.

onedrive-changes vs onedrive:

onedrive-changes (recommended): Uses the Delta API for fast incremental backups
onedrive: Full scan of every file (use only for the first backup or to force a rescan)

OneDrive backups use built-in OAuth credentials. No Microsoft app registration required!

Use Cloud Storage Backends

Store your backups on cloud storage for durability and accessibility:

Amazon S3
Backblaze B2
SFTP

# Set credentials (or use AWS CLI profiles)
export AWS_ACCESS_KEY_ID=your-access-key
export AWS_SECRET_ACCESS_KEY=your-secret-key

# Initialize repository in S3 bucket
cloudstic init -store s3:my-backup-bucket

# Create a backup
cloudstic backup -store s3:my-backup-bucket \
  -source local:~/Documents

S3-Compatible Storage (R2, MinIO, Wasabi)

For S3-compatible services, specify a custom endpoint:

# Cloudflare R2
cloudstic init -store s3:my-bucket \
  -s3-endpoint https://<account_id>.r2.cloudflarestorage.com \
  -s3-region auto

# MinIO
cloudstic init -store s3:my-bucket \
  -s3-endpoint https://minio.example.com \
  -s3-region us-east-1

# Set B2 credentials
export B2_KEY_ID=your-key-id
export B2_APP_KEY=your-app-key

# Initialize repository in B2 bucket
cloudstic init -store b2:my-backup-bucket

# Create a backup
cloudstic backup -store b2:my-backup-bucket \
  -source local:~/Documents

Backblaze B2 is significantly cheaper than S3 for backup storage. Perfect for long-term retention.

# Initialize repository on SFTP server
cloudstic init \
  -store sftp://backup@myserver.com/backups/cloudstic \
  -store-sftp-key ~/.ssh/id_ed25519

# Create a backup
cloudstic backup \
  -store sftp://backup@myserver.com/backups/cloudstic \
  -store-sftp-key ~/.ssh/id_ed25519 \
  -source local:~/Documents

SFTP supports password authentication (-store-sftp-password) or SSH key authentication (-store-sftp-key). If neither is provided, Cloudstic uses your SSH_AUTH_SOCK agent.

Simplify with Profiles

Save your backup configuration once and reuse it:

# Create a store
cloudstic store new -name my-s3 -uri s3:my-backup-bucket -s3-region us-east-1

# Create a profile
cloudstic profile new -name documents -source local:~/Documents -store-ref my-s3

# Now backups are one command
cloudstic backup -profile documents

See the Using Profiles guide for the complete walkthrough, including store encryption, cloud auth, and multi-profile automation.

Alternative: Environment Variables

You can also use environment variables instead of profiles:

~/.bashrc or ~/.zshrc

# Storage configuration
export CLOUDSTIC_STORE=s3:my-backup-bucket
export AWS_ACCESS_KEY_ID=your-access-key
export AWS_SECRET_ACCESS_KEY=your-secret-key

# Encryption
export CLOUDSTIC_PASSWORD="my secure passphrase"

# Default source
export CLOUDSTIC_SOURCE=local:~/Documents

Now commands become much simpler:

# Just run:
cloudstic backup

# Instead of:
cloudstic backup -store s3:my-bucket \
  -source local:~/Documents \
  -password "..."

Common Operations

Compare two snapshots

See what changed between backups:

cloudstic diff abc123def456... def789abc012...

Or compare against the latest:

cloudstic diff abc123def456... latest

Browse snapshot contents

List all files in a snapshot:

cloudstic ls

# Or specify a snapshot
cloudstic ls abc123def456...

Remove old snapshots

Delete a specific snapshot:

cloudstic forget abc123def456...

Apply retention policies to automatically clean up old backups:

# Keep last 7 snapshots + 4 weekly + 12 monthly
cloudstic forget -keep-last 7 -keep-weekly 4 -keep-monthly 12

Reclaim storage space

After forgetting snapshots, run prune to delete unreferenced chunks:

cloudstic prune

Or combine forget and prune in one command:

cloudstic forget abc123def456... -prune

Verify repository integrity

Check the repository for corruption:

# Basic integrity check
cloudstic check

# Full byte-level verification (re-hashes all chunks)
cloudstic check -read-data

Change repository password

cloudstic key passwd

Or non-interactively:

cloudstic key passwd \
  -password "old passphrase" \
  -new-password "new passphrase"

Automation Tips

Cron Job

Schedule daily backups:

# Add to crontab (crontab -e)
0 2 * * * /usr/local/bin/cloudstic backup

Platform Keys

Use hex keys instead of passwords for automation:

# Generate a 32-byte hex key
KEY=$(openssl rand -hex 32)

# Initialize with platform key
cloudstic init -encryption-key $KEY

# Store key securely (e.g., in CI secrets)
export CLOUDSTIC_ENCRYPTION_KEY=$KEY

Never commit credentials to version control! Use environment variables or secret management tools.

What’s Next?

Using Profiles

Save and reuse backup configurations with profiles, stores, and auth

Encryption Keys

Learn about key slots, recovery keys, and security design

Automation

Schedule automatic backups with cron and systemd

Retention Policies

Manage snapshot lifecycle and reclaim storage space

Need help? Join the discussion at github.com/cloudstic/cli/discussions or report issues at github.com/cloudstic/cli/issues.

Get Started

Core Concepts

Sources

Storage Backends

Guides

Prerequisites

Cloudstic Installed

Storage Location

Your First Backup in 4 Steps

Next: Run an Incremental Backup

Preview Changes with Dry Run

Back Up Cloud Drives

Back up your entire Google Drive

Back up a specific folder

Back up a Shared Drive

Back up your entire OneDrive

Use Cloud Storage Backends

Simplify with Profiles

Alternative: Environment Variables

Common Operations

Automation Tips

Cron Job

Platform Keys

What’s Next?

Using Profiles

Encryption Keys

Automation

Retention Policies

​Prerequisites

Cloudstic Installed

Storage Location

​Your First Backup in 4 Steps

​Next: Run an Incremental Backup

​Preview Changes with Dry Run

​Back Up Cloud Drives

​Back up your entire Google Drive

​Back up a specific folder

​Back up a Shared Drive

​Back up your entire OneDrive

​Use Cloud Storage Backends

​Simplify with Profiles

​Alternative: Environment Variables

​Common Operations

​Automation Tips

Cron Job

Platform Keys

​What’s Next?

Using Profiles

Encryption Keys

Automation

Retention Policies

Prerequisites

Your First Backup in 4 Steps

Next: Run an Incremental Backup

Preview Changes with Dry Run

Back Up Cloud Drives

Back up your entire Google Drive

Back up a specific folder

Back up a Shared Drive

Back up your entire OneDrive

Use Cloud Storage Backends

Simplify with Profiles

Alternative: Environment Variables

Common Operations

Automation Tips

What’s Next?