> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudstic.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Creating Your First Backup
> Complete walkthrough of initializing a repository and creating your first encrypted backup with Cloudstic
This guide walks you through setting up Cloudstic and creating your first encrypted backup, from installation to verification.
In a hurry to back up your whole machine? [`cloudstic setup workstation`](/commands/setup-workstation) is a guided flow that discovers your folders and portable drives and scaffolds profiles for you, as an alternative to the manual steps below.
## Prerequisites
Before you begin, ensure you have:
* Cloudstic CLI installed ([installation instructions](/installation))
* A directory you want to back up
* A storage location (local directory, S3 bucket, B2 bucket, or SFTP server)
## Step 1: Initialize Your Repository
First, create an encrypted repository. Encryption is required by default in Cloudstic.
Decide where to store your backups. For this example, we'll use a local directory, but you can also use S3, B2, or SFTP.
```bash theme={null}
# Local storage (default)
export CLOUDSTIC_STORE=local:~/backups
# Or for S3
# export CLOUDSTIC_STORE=s3:my-backup-bucket
# export AWS_ACCESS_KEY_ID=your-key
# export AWS_SECRET_ACCESS_KEY=your-secret
# Or for Backblaze B2
# export CLOUDSTIC_STORE=b2:my-bucket-name
# export B2_KEY_ID=your-key-id
# export B2_APP_KEY=your-app-key
```
Create the repository with password-based encryption. We strongly recommend also creating a recovery key.
```bash theme={null}
cloudstic init -password "your strong passphrase" -add-recovery-key
```
**Write down your recovery key immediately!** It will only be displayed once. If you lose your password, this 24-word phrase is your only way to recover your backups.
You'll see output like this:
```
╔══════════════════════════════════════════════════════════════╗
║ RECOVERY KEY ║
╠══════════════════════════════════════════════════════════════╣
║ ║
║ word1 word2 word3 ... word24 ║
║ ║
║ Write down these 24 words and store them in a safe place. ║
║ This is the ONLY time the recovery key will be displayed. ║
║ If you lose your password, this key is your only way to ║
║ recover your encrypted backups. ║
║ ║
╚══════════════════════════════════════════════════════════════╝
Repository initialized (encrypted: true).
```
Save your encryption password in a secure location:
* Use a password manager (1Password, Bitwarden, etc.)
* Write down your recovery key phrase on paper and store it in a safe place
* Never commit passwords to version control
For convenience, save your password as an environment variable:
```bash theme={null}
echo 'export CLOUDSTIC_PASSWORD="your passphrase"' >> ~/.bashrc
source ~/.bashrc
```
This way, you won't need to provide `-password` with every command.
## Step 2: Create Your First Backup
Now that your repository is initialized, let's back up a directory.
Start with a simple backup of a local folder:
```bash theme={null}
cloudstic backup -source local:~/Documents
```
You'll see progress output:
```
Scanning source...
Processing files: 1247/1247 [============================] 100%
Uploading chunks: 8532 chunks, 2.3 GiB
Writing snapshot...
Backup complete.
Files: 847 new, 0 changed, 0 unmodified, 0 removed
Dirs: 400 new, 0 changed, 0 unmodified, 0 removed
Raw data: 2.34 GiB
Stored: 2.31 GiB (compressed)
Duration: 1m 34s
```
If you want to skip certain files or directories, use exclude patterns:
```bash theme={null}
cloudstic backup -source local:~/project \
-exclude ".git/" -exclude "node_modules/" -exclude "*.tmp"
```
Or create a `.backupignore` file:
```
# .backupignore
.git/
node_modules/
__pycache__/
*.tmp
*.log
build/
dist/
```
Then reference it:
```bash theme={null}
cloudstic backup -source local:~/project \
-exclude-file ~/project/.backupignore
```
Tags help organize your backups:
```bash theme={null}
cloudstic backup -source local:~/Documents \
-tag daily -tag important
```
Preview what will be backed up without actually writing data:
```bash theme={null}
cloudstic backup -source local:~/Documents -dry-run
```
## Step 3: Verify Your Backup
After creating a backup, verify it was successful.
View all backups in your repository:
```bash theme={null}
cloudstic list
```
Output:
```
+-----+---------------------+------------------+--------+---------+------------+------+
| Seq | Created | Snapshot Hash | Source | Account | Path | Tags |
+-----+---------------------+------------------+--------+---------+------------+------+
| 1 | 2026-03-03 10:30:15 | abc123def456... | local | | /Documents | |
+-----+---------------------+------------------+--------+---------+------------+------+
```
Browse the contents of your backup:
```bash theme={null}
cloudstic ls
```
Or for a specific snapshot:
```bash theme={null}
cloudstic ls abc123def456
```
Run a full integrity check to ensure all data is readable:
```bash theme={null}
cloudstic check
```
Output:
```
Repository check complete.
Snapshots checked: 1
Objects verified: 1247
Errors found: 0
No errors found. Repository is healthy.
```
Run `cloudstic check -read-data` for a deeper verification that re-hashes all chunk data. This takes longer but detects silent corruption.
## Step 4: Create Incremental Backups
Subsequent backups are incremental. Only new or changed files are uploaded.
```bash theme={null}
# Make some changes to your documents
echo "New file" > ~/Documents/new-file.txt
# Run another backup
cloudstic backup -source local:~/Documents
```
Output:
```
Backup complete.
Files: 1 new, 0 changed, 846 unmodified, 0 removed
Dirs: 0 new, 1 changed, 399 unmodified, 0 removed
Raw data: 9 B
Stored: 142 B (compressed + encrypted)
Duration: 3s
```
Cloudstic uses content-addressable storage with deduplication. Identical files across snapshots are stored only once, saving significant space.
## Common Patterns
### Backing Up Multiple Sources
You can back up different sources into the same repository:
```bash Documents theme={null}
cloudstic backup -source local:~/Documents -tag documents
```
```bash Projects theme={null}
cloudstic backup -source local:~/projects -tag code
```
```bash Google Drive theme={null}
cloudstic backup -source gdrive-changes -tag cloud
```
### Using Configuration Files
For complex setups, use environment variables:
```bash ~/.bashrc theme={null}
export CLOUDSTIC_STORE=s3:my-backup-bucket
export CLOUDSTIC_PASSWORD="your passphrase"
export AWS_ACCESS_KEY_ID=your-key
export AWS_SECRET_ACCESS_KEY=your-secret
```
Then commands become simpler:
```bash theme={null}
cloudstic backup -source local:~/Documents
cloudstic list
cloudstic restore
```
## Troubleshooting
### "Repository not initialized" Error
Make sure you've run `cloudstic init` first and are pointing to the correct storage location.
### Authentication Errors
For cloud storage (S3, B2), verify your credentials are set:
```bash theme={null}
# For S3
echo $AWS_ACCESS_KEY_ID
echo $AWS_SECRET_ACCESS_KEY
# For B2
echo $B2_KEY_ID
echo $B2_APP_KEY
```
### Slow First Backup
The first backup is always slower because all files must be uploaded. Subsequent backups are much faster due to incremental processing and deduplication.
## Next Steps
Learn how to automatically manage snapshot lifecycle
Recover files from your backups
Manage passwords and recovery keys
Schedule automatic backups with cron