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: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 -source-path ~/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 -source-path ~/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 to a ZIP file: This creates restore.zip in the current directory with all files from the snapshot.
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 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 -source-path ~/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 -source-path ~/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 -root-folder < folder-i d >
Get the folder ID from the URL when viewing the folder in Google Drive: https://drive.google.com/drive/folders/1a2b3c4d5e6f7g8h9... ^^^^^^^^^^^^^^^^^
Back up a Shared Drive cloudstic backup -source gdrive-changes -drive-id < shared-drive-i d >
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 -store-path my-backup-bucket # Create a backup cloudstic backup -store s3 -store-path my-backup-bucket \ -source local -source-path ~/Documents
S3-Compatible Storage (R2, MinIO, Wasabi)
For S3-compatible services, specify a custom endpoint: # Cloudflare R2 cloudstic init -store s3 \ -s3-endpoint https:// < account_i d > .r2.cloudflarestorage.com \ -s3-region auto \ -store-path my-bucket # MinIO cloudstic init -store s3 \ -s3-endpoint https://minio.example.com \ -s3-region us-east-1 \ -store-path my-bucket
# 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 -store-path my-backup-bucket # Create a backup cloudstic backup -store b2 -store-path my-backup-bucket \ -source local -source-path ~/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 \ -store-path /backups/cloudstic \ -sftp-host myserver.com \ -sftp-user backup \ -sftp-key ~/.ssh/id_ed25519 # Create a backup cloudstic backup -store sftp \ -store-path /backups/cloudstic \ -sftp-host myserver.com \ -sftp-user backup \ -sftp-key ~/.ssh/id_ed25519 \ -source local -source-path ~/Documents
SFTP supports password authentication (-sftp-password) or SSH key authentication (-sftp-key). If neither is provided, Cloudstic uses your SSH_AUTH_SOCK agent.
Simplify with Environment Variables Avoid repeating flags by setting defaults in your shell profile:
# Storage configuration export CLOUDSTIC_STORE = s3 export CLOUDSTIC_STORE_PATH = my-backup-bucket export AWS_ACCESS_KEY_ID = your-access-key export AWS_SECRET_ACCESS_KEY = your-secret-key # Encryption export CLOUDSTIC_ENCRYPTION_PASSWORD = "my secure passphrase" # Default source export CLOUDSTIC_SOURCE = local export CLOUDSTIC_SOURCE_PATH =~ / Documents
Now commands become much simpler:
# Just run: cloudstic backup # Instead of: cloudstic backup -store s3 -store-path my-bucket \ -source local -source-path ~/Documents \ -encryption-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 \ -encryption-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?