cloudstic init

Overview

The cloudstic init command bootstraps a new Cloudstic repository by creating encryption key slots and writing the repository configuration marker. This command must be run before your first backup.

Encryption is required by default. All data is encrypted with AES-256-GCM unless you explicitly disable it with -no-encryption (not recommended).

Basic Usage

cloudstic init [options]

Encryption Modes

Password-Based Encryption (Recommended)

cloudstic init -password "your-secure-passphrase"

If running in an interactive terminal and no credentials are provided, you will be prompted to enter a password:

$ cloudstic init
Enter new repository password: ****
Confirm repository password: ****
Created new encryption key slots.
Repository initialized (encrypted: true).

If credentials are already provided (via -encryption-key, -kms-key-arn, etc.), no password is prompted unless you explicitly pass -prompt.

Platform Key + Password (Multi-Factor)

For maximum security, combine a platform key with an interactive password. Both are required to decrypt:

cloudstic init -encryption-key "0123456789abcdef..." -prompt

Platform Key Only

cloudstic init -encryption-key "0123456789abcdef..." # 64 hex chars = 32 bytes

With Recovery Key

Generate a 24-word BIP39 recovery phrase during initialization:

cloudstic init -password "your-passphrase" -add-recovery-key

Output:

Created new encryption key slots.

╔══════════════════════════════════════════════════════════════╗
║                      RECOVERY KEY                           ║
╠══════════════════════════════════════════════════════════════╣
║                                                              ║
║  abandon ability able about above absent absorb abstract...
║                                                              ║
║  Write down these 24 words and store them in a safe place.   ║
║  This is the ONLY time the recovery key will be displayed.   ║
║  If you lose your password, this key is your only way to     ║
║  recover your encrypted backups.                             ║
║                                                              ║
╚══════════════════════════════════════════════════════════════╝

Repository initialized (encrypted: true).

Store your recovery key in a password manager or write it down and keep it in a secure location. This is your last resort for recovering encrypted backups if you forget your password.

Unencrypted Repository (Not Recommended)

cloudstic init -no-encryption

Output:

WARNING: creating unencrypted repository. Your backups will NOT be encrypted at rest.
Repository initialized (encrypted: false).

Only use -no-encryption for testing or when storing data that is already encrypted at rest by another system. Your backup data will be stored in plaintext.

Command Flags

boolean

default:"false"

Generate a 24-word BIP39 recovery key during initialization. The recovery phrase is displayed once and allows you to recover your repository if you lose your password or platform key.

boolean

default:"false"

Create an unencrypted repository. Not recommended unless you have a specific reason (e.g., data is pre-encrypted, testing, or compliance requirements).

boolean

default:"false"

Force an interactive password prompt even when other credentials (e.g. -encryption-key, -kms-key-arn) are already provided. Use this to add a password layer on top of a platform or KMS key.

boolean

default:"false"

Disable all interactive prompts. If no encryption credentials are provided and --no-prompt is set, init fails with an error instead of prompting for a password. Useful for scripts and CI/CD pipelines.

Global Flags (All Commands)

string

default:"local:./backup_store"

Storage backend URI. Formats: local:<path>, s3:<bucket>[/<prefix>], b2:<bucket>[/<prefix>], sftp://[user@]host[:port]/<path>.

string

default:""

Platform key as 64 hexadecimal characters (32 bytes). Used for platform-managed encryption in automated environments.

string

default:""

Repository password for password-based encryption. If not provided and no other credentials are set, and running interactively, you will be prompted.

string

default:""

AWS KMS key ARN for envelope encryption. Requires AWS credentials with KMS decrypt permissions.

string

default:""

AWS region for KMS operations. Defaults to AWS SDK’s standard discovery logic if not provided.

string

default:""

Custom endpoint URL for KMS operations (e.g., for local testing with LocalStack).

boolean

default:"false"

Log detailed operations.

boolean

default:"false"

Suppress progress output (keeps final summary).

boolean

default:"false"

Write the command result as JSON to stdout instead of the human-readable initialization summary.

boolean

default:"false"

Log every store request with network call details, timing, and sizes.

S3-Specific Flags

string

default:""

S3-compatible endpoint URL (for MinIO, Cloudflare R2, DigitalOcean Spaces, etc.).

string

default:"us-east-1"

S3 region.

string

default:""

S3 access key ID.

string

default:""

S3 secret access key.

SFTP Store Credentials

string

default:""

SFTP store password.

string

default:""

Path to SSH private key for SFTP store authentication.

string

default:""

Path to custom known_hosts file for host key validation.

boolean

default:"false"

Skip host key validation (INSECURE).

Backblaze B2 Flags

string

default:""

Backblaze B2 application key ID.

string

default:""

Backblaze B2 application key.

Examples

Local Repository with Password

cloudstic init -password "my-secure-passphrase"

S3 Repository with Recovery Key

export AWS_ACCESS_KEY_ID="AKIAIOSFODNN7EXAMPLE"
export AWS_SECRET_ACCESS_KEY="wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"

cloudstic init \
  -store s3:my-backup-bucket \
  -s3-region us-west-2 \
  -password "my-secure-passphrase" \
  -add-recovery-key

MinIO/S3-Compatible Storage

cloudstic init \
  -store s3:my-backups \
  -s3-endpoint https://minio.example.com \
  -s3-region us-east-1 \
  -password "my-secure-passphrase"

SFTP Repository

cloudstic init \
  -store sftp://backupuser@backup.example.com/home/backupuser/cloudstic \
  -store-sftp-key ~/.ssh/id_rsa \
  -password "my-secure-passphrase"

Backblaze B2

export B2_KEY_ID="your_key_id"
export B2_APP_KEY="your_app_key"

cloudstic init \
  -store b2:my-bucket-name/cloudstic/ \
  -password "my-secure-passphrase"

Behavior

Encryption Key Slots

When you initialize an encrypted repository, Cloudstic:

Generates a random 32-byte master key
Wraps the master key with your password or platform key using strong KDF (Argon2id for passwords)
Stores the encrypted key slot(s) under keys/ in the repository
Derives an HMAC dedup key from the master key for content-addressing without exposing plaintext hashes

Adopting Existing Key Slots

If key slots already exist in the store (e.g., from a previous partial init or if you are adding new credentials), cloudstic init --adopt-slots will verify you can unlock them with the provided credentials and automatically create new slots for any additional credentials provided in the command line.

# Example: Adding a platform key to a repository that currently only has a password
cloudstic init --adopt-slots --password "mypass" --encryption-key "a1b2..."

Output:

Adopted existing encryption key slots.
Repository initialized (encrypted: true).

If credentials don’t match, init fails:

Found existing key slots but cannot open them: no provided credential matches (types: password)

Repository Already Initialized

Running init on an already initialized repository exits immediately:

Repository is already initialized.

Troubleshooting

Error: encryption is required by default

Error: encryption is required by default.
Provide --password or --encryption-key to encrypt your repository.
To create an unencrypted repository, pass --no-encryption (not recommended).

Solution: Provide credentials via flags, or run interactively to be prompted for a password. If using a platform key or KMS, no password is prompted automatically. Add -prompt to explicitly request one.

Error: encryption password cannot be empty

Error: encryption password cannot be empty.

Solution: Provide a non-empty password when prompted or via the -password flag.

Error: passwords do not match

Error: passwords do not match.

Solution: Re-run the command and ensure both password entries are identical.

Invalid —encryption-key

invalid --encryption-key (must be hex-encoded): encoding/hex: invalid byte: U+...

Solution: The -encryption-key must be exactly 64 hexadecimal characters (0-9, a-f). Generate with:

openssl rand -hex 32

cloudstic backup: Create your first backup after initializing
cloudstic key add-recovery: Add a recovery key to an existing repository
cloudstic key passwd: Change the repository password
cloudstic check: Verify repository integrity

Onboarding

Interactive Mode

Repository Management

Backup & Restore

Maintenance

Key Management

Configuration

Utilities

Overview

Basic Usage

Encryption Modes

Password-Based Encryption (Recommended)

Platform Key + Password (Multi-Factor)

Platform Key Only

With Recovery Key

Unencrypted Repository (Not Recommended)

Command Flags

Global Flags (All Commands)

S3-Specific Flags

SFTP Store Credentials

Backblaze B2 Flags

Examples

Local Repository with Password

S3 Repository with Recovery Key

MinIO/S3-Compatible Storage

SFTP Repository

Backblaze B2

Behavior

Encryption Key Slots

Adopting Existing Key Slots

Repository Already Initialized

Troubleshooting

Error: encryption is required by default

Error: encryption password cannot be empty

Error: passwords do not match

Invalid —encryption-key

​Overview

​Basic Usage

​Encryption Modes

​Password-Based Encryption (Recommended)

​Platform Key + Password (Multi-Factor)

​Platform Key Only

​With Recovery Key

​Unencrypted Repository (Not Recommended)

​Command Flags

​Global Flags (All Commands)

​S3-Specific Flags

​SFTP Store Credentials

​Backblaze B2 Flags

​Examples

​Local Repository with Password

​S3 Repository with Recovery Key

​MinIO/S3-Compatible Storage

​SFTP Repository

​Backblaze B2

​Behavior

​Encryption Key Slots

​Adopting Existing Key Slots

​Repository Already Initialized

​Troubleshooting

​Error: encryption is required by default

​Error: encryption password cannot be empty

​Error: passwords do not match

​Invalid —encryption-key

​Related Commands

Overview

Basic Usage

Encryption Modes

Password-Based Encryption (Recommended)

Platform Key + Password (Multi-Factor)

Platform Key Only

With Recovery Key

Unencrypted Repository (Not Recommended)

Command Flags

Global Flags (All Commands)

S3-Specific Flags

SFTP Store Credentials

Backblaze B2 Flags

Examples

Local Repository with Password

S3 Repository with Recovery Key

MinIO/S3-Compatible Storage

SFTP Repository

Backblaze B2

Behavior

Encryption Key Slots

Adopting Existing Key Slots

Repository Already Initialized

Troubleshooting

Error: encryption is required by default

Error: encryption password cannot be empty

Error: passwords do not match

Invalid —encryption-key

Related Commands