cloudstic

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 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
cloudstic restore -target ./restored -encryption-password "my passphrase"

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 Client
  • func NewClient(s store.ObjectStore, opts ...ClientOption) *Client
  • func (c *Client) Backup(ctx context.Context, src store.Source, opts ...BackupOption) (*engine.RunResult, 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) (*engine.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) (*engine.PruneResult, error)
  • func (c *Client) Restore(ctx context.Context, targetPath string, snapshotID string, ...) (*RestoreResult, error)
• type ClientOption
  • func WithReporter(r ui.Reporter) ClientOption
• type DiffOption
• type DiffResult
• type ForgetOption
• type ListOption
• type ListResult
• type LsSnapshotOption
• type LsSnapshotResult
• type PolicyResult
• type PruneOption
• type RestoreOption
• type RestoreResult

Variables

var (
	WithVerbose   = engine.WithVerbose
	WithTags      = engine.WithTags
	WithGenerator = engine.WithGenerator
	WithMeta      = engine.WithMeta
)

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
)

Types

type BackupOption

type BackupOption = engine.BackupOption

BackupOption configures a Backup operation (re-exported from engine).

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(s store.ObjectStore, opts ...ClientOption) *Client

NewClient creates a new Cloudstic client with a configured object store.

func (*Client) Backup

func (c *Client) Backup(ctx context.Context, src store.Source, opts ...BackupOption) (*engine.RunResult, error)

Backup runs a backup from src and returns the result.

func (*Client) Diff

func (c *Client) Diff(ctx context.Context, snap1, snap2 string, opts ...DiffOption) (*DiffResult, error)

Diff compares two snapshots.

func (*Client) Forget

func (c *Client) Forget(ctx context.Context, snapshotID string, opts ...ForgetOption) (*engine.ForgetResult, error)

Forget removes a snapshot by ID.

func (*Client) ForgetPolicy

func (c *Client) ForgetPolicy(ctx context.Context, opts ...ForgetOption) (*PolicyResult, error)

ForgetPolicy applies a retention policy and removes snapshots not matched by any keep rule.

func (*Client) List

func (c *Client) List(ctx context.Context, opts ...ListOption) (*ListResult, error)

List returns all snapshots.

func (*Client) LsSnapshot

func (c *Client) LsSnapshot(ctx context.Context, snapshotID string, opts ...LsSnapshotOption) (*LsSnapshotResult, error)

LsSnapshot lists the contents of a snapshot.

func (*Client) Prune

func (c *Client) Prune(ctx context.Context, opts ...PruneOption) (*engine.PruneResult, error)

Prune removes unreferenced data from the store.

func (*Client) Restore

func (c *Client) Restore(ctx context.Context, targetPath string, snapshotID string, opts ...RestoreOption) (*RestoreResult, error)

Restore downloads a snapshot as files into targetPath.

type ClientOption

type ClientOption func(*Client)

ClientOption configures a Client.

func WithReporter

func WithReporter(r ui.Reporter) ClientOption

WithReporter sets the progress reporter for the client.

type DiffOption

type DiffOption = engine.DiffOption

DiffOption configures a Diff operation (re-exported from engine).

type DiffResult

type DiffResult = engine.DiffResult

DiffResult holds the outcome of a diff operation (re-exported from engine).

type ForgetOption

type ForgetOption = engine.ForgetOption

ForgetOption configures a Forget operation (re-exported from engine).

type ListOption

type ListOption = engine.ListOption

ListOption configures a List operation (re-exported from engine).

type ListResult

type ListResult = engine.ListResult

ListResult holds the snapshots returned by a list operation (re-exported from engine).

type LsSnapshotOption

type LsSnapshotOption = engine.LsSnapshotOption

LsSnapshotOption configures a LsSnapshot operation (re-exported from engine).

type LsSnapshotResult

type LsSnapshotResult = engine.LsSnapshotResult

LsSnapshotResult holds the data returned by an ls-snapshot operation (re-exported from engine).

type PolicyResult

type PolicyResult = engine.PolicyResult

type PruneOption

type PruneOption = engine.PruneOption

PruneOption configures a Prune operation (re-exported from engine).

type RestoreOption

type RestoreOption = engine.RestoreOption

RestoreOption configures a Restore operation (re-exported from engine).

type RestoreResult

type RestoreResult = engine.RestoreResult

RestoreResult holds the outcome of a restore operation (re-exported from engine).