Prerequisites Before starting, make sure you have:
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:
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
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:
+-----+---------------------+------------------+--------+---------+-------------+------+ | 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: 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
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:
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-changesgdrive 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-changesonedrive 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_i d > .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:
# 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
See what changed between backups: cloudstic diff abc123def456... def789abc012...
Or compare against the latest: cloudstic diff abc123def456... latest
List all files in a snapshot: cloudstic ls # Or specify a snapshot cloudstic ls abc123def456...
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
After forgetting snapshots, run prune to delete unreferenced chunks: 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
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
