Skip to main content

​
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

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

​
-add-recovery-key
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.
​
-no-encryption
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).
​
-prompt
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.
​
--no-prompt
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)

​
-store
string
default:"local:./backup_store"
Storage backend URI. Formats: local:<path>, s3:<bucket>[/<prefix>], b2:<bucket>[/<prefix>], sftp://[user@]host[:port]/<path>.
​
-encryption-key
string
default:""
Platform key as 64 hexadecimal characters (32 bytes). Used for platform-managed encryption in automated environments.
​
-password
string
default:""
Repository password for password-based encryption. If not provided and no other credentials are set, and running interactively, you will be prompted.
​
-kms-key-arn
string
default:""
AWS KMS key ARN for envelope encryption. Requires AWS credentials with KMS decrypt permissions.
​
-kms-region
string
default:""
AWS region for KMS operations. Defaults to AWS SDK’s standard discovery logic if not provided.
​
-kms-endpoint
string
default:""
Custom endpoint URL for KMS operations (e.g., for local testing with LocalStack).
​
-verbose
boolean
default:"false"
Log detailed operations.
​
-quiet
boolean
default:"false"
Suppress progress output (keeps final summary).
​
-json
boolean
default:"false"
Write the command result as JSON to stdout instead of the human-readable initialization summary.
​
-debug
boolean
default:"false"
Log every store request with network call details, timing, and sizes.

​
S3-Specific Flags

​
-s3-endpoint
string
default:""
S3-compatible endpoint URL (for MinIO, Cloudflare R2, DigitalOcean Spaces, etc.).
​
-s3-region
string
default:"us-east-1"
S3 region.
​
-s3-access-key
string
default:""
S3 access key ID.
​
-s3-secret-key
string
default:""
S3 secret access key.

​
SFTP Store Credentials

​
-store-sftp-password
string
default:""
SFTP store password.
​
-store-sftp-key
string
default:""
Path to SSH private key for SFTP store authentication.
​
-store-sftp-known-hosts
string
default:""
Path to custom known_hosts file for host key validation.
​
-store-sftp-insecure
boolean
default:"false"
Skip host key validation (INSECURE).

​
Backblaze B2 Flags

B2 requires B2_KEY_ID and B2_APP_KEY environment variables.

​
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:
  1. Generates a random 32-byte master key
  2. Wraps the master key with your password or platform key using strong KDF (Argon2id for passwords)
  3. Stores the encrypted key slot(s) under keys/ in the repository
  4. 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