README
¶
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
- Point-in-time restore — Restore any snapshot, any file, any time
Supported Sources
| Source | Flag | Description |
|---|---|---|
| Local directory | -source local |
Back up any local folder |
| Google Drive | -source gdrive |
Full rescan of My Drive or a Shared Drive |
| Google Drive (Changes) | -source gdrive-changes |
Recommended. Fast incremental backup via the Changes API |
| OneDrive | -source onedrive |
Full scan of a Microsoft OneDrive account |
| OneDrive (Changes) | -source onedrive-changes |
Recommended. Fast incremental backup via the Delta API |
Google Drive and OneDrive work out of the box — no API keys or credentials setup needed. 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
Or download a binary from Releases. See the User Guide for all options.
Quick Start
# Initialize an encrypted repository
cloudstic init -encryption-password "my passphrase"
# Back up a local directory
cloudstic backup -source local -source-path ~/Documents -encryption-password "my passphrase"
# Back up Google Drive (opens browser for auth on first run)
cloudstic backup -source gdrive-changes -encryption-password "my passphrase"
# List snapshots
cloudstic list -encryption-password "my passphrase"
# Restore latest snapshot to a zip file
cloudstic restore -encryption-password "my passphrase"
# Preview what a backup would do (dry run)
cloudstic backup -source local -source-path ~/Documents -dry-run
Documentation
- 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
Cloud Service
Don't want to manage infrastructure? Cloudstic Cloud handles scheduling, storage, and retention automatically. Same engine, zero ops.
License
MIT
Documentation
¶
Index ¶
- Variables
- type BackupOption
- type BackupResult
- type Client
- func (c *Client) Backup(ctx context.Context, src store.Source, opts ...BackupOption) (*BackupResult, error)
- func (c *Client) BreakLock(ctx context.Context) ([]*RepoLock, error)
- func (c *Client) Diff(ctx context.Context, snap1, snap2 string, opts ...DiffOption) (*DiffResult, error)
- func (c *Client) Forget(ctx context.Context, snapshotID string, opts ...ForgetOption) (*ForgetResult, error)
- func (c *Client) ForgetPolicy(ctx context.Context, opts ...ForgetOption) (*PolicyResult, error)
- func (c *Client) List(ctx context.Context, opts ...ListOption) (*ListResult, error)
- func (c *Client) LsSnapshot(ctx context.Context, snapshotID string, opts ...LsSnapshotOption) (*LsSnapshotResult, error)
- func (c *Client) Prune(ctx context.Context, opts ...PruneOption) (*PruneResult, error)
- func (c *Client) Restore(ctx context.Context, w io.Writer, snapshotRef string, opts ...RestoreOption) (*RestoreResult, error)
- func (c *Client) Store() store.ObjectStore
- type ClientOption
- type DiffOption
- type DiffResult
- type ForgetOption
- type ForgetResult
- type ListOption
- type ListResult
- type LsSnapshotOption
- type LsSnapshotResult
- type Phase
- type PolicyResult
- type PruneOption
- type PruneResult
- type RepoConfig
- type RepoLock
- type Reporter
- type RestoreOption
- type RestoreResult
Constants ¶
This section is empty.
Variables ¶
View Source
var ( WithVerbose = engine.WithVerbose WithBackupDryRun = engine.WithBackupDryRun WithTags = engine.WithTags WithGenerator = engine.WithGenerator WithMeta = engine.WithMeta )
View Source
var ( WithRestoreDryRun = engine.WithRestoreDryRun WithRestoreVerbose = engine.WithRestoreVerbose )
View Source
var ( WithPruneDryRun = engine.WithPruneDryRun WithPruneVerbose = engine.WithPruneVerbose )
View Source
var ( WithPrune = engine.WithPrune WithDryRun = engine.WithDryRun WithKeepLast = engine.WithKeepLast WithKeepHourly = engine.WithKeepHourly WithKeepDaily = engine.WithKeepDaily WithKeepWeekly = engine.WithKeepWeekly WithKeepMonthly = engine.WithKeepMonthly WithKeepYearly = engine.WithKeepYearly WithGroupBy = engine.WithGroupBy WithFilterTag = engine.WithFilterTag WithFilterSource = engine.WithFilterSource WithFilterAccount = engine.WithFilterAccount WithFilterPath = engine.WithFilterPath )
Functions ¶
This section is empty.
Types ¶
type BackupOption ¶
type BackupOption = engine.BackupOption
type BackupResult ¶ added in v1.2.0
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client is the high-level interface for using Cloudstic as a library.
func NewClient ¶
func NewClient(base store.ObjectStore, opts ...ClientOption) (*Client, error)
func (*Client) Backup ¶
func (c *Client) Backup(ctx context.Context, src store.Source, opts ...BackupOption) (*BackupResult, error)
func (*Client) Diff ¶
func (c *Client) Diff(ctx context.Context, snap1, snap2 string, opts ...DiffOption) (*DiffResult, error)
func (*Client) Forget ¶
func (c *Client) Forget(ctx context.Context, snapshotID string, opts ...ForgetOption) (*ForgetResult, error)
func (*Client) ForgetPolicy ¶
func (c *Client) ForgetPolicy(ctx context.Context, opts ...ForgetOption) (*PolicyResult, error)
func (*Client) List ¶
func (c *Client) List(ctx context.Context, opts ...ListOption) (*ListResult, error)
func (*Client) LsSnapshot ¶
func (c *Client) LsSnapshot(ctx context.Context, snapshotID string, opts ...LsSnapshotOption) (*LsSnapshotResult, error)
func (*Client) Prune ¶
func (c *Client) Prune(ctx context.Context, opts ...PruneOption) (*PruneResult, error)
func (*Client) Restore ¶
func (c *Client) Restore(ctx context.Context, w io.Writer, snapshotRef string, opts ...RestoreOption) (*RestoreResult, error)
Restore writes the snapshot's file tree as a ZIP archive to w. snapshotRef can be "", "latest", a bare hash, or "snapshot/<hash>".
func (*Client) Store ¶ added in v1.1.0
func (c *Client) Store() store.ObjectStore
type ClientOption ¶
type ClientOption func(*Client)
ClientOption configures a Client.
func WithEncryptionKey ¶ added in v1.1.0
func WithEncryptionKey(key []byte) ClientOption
WithEncryptionKey enables AES-256-GCM encryption. Key must be 32 bytes. The HMAC deduplication key is automatically derived from this key.
func WithPackfile ¶ added in v1.4.3
func WithPackfile(enable bool) ClientOption
WithPackfile enables bundling small objects into 8MB packs to save API calls.
func WithReporter ¶
func WithReporter(r Reporter) ClientOption
WithReporter sets the progress reporter for the client.
type DiffOption ¶
type DiffOption = engine.DiffOption
type DiffResult ¶
type DiffResult = engine.DiffResult
type ForgetOption ¶
type ForgetOption = engine.ForgetOption
type ForgetResult ¶ added in v1.2.0
type ForgetResult = engine.ForgetResult
type ListOption ¶
type ListOption = engine.ListOption
type ListResult ¶
type ListResult = engine.ListResult
type LsSnapshotOption ¶
type LsSnapshotOption = engine.LsSnapshotOption
type LsSnapshotResult ¶
type LsSnapshotResult = engine.LsSnapshotResult
type PolicyResult ¶
type PolicyResult = engine.PolicyResult
type PruneOption ¶
type PruneOption = engine.PruneOption
type PruneResult ¶ added in v1.2.0
type PruneResult = engine.PruneResult
type RepoConfig ¶ added in v1.2.0
type RepoConfig = core.RepoConfig
RepoConfig is the repository marker written by "init".
type RestoreOption ¶
type RestoreOption = engine.RestoreOption
type RestoreResult ¶
type RestoreResult = engine.RestoreResult
Source Files
Directories
Click to show internal directories.
Click to hide internal directories.