cloudstic

Cloudstic CLI

Content-addressable, encrypted backup tool for Google Drive, OneDrive, and local files.

Features

• Encrypted by default: AES-256-GCM encryption with password, platform key, or recovery key slots
• Content-addressable storage: Deduplication across sources; identical files stored only once
• Incremental backups: Only changed files are stored
• Multiple sources: Google Drive, Google Drive Changes API, OneDrive, local directories
• Multiple backends: Local filesystem, Amazon S3 (and compatibles like R2, MinIO), or Backblaze B2
• Retention policies: Keep-last, hourly, daily, weekly, monthly, yearly
• Portable drive awareness: Automatically identifies USB drives and external disks by GPT partition UUID — back up the same drive from any machine or mount point, across macOS, Linux, and Windows
• Point-in-time restore: Restore any snapshot, any file, any time

Supported Sources

Google Drive and OneDrive work out of the box. On first run, Cloudstic opens your browser for authorization and caches the token locally. See the User Guide — Sources for details.

Install

brew install cloudstic/tap/cloudstic   # macOS / Linux
winget install Cloudstic.CLI           # Windows
go install github.com/cloudstic/cli/cmd/cloudstic@latest  # with Go

# Curl installer (macOS / Linux)
curl -fsSL https://raw.githubusercontent.com/Cloudstic/cli/main/scripts/install.sh | sh

# Install with shell completion
curl -fsSL https://raw.githubusercontent.com/Cloudstic/cli/main/scripts/install.sh | sh -s -- --with-completion

Or download a binary from Releases. See the User Guide for all options.

Quick Start

# Initialize an encrypted repository (prompts for password interactively)
cloudstic init

# Back up a local directory (prompts for password if not set via flag or env)
cloudstic backup -source local:~/Documents

# Back up Google Drive (opens browser for auth on first run)
cloudstic backup -source gdrive-changes

# Back up a USB drive (auto-detected by partition UUID)
cloudstic backup -source local:/Volumes/MyUSB

# List snapshots
cloudstic list

# Find a file across every snapshot, without knowing which one holds it
cloudstic find "vault.kdbx"

# Restore latest snapshot to a zip file
cloudstic restore

# Preview what a backup would do (dry run)
cloudstic backup -source local:~/Documents -dry-run

# Discover local source candidates and portable drives
cloudstic source discover -portable-only

# Preview a workstation onboarding plan
cloudstic setup workstation -dry-run

# Launch the interactive dashboard for configured profiles
cloudstic tui

Profiles

Save your backup configuration once and reuse it:

# Create a store (interactive — prompts for encryption setup)
cloudstic store new -name my-s3 -uri s3:my-bucket/backups -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

# Or back up all profiles at once
cloudstic backup -all-profiles

See the User Guide — Profiles for details.

When running interactively, Cloudstic prompts for the repository password if no credential is provided via flags or environment variables. For non-interactive use (scripts, cron), pass -password or set CLOUDSTIC_PASSWORD:

cloudstic init -password "my passphrase"
cloudstic backup -source local:~/Documents -password "my passphrase"

Portable Drive Backup

Cloudstic automatically detects when a source path is on a portable drive (USB stick, external SSD, SD card). It identifies the drive by its GPT partition UUID and stores paths relative to the volume root, so backups are consistent regardless of where the drive is mounted or which OS you use.

# On macOS — drive mounts at /Volumes/MyUSB
cloudstic backup -source local:/Volumes/MyUSB

# On Linux — same drive mounts at /mnt/usb
cloudstic backup -source local:/mnt/usb

# Both produce identical snapshots with the same source identity
cloudstic list

This works automatically on GPT-formatted drives (exFAT, APFS, ext4, NTFS). For older MBR-formatted drives, pass -volume-uuid explicitly. See the User Guide for details.

Performance

Benchmarked against Restic, Borg, and Duplicacy on a ~1 GB dataset (local) and a real Google Drive account (~40 MB). Full methodology and numbers in docs/benchmark-results.md.

Local filesystem (time / peak RAM):

Google Drive — each step run stateless (no rclone cache) to reflect real-world cold-start conditions:

Cloudstic uses the Google Drive Changes API natively — incremental backups only fetch what actually changed, no full re-scan required. Restic and Borg rely on rclone FUSE mounts and must re-download the entire dataset to detect changes.

Documentation

Full documentation is available at docs.cloudstic.com.

This repository also contains developer-focused reference docs:

• User Guide: commands, setup, encryption, retention policies
• Source API: source interface, implementations, and how to add a new source
• Specification: object types, backup/restore flow, HAMT structure
• Encryption: key slot design, AES-256-GCM, recovery keys
• Storage Model: content-addressable storage layout
• Contributing: testing, profiling, debugging

Cloud Service

Don't want to manage infrastructure? Cloudstic Cloud handles scheduling, storage, and retention automatically. Same engine, zero ops.

License

MIT