Skip to content

user-guide.md

Latest commit

 

History

History
1815 lines (1257 loc) · 64.1 KB

user-guide.md

File metadata and controls

1815 lines (1257 loc) · 64.1 KB

Cloudstic CLI User Guide

Cloudstic is a content-addressable backup tool that creates encrypted, deduplicated snapshots of your files — from local directories, SFTP servers, Google Drive, or OneDrive — and stores them locally, on Amazon S3, Backblaze B2, or a remote SFTP server.

Full documentation (with guides, examples, and API reference) is available at docs.cloudstic.com.

Table of Contents

Quick Start

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

# 2. Back up a local directory (prompts for password)
cloudstic backup -source local:~/Documents

# 3. List snapshots
cloudstic list

# 4. Restore the latest snapshot
cloudstic restore

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

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

Installation

Homebrew (macOS / Linux)

# Install
brew install cloudstic/tap/cloudstic

# Upgrade to the latest version
brew upgrade cloudstic

# Uninstall
brew uninstall cloudstic

Winget (Windows)

# Install
winget install Cloudstic.CLI

# Upgrade to the latest version
winget upgrade Cloudstic.CLI

# Uninstall
winget uninstall Cloudstic.CLI

Curl installer (macOS / Linux)

# Install latest
curl -fsSL https://raw.githubusercontent.com/Cloudstic/cli/main/scripts/install.sh | sh

# Install a specific version
curl -fsSL https://raw.githubusercontent.com/Cloudstic/cli/main/scripts/install.sh | sh -s -- --version v1.2.3

# Install to a user-writable directory
curl -fsSL https://raw.githubusercontent.com/Cloudstic/cli/main/scripts/install.sh | sh -s -- --install-dir "$HOME/.local/bin"

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

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

# Skip checksum verification (not recommended)
curl -fsSL https://raw.githubusercontent.com/Cloudstic/cli/main/scripts/install.sh | sh -s -- --no-verify

The installer verifies release checksums by default. --no-verify is available for constrained/debug environments but is not recommended. Completion files are written to user directories (for example ~/.zfunc for zsh, ~/.config/fish/completions for fish, and ~/.local/share/bash-completion/completions for bash).

Pre-built binaries

Download the latest release for your platform from the GitHub Releases page. Binaries are available for macOS (Intel & Apple Silicon), Linux (amd64 & arm64), and Windows.

Prefer the curl installer above when possible; it verifies checksums automatically.

# Example: macOS Apple Silicon
VERSION=$(curl -fsSL https://api.github.com/repos/cloudstic/cli/releases/latest | awk -F '"' '/tag_name/{gsub(/^v/,"",$4); print $4; exit}')
ASSET="cloudstic_${VERSION}_darwin_arm64.tar.gz"
curl -fsSL "https://github.com/cloudstic/cli/releases/latest/download/${ASSET}" -o "${ASSET}"
curl -fsSL https://github.com/cloudstic/cli/releases/latest/download/checksums.txt -o checksums.txt
grep " ${ASSET}$" checksums.txt | shasum -a 256 -c -
tar -xzf "${ASSET}"
mv cloudstic /usr/local/bin/

Install with Go

go install github.com/cloudstic/cli/cmd/cloudstic@latest

Build from source

Requires Go 1.26+:

git clone https://github.com/cloudstic/cli.git
cd cli
go build -o cloudstic ./cmd/cloudstic
mv cloudstic /usr/local/bin/

Verify

cloudstic version

Concepts

Repository — A storage location (local directory or B2 bucket) that holds your backups. Created with cloudstic init.

Snapshot — A point-in-time record of all files from a source. Each backup creates a new snapshot. Snapshots are identified by a SHA-256 hash.

Source — Where files are read from during backup: a local directory, an SFTP server, Google Drive, or OneDrive.

Content-addressable storage — Files are split into chunks and stored by their content hash. Identical chunks across files or snapshots are stored only once (deduplication).

Key slots — Encryption keys are wrapped in "slots", each accessible via a different credential (password, platform key, or recovery key). All slots unlock the same master key.

Configuration

Config directory

Cloudstic stores OAuth tokens and other state files in a platform-specific config directory:

Platform Default path
Linux ~/.config/cloudstic/
macOS ~/Library/Application Support/cloudstic/
Windows %AppData%\cloudstic\

Override with the CLOUDSTIC_CONFIG_DIR environment variable.

Setting defaults with environment variables

Most flags can be set via environment variables to avoid repeating them. For example:

export CLOUDSTIC_STORE=s3:my-backup-bucket
export CLOUDSTIC_PASSWORD="my secret passphrase"
export AWS_ACCESS_KEY_ID=your-access-key
export AWS_SECRET_ACCESS_KEY=your-secret-key

# Now commands are much shorter:
cloudstic backup -source local:~/Documents
cloudstic list
cloudstic restore

See Environment Variables for the full list.

Commands

Global flags

These flags apply to all commands:

Flag Description
-verbose Log detailed file-level operations (files scanned, written, deleted)
-quiet Suppress progress bars (keeps final summary output)
-json Write the command result as JSON to stdout
-debug Log every store request (network calls, timing, sizes)
-disable-packfile Disable bundling small objects into 8MB packs (packfile is on by default) — env: CLOUDSTIC_DISABLE_PACKFILE=1

-verbose and -quiet are mutually exclusive. If both are set, -quiet takes precedence.

-json is available on the operational commands that return structured results, including init, backup, restore, list, ls, diff, forget, prune, break-lock, check, key list, key add-recovery, key passwd, and cat. When -json is set, Cloudstic suppresses progress output and writes a single JSON document to stdout instead of the usual human-readable summary.

init

Initialize a new repository. Encryption is required by default.

# Interactive — prompts for password (recommended for personal use)
cloudstic init

# Interactive with a recovery key (strongly recommended)
cloudstic init -add-recovery-key

# Non-interactive — password provided via flag
cloudstic init -password "my secret passphrase"

# Non-interactive with a recovery key
cloudstic init -password "my secret passphrase" -add-recovery-key

# Platform key encryption (for automation)
cloudstic init -encryption-key <64-hex-chars>

# Both password and platform key (dual access)
cloudstic init -password "passphrase" -encryption-key <hex>

# Unencrypted (must be explicit — not recommended)
cloudstic init -no-encryption

When no encryption credential is provided and stdin is a terminal, init prompts for a new password with confirmation. In non-interactive environments (piped input, cron jobs), you must pass -password, -encryption-key, or -no-encryption explicitly.

If you are using a platform key or KMS but also want to protect the repository with a password, use -prompt to trigger an interactive password prompt alongside other credentials:

cloudstic init -encryption-key <hex> -prompt

Flags:

Flag Description
-password <value> Password for password-based encryption (non-interactive)
-prompt Prompt for password interactively (use alongside -encryption-key or -kms-key-arn to add a password layer)
-encryption-key Platform key (64 hex chars = 32 bytes)
-add-recovery-key Generate a 24-word recovery key during init
-no-encryption Create an unencrypted repository (not recommended)
-adopt-slots Adopt existing key slots (and add new credentials to them)

When -add-recovery-key is used, a 24-word seed phrase is displayed once. Write it down and store it safely — it's your last resort if you lose your password.

backup

Create a new snapshot from a source.

# Back up a local directory
cloudstic backup -source local:~/Documents

# Back up Google Drive (My Drive)
cloudstic backup -source gdrive

# Back up a specific Google Drive shared drive and folder
cloudstic backup -source "gdrive://Company Data/path/to/folder"

# Back up with tags
cloudstic backup -source local:~/Documents -tag daily -tag important

# Verbose output (shows individual files)
cloudstic backup -source local:~/Documents -verbose

# Dry run — see what would change without writing to the store
cloudstic backup -source local:~/Documents -dry-run

Flags:

Flag Default Description
-source gdrive Source type: local:<path>, sftp://[user@]host[:port]/<path>, gdrive[://<Drive Name>][/<path>], gdrive-changes[://<Drive Name>][/<path>], onedrive[://<Drive Name>][/<path>], onedrive-changes[://<Drive Name>][/<path>]
-profile Run backup using one named profile from profiles.yaml
-all-profiles false Run backup for all enabled profiles from profiles.yaml
-auth-ref Use one named auth entry from profiles.yaml for cloud source credentials
-profiles-file <config-dir>/profiles.yaml Override profile YAML location (also CLOUDSTIC_PROFILES_FILE)
-tag Tag to apply to the snapshot (repeatable)
-exclude Exclude pattern using gitignore syntax (repeatable)
-exclude-file Path to file containing exclude patterns, one per line
-ignore-empty-snapshot false Skip creating a new snapshot when the resulting tree is identical to the previous one
-volume-uuid Override volume UUID for local source (enables cross-machine incremental backup for portable drives)
-skip-mode Skip POSIX metadata collection (mode, uid, gid, btime, flags)
-skip-flags Skip file flags collection
-skip-xattrs Skip extended attribute collection
-xattr-namespaces Comma-separated xattr namespace prefixes to collect (e.g. user.,com.apple.)
-dry-run false Scan source and report changes without writing to the store

-profile and -all-profiles are mutually exclusive.

-auth-ref can be used with direct backup -source ... runs (outside profile mode) to reuse a cloud auth entry from profiles.yaml.

If you run a cloud backup without -auth-ref, Cloudstic automatically records a provider default auth entry in profiles.yaml so it is discoverable later:

  • Google sources -> google-default
  • OneDrive sources -> onedrive-default

The gdrive-changes and onedrive-changes source types use their respective change/delta APIs for faster incremental backups after the first full backup.

When -ignore-empty-snapshot is enabled, Cloudstic still scans the source and reports stats, but it does not write a new snapshot if the resulting tree is unchanged. For changes-based cloud sources, this also means an unchanged run does not persist a fresh change token, so the next run may revisit the same empty delta window.

Cloudstic tracks source lineage using stable source identities internally (container identity + root location identity), not just display labels. For cloud sources, this uses stable drive/folder IDs so incremental continuity is preserved across folder renames or moves.

Locking: backup acquires a shared lock on the repository at the start of the run (skipped for -dry-run). Multiple backups can run concurrently. The lock is released when the command exits. If the repository is exclusively locked by a prune run, backup will fail immediately with an error message. Use break-lock if a lock is stale.

Exclude patterns

You can exclude files and directories from the backup using gitignore-style patterns. This works with all source types — local, SFTP, Google Drive, and OneDrive. This is essential for skipping development directories that contain .git/, node_modules/, build artifacts, etc.

# Exclude specific directories and file types
cloudstic backup -source local:~/project \
  -exclude ".git/" -exclude "node_modules/" -exclude "*.tmp" -exclude "*.log"

# Works with cloud sources too
cloudstic backup -source gdrive-changes -exclude "node_modules/" -exclude "*.tmp"

# Load patterns from a file
cloudstic backup -source local:~/project -exclude-file ~/project/.backupignore

# Combine both
cloudstic backup -source local:~/project \
  -exclude "build/" -exclude-file .backupignore

Supported pattern syntax:

Pattern Meaning
*.tmp Exclude all .tmp files in any directory
.git/ Exclude the .git directory (trailing / = directories only)
node_modules/ Exclude node_modules directories anywhere in the tree
**/*.log Exclude all .log files at any depth
build/output Exclude build/output anchored at root (patterns with / are anchored)
!important.log Re-include important.log even if a previous pattern excluded *.log
# comment Lines starting with # are comments (ignored)

Exclude file format (-exclude-file):

# Development artifacts
.git/
node_modules/
__pycache__/

# Build output
build/
dist/
*.o

# Temporary files
*.tmp
*.swp
*~

# But keep this one
!important.tmp

Patterns are evaluated in order; the last matching rule wins. This allows negation (!) to override earlier excludes.

For cloud sources (Google Drive, OneDrive), exclude patterns are matched against the full path of each file as it appears in the drive (e.g. Documents/Reports/draft.docx).

Automatic rescan when exclude patterns change

When using incremental sources (gdrive-changes, onedrive-changes), Cloudstic stores a hash of the active exclude patterns in each snapshot. If the patterns change between runs (added, removed, or reordered), the next backup automatically performs a full rescan instead of an incremental one. This ensures the new patterns are applied comprehensively. The full rescan also captures a fresh change token, so subsequent runs resume incremental mode from that point.

No manual intervention is required — just update your -exclude / -exclude-file flags and run the backup as usual.

profile

Manage backup profiles stored in YAML.

Profiles are stored by default at <config-dir>/profiles.yaml.

profile list

List configured stores, auth entries, and profiles.

cloudstic profile list

# Custom file location
cloudstic profile list -profiles-file ./profiles.yaml

If the profiles file does not exist yet, profile list exits successfully with no output.

profile show

Show one profile with resolved store and auth references.

cloudstic profile show work-drive

# Custom file location
cloudstic profile show -profiles-file ./profiles.yaml work-drive

profile new

Create or update one profile entry.

# Create profile and create/update referenced store entry
cloudstic profile new \
  -name google-drive \
  -source gdrive-changes \
  -store-ref home-s3 \
  -store s3:my-bucket/cloudstic

# Reuse an existing store reference (no -store needed)
cloudstic profile new \
  -name documents \
  -source local:~/Documents \
  -store-ref home-s3

# Create auth entry first, then attach it to a profile
cloudstic auth new \
  -name google-work \
  -provider google \
  -google-token-file ~/.config/cloudstic/tokens/google-work.json

cloudstic profile new \
  -name work-drive \
  -source "gdrive-changes:/Team Folder" \
  -auth-ref google-work

# Create a profile and define store encryption with secret refs
cloudstic profile new \
  -name photos \
  -source local:~/Pictures \
  -store-ref home-s3 \
  -store s3:my-bucket/cloudstic

Important: profile new requires explicit -name and -source.

If these required flags are omitted and you are in an interactive terminal, Cloudstic prompts for the missing values.

It intentionally does not read CLOUDSTIC_SOURCE for these required fields, to avoid accidentally persisting environment-specific defaults into profiles.yaml.

Use --no-prompt to disable all interactive prompts. Missing required fields will cause an error instead.

Use -store-ref by itself to reference an existing store entry. Add -store with -store-ref to create or update that store entry in the same command.

When profile new creates a new store in interactive mode, it reuses the same encryption setup flow as store new (including secret reference prompts).

Use -auth-ref to reference reusable cloud OAuth settings under top-level auth: in profiles.yaml.

-auth-ref must point to an existing auth entry.

You can also use -auth-ref directly with backup when not using -profile:

cloudstic backup \
  -source "gdrive-changes:/Team Folder" \
  -auth-ref google-work

profile new validates that -auth-ref points to an existing auth entry and that provider matches the source type.

-auth-ref is only valid for cloud sources.

source

Inspect local source candidates for workstation onboarding.

source discover

List local source roots with mount metadata and portable-drive hints.

cloudstic source discover

# Only show portable/external candidates
cloudstic source discover -portable-only

# JSON output for automation
cloudstic source discover -json

This command is intended to support workstation onboarding and source selection flows. It emits candidate local: source URIs together with mount metadata such as identity, filesystem type, and whether the source is considered portable.

setup

Guide workstation onboarding and profile scaffolding.

setup workstation

Interactive onboarding flow:

cloudstic setup workstation

Accept the proposed plan without confirmation:

cloudstic setup workstation -yes -store-ref my-s3

Preview only:

cloudstic setup workstation -dry-run

Attach an existing store to the generated profile drafts:

cloudstic setup workstation -dry-run -store-ref my-s3

Write the onboarding plan as JSON:

cloudstic setup workstation -dry-run -json

The preview uses OS-aware local folder suggestions and portable-drive discovery to generate a review-first profile plan. The command is interactive by default. Use -dry-run for a side-effect-free preview or -yes to accept the proposed plan without a confirmation prompt.

tui

Launch the interactive terminal dashboard for configured profiles.

# Launch the dashboard
cloudstic tui

# Use a specific profiles file
cloudstic tui -profiles-file ~/.config/cloudstic/profiles.yaml

The TUI is intended for interactive operator workflows. It shows:

  • configured profiles and their current readiness
  • the selected profile's source, store, auth, and latest backup metadata
  • recent activity for in-TUI actions

Current controls:

  • ↑ / ↓ or j / k: move selection
  • b: run backup for the selected profile, or init if its store is not initialized
  • c: run check for the selected profile's repository
  • q: quit

cloudstic tui requires an interactive terminal. It is not intended for scripts or CI.

store

Manage named store entries in profiles.yaml. Stores define storage backend, connection credentials, and encryption settings.

store list

List configured stores.

cloudstic store list

store show

Show details for a named store.

cloudstic store show prod-s3

store verify

Resolve credentials for one named store and verify connectivity/unlock behavior.

cloudstic store verify prod-s3

store verify is a configuration/access check (credentials, backend connectivity, and encrypted repo unlock). It is different from cloudstic check, which verifies repository data integrity.

store init

Initialize a configured store by reference from profiles.yaml.

cloudstic store init prod-s3

# Non-interactive (skip confirmation prompt)
cloudstic store init -yes prod-s3

Use this when a store was created/configured earlier but repository initialization was skipped or failed.

store new

Create or update a named store entry in profiles.yaml. Stores define storage backend, connection credentials, and encryption settings.

cloudstic store new \
  -name prod-s3 \
  -uri s3:my-bucket/backups \
  -s3-region eu-west-1

Store names must start with a letter or digit and contain only letters, digits, dots, hyphens, or underscores. URIs must use a supported scheme (local, s3, b2, sftp).

In interactive mode, store new prompts for:

  • Missing required fields (name, URI)
  • For existing stores (when no override flags are passed):
    • Store URI with current value prefilled
    • Keep current encryption settings? [Y/n]
  • Encryption configuration (if no encryption flags provided):
    1. Password — saves a secret reference (default: env://CLOUDSTIC_PASSWORD)
    2. Platform key — saves a secret reference (default: env://CLOUDSTIC_ENCRYPTION_KEY)
    3. AWS KMS key — saves ARN and region
    4. No encryption
  • Store initialization (if the store is accessible but not yet initialized)

Prefer *_secret fields and secret refs in profiles.yaml. Supported schemes:

  • env://VAR_NAME
  • keychain://service/account (macOS)
  • wincred://target (Windows)
  • secret-service://collection/item (Linux)

Use *_secret fields for all secret-backed profile settings.

Examples:

stores:
  prod:
    uri: s3:my-bucket/cloudstic
    s3_access_key_secret: env://AWS_ACCESS_KEY_ID
    s3_secret_key_secret: keychain://cloudstic/prod/s3-secret-key
    password_secret: keychain://cloudstic/prod/repo-password

If native secret backends are unavailable (for example headless sessions without desktop keyring/keychain access), use env://... references.

Use --no-prompt to disable all interactive prompts (for scripts/CI).

auth

Manage reusable cloud OAuth entries in profiles.yaml.

auth new

Create or update an auth entry.

# Google auth entry
cloudstic auth new \
  -name google-work \
  -provider google \
  -google-token-file ~/.config/cloudstic/tokens/google-work.json

# OneDrive auth entry
cloudstic auth new \
  -name ms-personal \
  -provider onedrive \
  -onedrive-token-file ~/.config/cloudstic/tokens/ms-personal.json

If token storage flags are omitted, Cloudstic defaults to a managed encrypted reference under config-token://<provider>/<auth-name>.

If required flags are omitted and you are in an interactive terminal, auth new prompts for missing values.

Secret References and Secure Storage

Cloudstic uses Secret References to avoid storing sensitive credentials like OAuth tokens or service account JSON in plaintext within your profiles.yaml.

When creating an auth entry, you can specify a reference instead of a raw file path:

# Store Google token in macOS Keychain (secure)
cloudstic auth new -name google-work -provider google \
  -google-token-ref keychain://cloudstic/auth/google-work

# Store Google token in an encrypted local file (managed by Cloudstic)
cloudstic auth new -name google-work -provider google \
  -google-token-ref config-token://google/google-work

# Use a raw file (e.g. for Kubernetes mounted secrets)
cloudstic auth new -name google-work -provider google \
  -google-token-ref file:///etc/secrets/google-token.json

Supported Schemes:

Scheme Description Use Case
keychain:// macOS Keychain blob storage Personal macOS workstations
wincred:// Windows Credential Manager secret storage Personal Windows workstations
secret-service:// Linux Secret Service secret storage Linux desktops with a keyring
config-token:// Encrypted local file Headless servers, Linux desktops
file:// Raw local file CI/CD, Kubernetes, Docker

For config-token://, Cloudstic automatically encrypts the token at rest using a key derived from your machine ID and user ID. See the Encryption Design for more details.

auth login

Trigger OAuth login for an auth entry and save the token in its configured token storage.

cloudstic auth login -name google-work

This is useful to pre-authorize before first backup.

auth list / auth show

cloudstic auth list
cloudstic auth show google-work

auth list exits successfully with no output when the profiles file does not exist yet.

restore

Restore a snapshot either as a ZIP archive (-format zip) or directly to a directory (-format dir). By default, the format is inferred from -output. If -output ends with .zip, Cloudstic uses ZIP format; otherwise it restores to a directory.

In directory mode, Cloudstic creates parent directories automatically and, on macOS and Linux, replays captured metadata on a best-effort basis (for example mode bits, ownership, modification times, xattrs, and file flags where the destination filesystem supports them). Existing files are skipped with warnings instead of being overwritten, so rerunning the same restore into the same output directory is safe.

# Restore the latest snapshot
cloudstic restore

# Restore a specific snapshot
cloudstic restore <snapshot-hash>

# Restore to a custom output path
cloudstic restore <snapshot-hash> -output ./my-backup.zip

# Restore directly to a directory
cloudstic restore <snapshot-hash> -format dir -output ./restored

# Restore a single file
cloudstic restore <snapshot-hash> -path Documents/report.pdf

# Restore a subtree (trailing slash)
cloudstic restore <snapshot-hash> -path Documents/

# Dry run — see what would be restored without writing output
cloudstic restore -dry-run

Flags:

Flag Default Description
-output ./restore.zip Output path (ZIP file for zip, directory for dir)
-format auto Restore format: zip or dir (auto-detected from -output when omitted)
-path Restore only the given file or subtree. Use a trailing / to select an entire directory (e.g. Documents/). Without a trailing slash, the exact file path is matched (e.g. Documents/report.pdf).
-dry-run false Show what would be restored without writing output

The snapshot ID is a positional argument (defaults to latest if omitted).

Locking: restore always acquires a shared lock at the start of the run (including -dry-run). The lock is released when the command exits.

list

List all snapshots in the repository.

cloudstic list

Outputs a table with sequence number, creation time, snapshot hash, source info, and tags.

ls

List the file tree within a specific snapshot.

# List files in the latest snapshot
cloudstic ls

# List files in a specific snapshot
cloudstic ls <snapshot-hash>

diff

Compare two snapshots to see what changed.

# Compare two specific snapshots
cloudstic diff <snapshot-hash-1> <snapshot-hash-2>

# Compare a snapshot against the latest
cloudstic diff <snapshot-hash> latest

Shows added, modified, and removed files between the two snapshots.

forget

Remove snapshots from the repository. This deletes the snapshot metadata but does not reclaim storage — run prune afterwards (or use -prune).

# Forget a single snapshot
cloudstic forget <snapshot-hash>

# Forget and immediately prune
cloudstic forget <snapshot-hash> -prune

# Apply a retention policy
cloudstic forget -keep-last 7 -keep-daily 30 -keep-monthly 12

# Dry run — show what would be removed without actually removing
cloudstic forget -keep-last 7 -keep-daily 30 -dry-run

# Filter by tag before applying policy
cloudstic forget -keep-last 3 -tag daily

# Filter by source
cloudstic forget -keep-last 5 -source gdrive -account user@gmail.com

Retention policy flags:

Flag Description
-keep-last N Keep the N most recent snapshots
-keep-hourly N Keep N hourly snapshots
-keep-daily N Keep N daily snapshots
-keep-weekly N Keep N weekly snapshots
-keep-monthly N Keep N monthly snapshots
-keep-yearly N Keep N yearly snapshots

Filter flags:

Flag Description
-tag Filter by tag (repeatable)
-source Filter by source URI (e.g., local:/path, gdrive, sftp://host/path)
-account Filter by account
-group-by Group snapshots by fields (default: source,account,path)

Other flags:

Flag Description
-prune Run prune immediately after forgetting
-dry-run Show what would be removed without acting

prune

Remove unreachable data chunks that are no longer referenced by any snapshot. Run this after forget to reclaim storage.

cloudstic prune

# Dry run — see what would be deleted without deleting
cloudstic prune -dry-run

# Verbose output — see each deleted key
cloudstic prune -verbose

Flags:

Flag Default Description
-dry-run false Show what would be deleted without deleting

Locking: prune acquires an exclusive lock at the start of the run (skipped for -dry-run). While the exclusive lock is held, all backup and restore commands will fail immediately. The lock is released when prune exits. If prune crashes, the lock expires automatically after 1 minute. Use break-lock to remove it sooner.

break-lock

Force-remove a stale repository lock left behind by a crashed or interrupted process. Only use this when you are certain no backup, restore, or prune is actively running against the repository.

cloudstic break-lock

If no lock is present, the command reports that and exits cleanly. If one or more locks are found, each is removed and its metadata is printed:

Locks removed:
  Operation:  backup
  Holder:     mac-studio.local (pid 12345)
  Acquired:   2026-03-07T09:00:00Z
  Expired at: 2026-03-07T09:01:00Z
  Shared:     true

When to use break-lock:

  • A prune, backup, or restore run was killed and you see "repository is locked" on the next attempt.
  • The lock TTL has already passed (locks expire automatically after 1 minute) but you don't want to wait.
  • You are certain the holder process is no longer running.

Do not use break-lock if the locking operation is still in progress — removing the lock while prune is running can leave the repository in an inconsistent state.

check

Verify the integrity of a repository by walking the full reference chain and checking that every referenced object exists, can be read, decrypts successfully, and decompresses correctly.

# Check all snapshots (structure verification)
cloudstic check

# Full byte-level verification (re-hash all chunk data)
cloudstic check -read-data

# Check a specific snapshot
cloudstic check <snapshot-hash>
cloudstic check latest

# Verbose output — log each verified object
cloudstic check -verbose

What it verifies:

  1. Reference chain — index/latest → snapshot → HAMT nodes → filemeta → content → chunk
  2. Object readability — Every referenced object exists, decrypts, and decompresses without error
  3. Data integrity (with -read-data) — Re-hashes chunk data and verifies it matches the content-addressed key

Flags:

Flag Default Description
-read-data false Re-hash all chunk data for full byte-level verification
-snapshot (all) Check a specific snapshot instead of all

The snapshot can also be passed as a positional argument.

Output:

On success, the command prints a summary and exits with code 0:

Repository check complete.
  Snapshots checked:  3
  Objects verified:   1247
  Errors found:       0

No errors found — repository is healthy.

If errors are found, they are listed and the command exits with code 1:

Repository check complete.
  Snapshots checked:  3
  Objects verified:   1244
  Errors found:       3

  [missing] chunk/abc123...: chunk not found or unreadable: ...
  [corrupt] chunk/def456...: hash mismatch: expected def456..., got 789abc...
  [missing] content/ghi789...: content object not found or unreadable: ...

Tip: Run cloudstic check periodically (e.g. via cron) to catch silent corruption early. Use -read-data for thorough verification at the cost of reading all data from the backend.

key list

List all encryption key slots present in the repository. This lets you see which credential types are configured (password, platform, kms-platform, recovery).

cloudstic key list

Example output:

+──────────────+─────────+──────────+
| TYPE         | LABEL   | KDF      |
+──────────────+─────────+──────────+
| password     | default | argon2id |
| recovery     | default | —        |
+──────────────+─────────+──────────+

2 key slot(s) found.

Note: key list does not require the encryption key — slot metadata is stored unencrypted.

key add-recovery

Generate a 24-word recovery key for an existing encrypted repository. Requires your current encryption credential to unlock the master key.

# Interactive — prompts for current password
cloudstic key add-recovery

# Non-interactive
cloudstic key add-recovery -password "my secret passphrase"

# For KMS-managed repositories
cloudstic key add-recovery -kms-key-arn arn:aws:kms:us-east-1:123:key/abc

The recovery key is displayed once. Write it down immediately.

The legacy add-recovery-key command is still accepted but deprecated.

key passwd

Change (or add) the repository password. You must provide your current credentials to unlock the master key.

# Interactive — prompts for current and new password
cloudstic key passwd

# Non-interactive
cloudstic key passwd -password "old passphrase" -new-password "new passphrase"

# Unlock with platform key, set a password
cloudstic key passwd -encryption-key <hex> -new-password "my passphrase"

Flags:

Flag Description
-new-password New password (prompted interactively if not set)

cat

Display the raw JSON content of repository objects. This is useful for debugging, inspection, and understanding the internal structure of backups.

# Display repository configuration
cloudstic cat config

# Display the latest snapshot index
cloudstic cat index/latest

# Display a specific snapshot
cloudstic cat snapshot/abc123def456...

# Display multiple objects at once
cloudstic cat config index/latest

# Display a filemeta object
cloudstic cat filemeta/789abc...

# Display a HAMT node
cloudstic cat node/def456...

# Emit a machine-readable JSON result
cloudstic cat config -json

# Output raw, unformatted data for hashing
cloudstic cat -raw filemeta/789abc... | sha256sum

Object key types:

Key pattern Description
config Repository configuration (version, encryption status, creation time)
index/latest Pointer to the most recent snapshot
index/snapshots Snapshot catalog (lightweight summaries for fast listing)
snapshot/<hash> Snapshot metadata (creation time, root node, source info, tags)
filemeta/<hash> File metadata (name, size, modification time, content hash)
content/<hash> Content manifest (list of chunk references or inline data)
node/<hash> HAMT tree node (internal or leaf)
chunk/<hash> Raw file data chunk
keys/<slot> Encryption key slot (stored unencrypted)

Flags:

Flag Description
-json Write a JSON array of fetched objects to stdout
-raw Output raw, unformatted data (useful for hashing)

The output is pretty-printed object content by default. With -json, Cloudstic returns a single JSON array where each item includes the object key and decoded data. Use -raw when you need the exact stored bytes instead of a structured JSON document.

Examples:

# Pretty-print repository config
cloudstic cat config

# Extract version from config using jq
cloudstic cat config --json | jq -r .version

# List all snapshots from index
cloudstic list --json | jq -r '.[] | .ref'

# Inspect a specific snapshot's metadata
cloudstic cat snapshot/abc123... | jq .

# Verify the integrity of a filemeta object
cloudstic cat -raw filemeta/abc123... | sha256sum

Note: This command operates at the object store level and returns the raw JSON representation of repository objects. It does not reconstruct file contents — use restore for that.

completion

Generate shell completion scripts for bash, zsh, or fish.

cloudstic completion bash
cloudstic completion zsh
cloudstic completion fish

See Shell Completions below for setup instructions.

Shell Completions

Cloudstic can generate tab-completion scripts for popular shells. Once set up, pressing Tab will complete commands, flags, and flag values (like -store local:<path>|s3:<bucket>|b2:<bucket>|sftp://... and -source local:<path>|sftp://[user@]host/<path>|gdrive|...).

Bash

# Load for current session
source <(cloudstic completion bash)

# Load permanently (add to ~/.bashrc)
echo 'source <(cloudstic completion bash)' >> ~/.bashrc

Note: Bash completions require the bash-completion package. Install it via your package manager if not already present (brew install bash-completion on macOS, apt install bash-completion on Debian/Ubuntu).

Zsh

# Load for current session
source <(cloudstic completion zsh)

# Load permanently (add to ~/.zshrc)
echo 'source <(cloudstic completion zsh)' >> ~/.zshrc

Alternatively, place the output in your $fpath:

cloudstic completion zsh > "${fpath[1]}/_cloudstic"

Note: You may need to start a new shell or run compinit for changes to take effect.

Fish

# Load for current session
cloudstic completion fish | source

# Load permanently
cloudstic completion fish > ~/.config/fish/completions/cloudstic.fish

Sources

A source is where Cloudstic reads files from during a backup. Each source type connects to a different storage provider and walks its file tree to detect new, changed, or deleted files.

Source overview

Source -source flag What it backs up Auth
Local directory local Files on your local filesystem None
SFTP sftp Files on a remote SFTP server Password, SSH key, or ssh-agent
Google Drive gdrive Full scan of Google Drive (My Drive or Shared Drive) Automatic (browser)
Google Drive (Incremental) gdrive-changes Incremental changes since last backup (recommended for Google Drive) Automatic (browser)
OneDrive onedrive Full scan of Microsoft OneDrive Automatic (browser)
OneDrive (Incremental) onedrive-changes Incremental changes since last backup (recommended for OneDrive) Automatic (browser)

All sources produce the same snapshot format. You can back up different sources into the same repository, and snapshots are tagged with source metadata so retention policies can be applied per-source.

Local Directory

Back up files from a local filesystem path. No authentication or environment variables required. Specify the path as part of the source URI: -source local:<path>.

cloudstic backup -source local:/path/to/directory

# Skip common development directories
cloudstic backup -source local:~/project \
  -exclude ".git/" -exclude "node_modules/" -exclude "*.tmp"

# Use an exclude file
cloudstic backup -source local:~/project -exclude-file .backupignore
Flag Default Description
-exclude Exclude pattern, gitignore syntax (repeatable)
-exclude-file File containing exclude patterns (one per line)
-volume-uuid Override volume UUID (see Portable drives)
-skip-mode Skip POSIX metadata collection (mode, uid, gid, btime, flags)
-skip-flags Skip file flags collection
-skip-xattrs Skip extended attribute collection
-xattr-namespaces Comma-separated xattr namespace prefixes to collect (e.g. user.,com.apple.)

Cloudstic walks the directory recursively. Symbolic links are not followed.

Extended file attributes: By default, Cloudstic captures POSIX permissions (mode bits), numeric ownership (uid/gid), file creation time (btime, where supported), per-file flags, and extended attributes (xattrs). Directory restores on macOS and Linux replay this metadata on a best-effort basis where supported by the destination filesystem. Known OS-managed xattrs that are not meaningfully restorable, such as com.apple.provenance, are excluded automatically. To control what is captured:

# Skip all POSIX metadata (mode, uid, gid, btime, flags)
cloudstic backup -source local:/data -skip-mode

# Skip only file flags
cloudstic backup -source local:/data -skip-flags

# Skip extended attributes
cloudstic backup -source local:/data -skip-xattrs

# Collect only user.* xattrs (skip security.*, system.*, etc.)
cloudstic backup -source local:/data -xattr-namespaces "user."

See Exclude patterns for the full pattern syntax reference.

Portable Drives

When backing up a portable or external drive from multiple machines, Cloudstic automatically detects the volume identity (on macOS and Linux) and uses it to find previous snapshots. This enables true incremental backups across machines — only changed files are uploaded, even when the mount point or hostname differs.

# Back up a portable drive — UUID is auto-detected
cloudstic backup -source local:/Volumes/MyDrive

# Override UUID when auto-detection fails or for custom lineage
cloudstic backup -source local:/mnt/backup -volume-uuid "A1B2C3D4-1234-5678-ABCD-EF0123456789"

The volume UUID can also be set via the CLOUDSTIC_VOLUME_UUID environment variable. When provided, the explicit UUID takes precedence over auto-detection.

File paths inside the backup are normalized to forward slashes regardless of the operating system, so a backup started on one OS can be continued incrementally on another.

Retention policies (via forget) automatically group all snapshots of the same volume together across machines, so a --keep-daily 7 policy keeps 7 daily snapshots total regardless of which machine created them.

Cross-OS compatibility:

For modern GPT-formatted drives (the default for most drives today), Cloudstic uses the GPT partition UUID which is identical across all platforms — cross-OS incremental backups work automatically with no configuration needed.

For older MBR-formatted drives (some FAT32 USB sticks), the auto-detected UUID is platform-specific and will differ between operating systems. In this case, use -volume-uuid (or CLOUDSTIC_VOLUME_UUID) with a consistent UUID value of your choice.

Platform UUID detection Label detection
macOS ✓ Automatic (GPT partition UUID via diskutil, fallback to getattrlist) ✓ Automatic
Linux ✓ Automatic (GPT partition UUID via /dev/disk/by-partuuid/, fallback to /dev/disk/by-uuid/) ✓ Automatic (/dev/disk/by-label/)
Windows ✓ Automatic (GPT partition UUID via DeviceIoControl) ✓ Automatic (GetVolumeInformation)

Directories spanning multiple drives:

The volume UUID is determined from the backup root path only. If your backup directory contains mount points for other volumes (e.g. /data/external is a separate partition mounted under /data), those files are included in the backup but the volume identity reflects only the root path's filesystem. This is usually fine — the backup works correctly, and incremental detection still functions based on file content. However, for portable drive workflows, back up each volume separately rather than backing up a parent directory that spans multiple drives:

# Good: back up each volume independently
cloudstic backup -source local:/Volumes/MyDrive
cloudstic backup -source local:/Volumes/OtherDrive

# Avoid: backing up a parent that contains mount points from different volumes
cloudstic backup -source local:/Volumes

Note that symlinks to other volumes are not followed — only direct mount points within the tree are traversed.

SFTP Source

Back up files from a remote SFTP server. Supports password authentication, SSH private key, and ssh-agent. Specify the server and path using a URI: sftp://[user@]host[:port]/<path>.

# Back up a remote directory via SFTP
cloudstic backup -source sftp://backup@myserver.com/data/documents \
  -source-sftp-key ~/.ssh/id_ed25519

# Using password auth
cloudstic backup -source sftp://backup@myserver.com/home/user/files \
  -source-sftp-password "secret"
Flag Description
-source-sftp-password SFTP password (optional if using key auth)
-source-sftp-key Path to SSH private key (optional if using password auth)

If neither -source-sftp-password nor -source-sftp-key is provided, Cloudstic will fall back to your SSH_AUTH_SOCK agent.

SFTP backups capture file permissions (mode bits) and numeric ownership (uid/gid) via the SFTPv3 protocol. Birth time, file flags, and extended attributes are not available over SFTP.

Cloudstic walks the remote directory recursively. Mode bits and uid/gid are captured in snapshot metadata. Restore application of these fields depends on restore format support.

The -exclude and -exclude-file flags work with SFTP sources. See Exclude patterns for the full pattern syntax.

Google Drive

Full scan of a Google Drive account. On each backup, Cloudstic lists every file and folder, compares metadata against the previous snapshot, and uploads anything new or changed.

Note: For routine backups, prefer gdrive-changes instead — it is significantly faster and makes far fewer API requests.

When to use: First backup of a Google Drive, or when you want a guaranteed complete rescan (e.g. after recovering from an error).

Setup:

No configuration is required — Cloudstic ships with built-in OAuth credentials. On first run, your default browser opens automatically for you to authorize access. The resulting token is cached in the config directory.

# Back up entire My Drive
cloudstic backup -source gdrive:/

# Back up a shared drive
cloudstic backup -source "gdrive://Company Data"

# Back up only a specific folder
cloudstic backup -source "gdrive://Company Data/path/to/folder"

Environment variables (optional overrides):

Variable Description
GOOGLE_APPLICATION_CREDENTIALS Path to your own Google OAuth credentials JSON file (overrides built-in credentials)
GOOGLE_CREDENTIALS_JSON Inline Google credentials JSON string — OAuth client or service account (useful in CI/CD where mounting files is inconvenient)
GOOGLE_TOKEN_FILE Override token cache path (flag: -google-token-file)
-google-token-ref (Flag only) Secret reference to Google OAuth token (e.g., config-token://google/default)
-google-credentials-ref (Flag only) Secret reference to service account credentials JSON

Using your own credentials or a service account:

Cloudstic ships with built-in OAuth credentials, but you can use your own OAuth client or a Google service account instead.

Credentials can be provided in three ways (in priority order):

  1. Inline JSON via flag or env var (highest priority, ideal for CI/CD):

    # Via environment variable
export GOOGLE_CREDENTIALS_JSON='{"type":"service_account", ...}'
cloudstic backup -source gdrive-changes

# Via flag
cloudstic backup -source gdrive-changes \
  -google-credentials-json '{"type":"service_account", ...}'

  2. Secret reference (for profiles using secret managers):

    cloudstic backup -source gdrive -google-credentials-ref keychain://cloudstic/google-creds

  3. File path:

    export GOOGLE_APPLICATION_CREDENTIALS=~/service-account.json
cloudstic backup -source gdrive-changes

Both OAuth client JSON (authorized-user flow) and service-account JSON are auto-detected — Cloudstic tries the OAuth user flow first, then falls back to service-account auth.

Google Drive (Incremental)

This is the recommended way to back up Google Drive. Uses the Google Drive Changes API to fetch only files that changed since the last backup, rather than listing every file on the drive. This dramatically reduces both backup duration and the number of API requests — a drive with 100,000 files but 50 daily changes only needs to process those 50 files instead of listing all 100,000.

When to use: All routine Google Drive backups. The first run performs a full scan automatically, so there is no need to start with gdrive.

How it works: The first run behaves like a full gdrive backup and records a change token. Subsequent runs fetch only the changes since that token, making backups much faster for drives with thousands of files but few daily modifications.

# First run: full scan + saves change token
cloudstic backup -source gdrive-changes

# Subsequent runs: only fetches changes since last token
cloudstic backup -source gdrive-changes

Uses the same authentication and flags as Google Drive. No setup required — just run the command and authorize in the browser.

Tip: You can use -source gdrive-changes from day one — the first run performs a full scan just like gdrive. Only fall back to -source gdrive if you need to force a complete rescan.

OneDrive

Full scan of a Microsoft OneDrive account. Works the same way as the gdrive source — lists all files, compares against the previous snapshot, and uploads changes.

Setup:

No configuration is required — Cloudstic ships with built-in OAuth credentials. On first run, your default browser opens automatically for you to authorize access. The resulting token is cached in the config directory.

cloudstic backup -source onedrive

If you prefer to use your own Azure app registration instead of the built-in credentials:

  1. Go to the Azure App Registrations portal
  2. Register a new application with "Accounts in any organizational directory and personal Microsoft accounts"
  3. Under Authentication, add platform Mobile and desktop applications with redirect URI http://localhost/callback
  4. Under Authentication > Advanced settings, enable Allow public client flows
  5. Under API permissions, add Files.Read.All and User.Read (Microsoft Graph, Delegated)
export ONEDRIVE_CLIENT_ID=your-client-id

cloudstic backup -source onedrive

No client secret is needed — Cloudstic uses the public client flow with PKCE.

Environment variables (optional overrides):

Variable Description
ONEDRIVE_CLIENT_ID Azure app client ID (overrides built-in credentials)
ONEDRIVE_TOKEN_FILE Override token cache path (flag: -onedrive-token-file)
-onedrive-token-ref (Flag only) Secret reference to OneDrive OAuth token (e.g., config-token://onedrive/default)

OneDrive (Incremental)

This is the recommended way to back up OneDrive. Uses the Microsoft Graph delta API to fetch only files that changed since the last backup, rather than listing every file on the drive. This dramatically reduces both backup duration and the number of API requests.

When to use: All routine OneDrive backups. The first run performs a full scan automatically, so there is no need to start with onedrive.

How it works: The first run behaves like a full onedrive backup and records a delta token. Subsequent runs fetch only the changes since that token, making backups much faster for drives with many files but few daily modifications.

# First run: full scan + saves delta token
cloudstic backup -source onedrive-changes

# Subsequent runs: only fetches changes since last token
cloudstic backup -source onedrive-changes

Uses the same authentication as OneDrive. No setup required — just run the command and authorize in the browser.

Tip: You can use -source onedrive-changes from day one — the first run performs a full scan just like onedrive. Only fall back to -source onedrive if you need to force a complete rescan.

Source metadata in snapshots

Each snapshot records which source produced it. This metadata is used by retention policies to group snapshots — for example, you can keep different retention rules for your local backups vs. your Google Drive backups:

# Keep 30 daily snapshots for Google Drive, 7 for local
cloudstic forget -keep-daily 30 -source gdrive -prune
cloudstic forget -keep-daily 7 -source local:~/Documents -prune

Storage Backends

Local Storage

Store backups on the local filesystem. This is the default.

# Uses default path ./backup_store
cloudstic init -password "passphrase"

# Custom path
cloudstic init -store local:/mnt/external/backups -password "passphrase"

Backblaze B2

Store backups in a Backblaze B2 bucket. Requires B2 application keys.

export B2_KEY_ID=your-key-id
export B2_APP_KEY=your-app-key

cloudstic init -store b2:my-bucket-name -password "passphrase"
cloudstic backup -store b2:my-bucket-name -source local:~/Documents

Use a prefix to namespace objects within a bucket:

cloudstic init -store b2:my-bucket/laptop/ -password "passphrase"

Environment variables:

Variable Description
B2_KEY_ID Backblaze B2 application key ID
B2_APP_KEY Backblaze B2 application key

Amazon S3

Store backups in an Amazon S3 bucket (or S3-compatible endpoints like Cloudflare R2, MinIO, or Wasabi). Requires credentials and a bucket path.

Cloudstic uses the standard AWS SDK for Go, meaning it automatically loads credentials from your environment. You can use explicit credentials (AWS_ACCESS_KEY_ID), or if you already have the AWS CLI configured, you can omit them and Cloudstic will seamlessly use your ~/.aws/credentials profile.

# Using explicit environment variables
export AWS_ACCESS_KEY_ID=your-access-key
export AWS_SECRET_ACCESS_KEY=your-secret-key
cloudstic init -store s3:my-bucket-name -password "passphrase"

# Using an existing AWS CLI profile (e.g., from ~/.aws/credentials)
export AWS_PROFILE=my-profile
cloudstic backup -store s3:my-bucket-name -source local:~/Documents

If using an alternative S3 provider, you must specific the custom endpoint URL. Keep in mind you may also need to modify the -s3-region (defaults to us-east-1):

cloudstic init -store s3:my-bucket -s3-endpoint https://<account_id>.r2.cloudflarestorage.com -s3-region auto -password "passphrase"

Use a prefix to namespace objects within a bucket:

cloudstic init -store s3:my-bucket/laptop/ -password "passphrase"

If you rely on shared AWS config profiles, you can pin one explicitly:

cloudstic backup -store s3:my-bucket -s3-profile my-profile -source local:~/Documents

Environment variables:

Variable Description
AWS_ACCESS_KEY_ID S3 access key ID
AWS_SECRET_ACCESS_KEY S3 secret access key
AWS_PROFILE Shared AWS config profile name (also CLOUDSTIC_S3_PROFILE)
CLOUDSTIC_S3_ENDPOINT Custom endpoint URL (for R2, MinIO, etc.)
CLOUDSTIC_S3_REGION S3 Region

SFTP Storage

Store backups on a remote SFTP server. Supports password authentication, SSH private key, and ssh-agent.

# Initialize a repository on an SFTP server
cloudstic init -store sftp://backup@myserver.com/backups/cloudstic \
  -store-sftp-key ~/.ssh/id_ed25519 \
  -password "passphrase"

# Back up to the SFTP store
cloudstic backup -store sftp://backup@myserver.com/backups/cloudstic \
  -store-sftp-key ~/.ssh/id_ed25519 \
  -source local:~/Documents

The path component of the URI (/backups/cloudstic in the example above) is the remote directory where backup objects will be stored. It will be created if it doesn't exist.

Flags:

Flag Description
-store-sftp-password SFTP password for the store (optional if using key auth)
-store-sftp-key Path to SSH private key for the store (optional if using password auth)

Environment variables:

Variable Description
CLOUDSTIC_STORE_SFTP_PASSWORD SFTP password for the store
CLOUDSTIC_STORE_SFTP_KEY Path to SSH private key for the store

Encryption

Encryption is required by default. All backup data is encrypted with AES-256-GCM before being written to storage.

Interactive password prompt

When running in a terminal, Cloudstic prompts for the repository password only if no other credential is provided via flags (-password, -encryption-key, -recovery-key, -kms-key-arn) or environment variables (CLOUDSTIC_PASSWORD, etc.).

To explicitly request an interactive password prompt alongside a platform key or KMS key, use the -prompt flag:

cloudstic backup -encryption-key <hex> -prompt  # decrypt with key + password layer

This applies to all commands that access an encrypted repository — backup, restore, list, ls, diff, check, cat, key passwd, key add-recovery, and init.

For init, the prompt asks for a new password with confirmation. For all other commands, it asks for the existing repository password.

In non-interactive environments (piped input, cron, CI), you must provide credentials explicitly or the command will fail with an error.

How it works

  1. A random master key is generated during cloudstic init
  2. The master key is wrapped into one or more key slots, each protected by a different credential
  3. Every object written to the repository is encrypted with the master key
  4. Key slot metadata is stored unencrypted (under a keys/ prefix) so you can unlock the repo

Key slot types

Slot type Credential Use case
password --password Day-to-day personal use
platform --encryption-key Automation, CI/CD, platform integration (legacy)
kms-platform --kms-key-arn HSM-backed platform integration via AWS KMS (also supports --kms-region and --kms-endpoint)
recovery --recovery-key Emergency access when password is lost

Recommended setup

# Initialize with password + recovery key
cloudstic init -password "strong passphrase" -add-recovery-key

# Write down the 24-word recovery phrase and store it safely!

Using a recovery key

If you lose your password, provide the 24-word seed phrase:

cloudstic list -recovery-key "word1 word2 word3 ... word24"
cloudstic restore -recovery-key "word1 word2 ... word24"

Adding a recovery key later

# Interactive — prompts for current password
cloudstic key add-recovery

# Non-interactive
cloudstic key add-recovery -password "my passphrase"

# For KMS-managed repositories
cloudstic key add-recovery -kms-key-arn arn:aws:kms:us-east-1:123:key/abc

Changing your password

# Interactive — prompts for current and new password
cloudstic key passwd

# Non-interactive
cloudstic key passwd -password "old passphrase" -new-password "new passphrase"

Retention Policies

Use forget with retention flags to automatically expire old snapshots while keeping a defined history.

Example: keep 7 daily + 4 weekly + 12 monthly

cloudstic forget -keep-daily 7 -keep-weekly 4 -keep-monthly 12 -prune

How it works (Retention)

  • Snapshots are grouped by source, account, and path (configurable with -group-by)
  • Within each group, the retention policy decides which to keep
  • A snapshot matching multiple policies (e.g. both "daily" and "weekly") is kept with all reasons shown
  • Snapshots not matching any keep rule are removed
  • Add -prune to reclaim storage immediately, or run cloudstic prune separately

Preview before acting

Always safe to preview first:

cloudstic forget -keep-daily 7 -keep-monthly 12 -dry-run

Environment Variables

Variable Flag equivalent Description
CLOUDSTIC_STORE -store Storage backend URI: local:<path>, s3:<bucket>[/<prefix>], b2:<bucket>[/<prefix>], sftp://[user@]host[:port]/<path>
CLOUDSTIC_S3_ENDPOINT -s3-endpoint S3 compatible endpoint (for MinIO, R2, etc.)
CLOUDSTIC_S3_REGION -s3-region S3 Region
CLOUDSTIC_S3_PROFILE -s3-profile AWS shared config profile for S3 auth
AWS_ACCESS_KEY_ID -s3-access-key S3 Access Key ID
AWS_SECRET_ACCESS_KEY -s3-secret-key S3 Secret Access Key
CLOUDSTIC_STORE_SFTP_PASSWORD -store-sftp-password SFTP password for the store
CLOUDSTIC_STORE_SFTP_KEY -store-sftp-key Path to SSH private key for the store
CLOUDSTIC_SOURCE -source Source URI: local:<path>, sftp://[user@]host[:port]/<path>, gdrive[://<Drive Name>][/<path>], gdrive-changes[://<Drive Name>][/<path>], onedrive[://<Drive Name>][/<path>], onedrive-changes[://<Drive Name>][/<path>]
CLOUDSTIC_SOURCE_SFTP_PASSWORD -source-sftp-password SFTP password for the source
CLOUDSTIC_SOURCE_SFTP_KEY -source-sftp-key Path to SSH private key for the source
CLOUDSTIC_ENCRYPTION_KEY -encryption-key Platform key (hex)
CLOUDSTIC_PASSWORD -password Encryption password
CLOUDSTIC_RECOVERY_KEY -recovery-key Recovery seed phrase
CLOUDSTIC_KMS_KEY_ARN -kms-key-arn AWS KMS key ARN for kms-platform slots
CLOUDSTIC_KMS_REGION -kms-region AWS KMS region
CLOUDSTIC_KMS_ENDPOINT -kms-endpoint Custom AWS KMS endpoint URL
CLOUDSTIC_PROFILES_FILE -profiles-file Path to profiles YAML file
CLOUDSTIC_CONFIG_DIR — Override config directory path
GOOGLE_APPLICATION_CREDENTIALS -google-credentials Path to your own Google OAuth credentials file (optional, overrides built-in)
GOOGLE_CREDENTIALS_JSON -google-credentials-json Inline Google credentials JSON (OAuth client or service account)
GOOGLE_TOKEN_FILE -google-token-file Override Google OAuth token path
ONEDRIVE_CLIENT_ID — Microsoft app client ID (optional, overrides built-in)
ONEDRIVE_TOKEN_FILE — Override OneDrive token path
B2_KEY_ID — Backblaze B2 key ID
B2_APP_KEY — Backblaze B2 application key