Cloudstic CLI provides native installation methods for all major platforms. Choose the method that works best for your system:
Homebrew (Recommended) The easiest way to install Cloudstic on macOS is via Homebrew: # Install Cloudstic brew install cloudstic/tap/cloudstic
# Upgrade to the latest version brew upgrade cloudstic # Uninstall brew uninstall cloudstic
Pre-built Binary Download the latest release for your architecture: Apple Silicon (M1/M2/M3)
Intel
curl -L https://github.com/cloudstic/cli/releases/latest/download/cloudstic_darwin_arm64.tar.gz | tar xz sudo mv cloudstic /usr/local/bin/ chmod +x /usr/local/bin/cloudstic
Homebrew Install via Homebrew on Linux: # Install Cloudstic brew install cloudstic/tap/cloudstic # Upgrade to the latest version brew upgrade cloudstic
Pre-built Binary Download the latest release for your architecture: curl -L https://github.com/cloudstic/cli/releases/latest/download/cloudstic_linux_amd64.tar.gz | tar xz sudo mv cloudstic /usr/local/bin/ chmod +x /usr/local/bin/cloudstic
Binaries are statically linked and have no external dependencies beyond glibc.
Winget (Recommended) Install via Windows Package Manager: # Install Cloudstic winget install Cloudstic.CLI
# Upgrade to the latest version winget upgrade Cloudstic.CLI # Uninstall winget uninstall Cloudstic.CLI
Manual Download
Download the Windows binary from GitHub Releases
Extract the cloudstic.exe file
Add the executable to your PATH or run it from the extraction directory
To add Cloudstic to your PATH permanently, search for “Environment Variables” in Windows settings and add the directory containing cloudstic.exe to your system PATH.
If you have Go 1.21 or later installed: go install github.com/cloudstic/cli/cmd/cloudstic@latest
The binary will be installed to $GOPATH/bin/cloudstic (or $HOME/go/bin/cloudstic by default). Make sure $GOPATH/bin is in your PATH to run cloudstic from anywhere.
Verify Installation Confirm that Cloudstic is installed correctly:
You should see output similar to:
cloudstic 1.2.0 (commit a1b2c3d, built 2025-03-01T10:30:00Z)
Installation successful! You’re ready to initialize your first repository.
Build from Source For developers or users who want to build from the latest source code:
Clone the repository
git clone https://github.com/cloudstic/cli.git cd cli
Build the binary
go build -o cloudstic ./cmd/cloudstic
This creates a cloudstic binary in the current directory.
Install the binary (optional)
sudo mv cloudstic /usr/local/bin/
Or add the current directory to your PATH.
# Run all tests go test -v -race -count=1 ./... # Run the full check script (fmt + lint + test + coverage) ./scripts/check.sh
E2E tests require Docker for Testcontainers (MinIO, SFTP). They skip gracefully if Docker is unavailable.
Shell Completions Cloudstic supports tab-completion for commands, flags, and values in bash, zsh, and fish.
Load completion for current session source <( cloudstic completion bash)
Load completion permanently echo 'source <(cloudstic completion bash)' >> ~/.bashrc
Bash completions require the bash-completion package:
macOS : brew install bash-completionDebian/Ubuntu : apt install bash-completion Load completion for current session source <( cloudstic completion zsh)
Load completion permanently Add to ~/.zshrc: echo 'source <(cloudstic completion zsh)' >> ~/.zshrc
Alternative : Place in your $fpath:cloudstic completion zsh > "${ fpath [1]}/_cloudstic"
You may need to run compinit or start a new shell for changes to take effect.
Load completion for current session cloudstic completion fish | source
Load completion permanently cloudstic completion fish > ~/.config/fish/completions/cloudstic.fish
Configuration Directory Cloudstic stores OAuth tokens and state files in a platform-specific directory:
Platform Default Path Linux ~/.config/cloudstic/macOS ~/Library/Application Support/cloudstic/Windows %AppData%\cloudstic\
Override the config directory by setting the CLOUDSTIC_CONFIG_DIR environment variable: export CLOUDSTIC_CONFIG_DIR = / custom / path / to / config
This directory contains:
google_token.jsononedrive_token.jsonState files — For incremental backups (change tokens, delta links)
Environment Variables Simplify your workflow by setting default values via environment variables. This is especially useful for automation:
# Storage backend configuration export CLOUDSTIC_STORE = s3 export CLOUDSTIC_STORE_PATH = my-backup-bucket export CLOUDSTIC_STORE_PREFIX = "laptop/" # S3 credentials (or use AWS CLI profiles) export AWS_ACCESS_KEY_ID = your-access-key export AWS_SECRET_ACCESS_KEY = your-secret-key export CLOUDSTIC_S3_REGION = us-east-1 # Encryption export CLOUDSTIC_ENCRYPTION_PASSWORD = "my secure passphrase" # Source defaults export CLOUDSTIC_SOURCE = gdrive-changes
With these set, commands become much shorter:
# Instead of: cloudstic backup -store s3 -store-path my-bucket -source gdrive-changes -encryption-password "..." # Just run: cloudstic backup
See the User Guide for the complete list of supported environment variables. Next Steps Troubleshooting
Command not found after installation
Problem : Shell can’t find the cloudstic binary.Solution : Make sure the installation directory is in your PATH:# Check your PATH echo $PATH # Add /usr/local/bin to PATH (if missing) export PATH = "/usr/local/bin: $PATH " # For Go installs, ensure GOPATH/bin is in PATH export PATH = " $HOME /go/bin: $PATH "
Add the export statement to your ~/.bashrc, ~/.zshrc, or ~/.profile to make it permanent.
Permission denied when running cloudstic
Problem : Binary is not executable.Solution : Add execute permissions:chmod +x /usr/local/bin/cloudstic
Problem : brew install cloudstic/tap/cloudstic fails.Solution : Update Homebrew and try again:brew update brew install cloudstic/tap/cloudstic
Problem : Build fails with Go version error.Solution : Upgrade Go to version 1.21 or later:# Check current version go version # Download latest from https://golang.org/dl/