Installation

Choose Your Platform

Cloudstic CLI provides native installation methods for all major platforms. Choose the method that works best for your system:

macOS
Linux
Windows
Go

Homebrew (Recommended)

The easiest way to install Cloudstic on macOS is via Homebrew:

# Install Cloudstic
brew install cloudstic/tap/cloudstic

Upgrade and Uninstall

# Upgrade to the latest version
brew upgrade cloudstic

# Uninstall
brew uninstall cloudstic

Curl Installer

# Install latest release
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 with shell completion (auto-detect shell)
curl -fsSL https://raw.githubusercontent.com/Cloudstic/cli/main/scripts/install.sh | sh -s -- --with-completion

Pre-built Binary

Download the latest release for your architecture:

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

curl -L https://github.com/cloudstic/cli/releases/latest/download/cloudstic_darwin_amd64.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

Curl Installer

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

# 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 completion for a specific shell
curl -fsSL https://raw.githubusercontent.com/Cloudstic/cli/main/scripts/install.sh | sh -s -- --with-completion --shell bash

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

curl -L https://github.com/cloudstic/cli/releases/latest/download/cloudstic_linux_arm64.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 and Uninstall

# 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.

Install with Go Toolchain

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:

cloudstic version

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:

Install Go 1.21 or later

Download and install Go from golang.org

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 the test suite

# 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.

Bash
Zsh
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-completion
Debian/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.json: Google Drive OAuth token (if using Google Drive sources)
onedrive_token.json: OneDrive OAuth token (if using OneDrive sources)
State 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:

~/.bashrc or ~/.zshrc

# Storage backend configuration
export CLOUDSTIC_STORE=s3:my-backup-bucket/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_PASSWORD="my secure passphrase"

# Source defaults
export CLOUDSTIC_SOURCE=gdrive-changes

With these set, commands become much shorter:

# Instead of:
cloudstic backup -store s3:my-bucket -source gdrive-changes -password "..."

# Just run:
cloudstic backup

See the User Guide for the complete list of supported environment variables.

Next Steps

Quick Start

Initialize your first repository and create a backup

User Guide

Explore all commands and advanced features

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

Homebrew tap not found

Problem: brew install cloudstic/tap/cloudstic fails.Solution: Update Homebrew and try again:

brew update
brew install cloudstic/tap/cloudstic

Go version too old

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/

If you encounter issues not covered here, please report them at github.com/cloudstic/cli/issues.

Get Started

Core Concepts

Sources

Storage Backends

Guides

Choose Your Platform

Homebrew (Recommended)

Curl Installer

Pre-built Binary

Homebrew

Curl Installer

Pre-built Binary

Winget (Recommended)

Manual Download

Install with Go Toolchain

Verify Installation

Build from Source

Shell Completions

Load completion for current session

Load completion permanently

Load completion for current session

Load completion permanently

Load completion for current session

Load completion permanently

Configuration Directory

Environment Variables

Next Steps

Quick Start

User Guide

Troubleshooting

​Choose Your Platform

​Homebrew (Recommended)

​Curl Installer

​Pre-built Binary

​Homebrew

​Curl Installer

​Pre-built Binary

​Winget (Recommended)

​Manual Download

​Install with Go Toolchain

​Verify Installation

​Build from Source

​Shell Completions

​Load completion for current session

​Load completion permanently

​Load completion for current session

​Load completion permanently

​Load completion for current session

​Load completion permanently

​Configuration Directory

​Environment Variables

​Next Steps

Quick Start

User Guide

​Troubleshooting

Choose Your Platform

Homebrew (Recommended)

Curl Installer

Pre-built Binary

Homebrew

Curl Installer

Pre-built Binary

Winget (Recommended)

Manual Download

Install with Go Toolchain

Verify Installation

Build from Source

Shell Completions

Load completion for current session

Load completion permanently

Load completion for current session

Load completion permanently

Load completion for current session

Load completion permanently

Configuration Directory

Environment Variables

Next Steps

Troubleshooting