Skip to main content
Create a new backup snapshot from a local filesystem, SFTP server, Google Drive, or OneDrive. Backups are deduplicated, compressed, and encrypted automatically.

​
Usage

cloudstic backup [options]

​
Source Types

Cloudstic supports multiple backup sources:
  • local: Local filesystem directory
  • sftp: Remote directory via SFTP
  • gdrive: Google Drive (full scan)
  • gdrive-changes: Google Drive (incremental via changes API)
  • onedrive: Microsoft OneDrive (full scan)
  • onedrive-changes: Microsoft OneDrive (incremental via delta API)

​
Options

​
-profile
string
Run backup using a named profile from profiles.yaml. The profile’s source, store, auth, tags, and exclude settings are applied automatically. CLI flags override profile values.
​
-all-profiles
boolean
default:"false"
Run backup for all enabled profiles from profiles.yaml. Each profile runs with its own store, source, and auth configuration. Mutually exclusive with -profile.
​
-source
string
default:"gdrive"
Source to backup from. Can also be set via CLOUDSTIC_SOURCE environment variable.For local and SFTP sources, include the path as a URI: local:<path> or sftp://[user@]host[:port]/<path>. For cloud sources, use keywords or keywords with paths: gdrive[://<Drive Name>][/<path>], gdrive-changes[://<Drive Name>][/<path>], onedrive[://<Drive Name>][/<path>], onedrive-changes[://<Drive Name>][/<path>].
​
-auth-ref
string
Use a named auth entry from profiles.yaml for cloud source credentials. Allows reusing OAuth tokens across commands without a full profile.
​
-tag
string
Tag to apply to the snapshot. Can be specified multiple times to add multiple tags.Tags are useful for organizing and filtering snapshots later.
​
-exclude
string
Exclude pattern using gitignore syntax. Can be specified multiple times.Examples: *.log, node_modules/, .git/
​
-exclude-file
string
default:""
Path to a file containing exclude patterns (one per line, gitignore syntax).Patterns from this file are combined with patterns from -exclude flags.
​
-ignore-empty-snapshot
boolean
default:"false"
Skip creating a new snapshot when the resulting tree is identical to the previous snapshot.The backup still scans the source and reports stats, but no new checkpoint is written when nothing changed.
​
-dry-run
boolean
default:"false"
Scan the source and report changes without writing to the repository.Useful for testing exclude patterns or previewing what will be backed up.
​
-volume-uuid
string
default:""
Override the auto-detected volume UUID for local sources. Enables cross-machine incremental backups for portable drives. Can also be set via CLOUDSTIC_VOLUME_UUID environment variable.On macOS and Linux, the GPT partition UUID is detected automatically and is stable across operating systems. Use this flag when auto-detection is unavailable (Windows, MBR-formatted drives) or to manually link backups to a specific snapshot lineage.

​
Global Options

Use -json to emit the command result as a single JSON document on stdout.

​
Examples

cloudstic backup -source local:./documents

​
Output

Successful backup output includes: 
Backup complete. Snapshot: snapshot/a3f8d2..., Root: node/b4e9c1...
Files:  5 new,  2 changed,  120 unmodified,  0 removed
Dirs:   1 new,  0 changed,  15 unmodified,  0 removed
Added to the repository: 2.4 MiB (1.8 MiB compressed)
Processed 142 entries in 8s
Snapshot a3f8d2... saved

​
Incremental Backups

Cloudstic automatically performs incremental backups by comparing against the previous snapshot from the same source. Only new and changed files are uploaded to the repository. For cloud sources (Google Drive, OneDrive), the -changes variants use the provider’s native change tracking APIs for more efficient scans:
  • gdrive-changes uses Google Drive Changes API
  • onedrive-changes uses Microsoft Graph Delta API
The first backup from a source is always a full backup. Subsequent backups from the same source identity are incremental. Identity matching prefers stable IDs (type + identity + path_id) and falls back to legacy matching for older snapshots.
For gdrive-changes and onedrive-changes, enabling -ignore-empty-snapshot means an unchanged run does not persist the fresh change token for that run. The next backup may therefore revisit the same empty delta window.

​
Exclude Patterns

Exclude patterns follow gitignore syntax:
  • * matches any sequence of non-separator characters
  • ** matches any sequence of characters including path separators
  • ? matches any single non-separator character
  • Patterns ending with / only match directories
  • Patterns starting with ! negate the pattern
Create a .cloudsticignore file in your source directory to store exclude patterns, then use -exclude-file .cloudsticignore for cleaner commands.

​
Source Authentication

​
Local and SFTP

For SFTP sources, provide connection details via flags: 
cloudstic backup -source sftp://myuser@server.example.com/remote/path \
  -source-sftp-key ~/.ssh/id_rsa \
  -source-sftp-known-hosts ~/.ssh/known_hosts
FlagDescription
-source-sftp-password <pw>SFTP password
-source-sftp-key <path>Path to private key
-source-sftp-known-hosts <path>Path to known_hosts file
-source-sftp-insecureSkip host key validation (INSECURE)

​
Google Drive

Google Drive sources use OAuth 2.0. On first use, Cloudstic will open a browser for authentication. The access token is cached as google_token.json in your platform config directory. For service account authentication, set GOOGLE_APPLICATION_CREDENTIALS to point to your service account JSON key.

​
OneDrive

OneDrive sources also use OAuth 2.0 with browser-based authentication. The token is cached as onedrive_token.json in your platform config directory. For custom OAuth applications, set ONEDRIVE_CLIENT_ID with your registered app client ID.

​
Performance

Backup performance depends on:
  • Source type: Cloud sources (Drive/OneDrive) are slower than local/SFTP due to API rate limits
  • File size distribution: Many small files take longer to process than fewer large files
  • Network bandwidth: Upload speed to your storage backend
  • Deduplication: Unchanged files are skipped instantly
Use -verbose to see per-file progress. Use -quiet to suppress progress bars and only show the final summary.

​
Error Handling

If the backup fails partway through:
  • The snapshot is NOT saved: the repository remains in a consistent state
  • No partial snapshots are created
  • Data already uploaded (chunks, content) is safely deduplicated on the next run
  • Simply re-run the backup command to retry
backup acquires a shared lock on the repository at run start (skipped for -dry-run). Multiple backups can run concurrently because shared locks coexist. The lock is released when the command exits. If the repository holds an exclusive lock (from a running prune), backup will fail immediately with a lock error. See Repository Locking for details.

​
See Also