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

​
-source
string
default:"gdrive"
Source type to backup from. Can also be set via CLOUDSTIC_SOURCE environment variable.Valid values: local, sftp, gdrive, gdrive-changes, onedrive, onedrive-changes
​
-source-path
string
default:"."
Path to the source directory. Required for local and sftp sources. Can also be set via CLOUDSTIC_SOURCE_PATH environment variable.For local sources, this is a filesystem path. For SFTP sources, this is the remote path on the SFTP server.
​
-drive-id
string
default:""
Shared drive ID for Google Drive sources. Omit to use “My Drive”. Can also be set via CLOUDSTIC_DRIVE_ID environment variable.
​
-root-folder
string
default:""
Root folder ID for Google Drive sources. Defaults to the entire drive if not specified. Can also be set via CLOUDSTIC_ROOT_FOLDER environment variable.
​
-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.
​
-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.

​
Global Options

​
Examples

cloudstic backup -source local -source-path ./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 (source type + account + path) will be incremental.

​
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 \
  -source-path /remote/path \
  -source-sftp-host server.example.com \
  -source-sftp-user myuser \
  -source-sftp-key ~/.ssh/id_rsa

​
Google Drive

Google Drive sources use OAuth 2.0. On first use, Cloudstic will open a browser for authentication. The access token is cached in ~/.config/cloudstic/google_token.json. 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 in ~/.config/cloudstic/onedrive_token.json. 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
Do not run multiple backups from the same source simultaneously. Cloudstic uses locks to prevent concurrent writes, but multiple backups from different sources to the same repository are safe.

​
See Also