Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Cloudstic/cli/llms.txt

Use this file to discover all available pages before exploring further.

Cloudstic uses AES-256-GCM encryption by default. This guide explains how to manage encryption credentials, add recovery keys, change passwords, and understand the key slot system.

​
Understanding Cloudstic Encryption

Cloudstic’s encryption model:
  • A random 32-byte master key is generated during cloudstic init
  • The master key encrypts all backup data
  • The master key itself is wrapped into one or more key slots
  • Each slot is unlocked with different credentials (password, platform key, KMS key, or recovery phrase)
  • All slots unlock the same master key
Think of key slots like multiple keys to the same safe. You can unlock your backups with any valid credential.

​
Key Slot Types

Slot TypeCredentialUse Case
passwordUser password (passphrase)Day-to-day access, interactive use
platform64-character hex keyAutomation, CI/CD, non-interactive scripts
kms-platformAWS KMS key ARNHSM-backed enterprise encryption
recovery24-word BIP39 mnemonicEmergency access when password is lost

​
Creating a Repository with Encryption

​
Password-Based Encryption

Most common for personal use: 
cloudstic init -encryption-password "your strong passphrase"
Use a strong, unique passphrase. Consider using a passphrase manager like 1Password, Bitwarden, or LastPass.
Add a recovery key during initialization: 
cloudstic init -encryption-password "your passphrase" -recovery
Output: 
╔══════════════════════════════════════════════════════════════╗
║                      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).
Write down your recovery key immediately! It will only be displayed once. Store it in a safe, offline location (physical safe, safety deposit box, etc.).

​
Platform Key for Automation

Use a raw encryption key for non-interactive systems: 
# Generate a random 32-byte key (64 hex characters)
export CLOUDSTIC_ENCRYPTION_KEY=$(openssl rand -hex 32)

# Initialize repository
cloudstic init -encryption-key $CLOUDSTIC_ENCRYPTION_KEY

# Store the key securely (e.g., in a secrets manager)
echo $CLOUDSTIC_ENCRYPTION_KEY | vault kv put secret/backups key=-
Platform keys are intended for automation where password prompts aren’t possible. Store them in a secrets manager (HashiCorp Vault, AWS Secrets Manager, etc.).

​
Dual Access (Password + Platform Key)

Create a repository with both types of access: 
cloudstic init \
  -encryption-password "your passphrase" \
  -encryption-key $(openssl rand -hex 32)
Now you can unlock the repository with either credential.

​
Listing Key Slots

View all key slots in a repository: 
cloudstic key list
Output: 
+──────────────+─────────+──────────+
| Type         | Label   | KDF      |
+──────────────+─────────+──────────+
| password     | default | argon2id |
| recovery     | default | —        |
+──────────────+─────────+──────────+

2 key slot(s) found.
key list does not require authentication — slot metadata is stored unencrypted.

​
Adding a Recovery Key

Add a recovery key to an existing repository: 
cloudstic key add-recovery -encryption-password "your passphrase"
Output: 
╔══════════════════════════════════════════════════════════════╗
║                      RECOVERY KEY                           ║
╠══════════════════════════════════════════════════════════════╣
║                                                              ║
║  abandon ability able about above absent absorb abstract ... ║
║                                                              ║
╚══════════════════════════════════════════════════════════════╝

Recovery key slot has been added to the repository.
This is the only time the recovery key is displayed. Write it down and store it securely.
If you’re using a platform key instead of a password: 
cloudstic key add-recovery -encryption-key <your-hex-key>
For KMS-managed repositories: 
cloudstic key add-recovery -kms-key-arn arn:aws:kms:us-east-1:123456:key/abc-123

​
Changing Your Password

Update the password slot: 
cloudstic key passwd
You’ll be prompted for:
  1. Current password (or provide via -encryption-password)
  2. New password (or provide via -new-password)
  3. Confirmation of new password
Non-interactive example: 
cloudstic key passwd \
  -encryption-password "old passphrase" \
  -new-password "new passphrase"
If you’re unlocking with a platform key or KMS key, you can use those to set a new password:
cloudstic key passwd -encryption-key <hex-key> -new-password "new passphrase"

​
Using Recovery Keys to Access Backups

If you’ve lost your password, use your recovery key: 
cloudstic list -recovery-key "word1 word2 word3 ... word24"
Or set it as an environment variable: 
export CLOUDSTIC_RECOVERY_KEY="word1 word2 word3 ... word24"
cloudstic list
cloudstic restore
Once you’ve regained access, set a new password: 
cloudstic key passwd -recovery-key "word1 word2 ... word24" -new-password "new passphrase"

​
Environment Variables for Credentials

Avoid typing credentials repeatedly: 
# For password-based access
export CLOUDSTIC_ENCRYPTION_PASSWORD="your passphrase"

# For platform key access
export CLOUDSTIC_ENCRYPTION_KEY="64-character-hex-key"

# For recovery key access
export CLOUDSTIC_RECOVERY_KEY="word1 word2 ... word24"

# For KMS access
export CLOUDSTIC_KMS_KEY_ARN="arn:aws:kms:us-east-1:123456:key/abc-123"
Add to your shell profile (~/.bashrc, ~/.zshrc) for persistence: 
echo 'export CLOUDSTIC_ENCRYPTION_PASSWORD="your passphrase"' >> ~/.bashrc
source ~/.bashrc
Security consideration: Only store credentials in environment variables on trusted, single-user systems. For shared systems, enter passwords interactively.

​
Interactive Password Prompts

If no credential is provided, Cloudstic will prompt interactively: 
$ cloudstic restore
Repository password: [hidden input]
This is the most secure option for personal use.

​
Advanced: AWS KMS Integration

For enterprise deployments, use AWS KMS to manage encryption keys:
1

Create a KMS key

aws kms create-key --description "Cloudstic backup encryption"
Note the KeyId from the output.
2

Initialize repository with KMS

cloudstic init -kms-key-arn arn:aws:kms:us-east-1:123456:key/abc-123
3

Use KMS for all operations

export CLOUDSTIC_KMS_KEY_ARN="arn:aws:kms:us-east-1:123456:key/abc-123"
cloudstic backup -source local -source-path ~/Documents
cloudstic restore
KMS integration requires AWS credentials with kms:Decrypt and kms:GenerateDataKey permissions.

​
Security Best Practices

1

Use strong, unique passphrases

  • At least 20 characters
  • Mix of words, numbers, and symbols
  • Not reused from other services
  • Consider using a passphrase generator
2

Always create a recovery key

cloudstic init -encryption-password "passphrase" -recovery
3

Store recovery keys offline

  • Write on paper, store in a safe
  • Use a safety deposit box
  • Split across multiple secure locations
  • Never store digitally alongside backups
4

Test recovery key access

Verify your recovery key works:
cloudstic list -recovery-key "word1 word2 ... word24"
5

Rotate passwords periodically

cloudstic key passwd
Recommended: every 6-12 months
6

Use KMS for production systems

Leverage hardware security modules for enterprise deployments:
cloudstic init -kms-key-arn arn:aws:kms:...

​
Troubleshooting

​
”Could not open key slots” Error

Your password or key is incorrect. Verify: 
# Check environment variable
echo $CLOUDSTIC_ENCRYPTION_PASSWORD

# Try recovery key
cloudstic list -recovery-key "word1 word2 ... word24"

​
“Repository not encrypted” Message

The repository was created with -no-encryption. Key management commands don’t apply to unencrypted repositories.

​
Lost Password and Recovery Key

There is no recovery option if both are lost. Your backups are permanently inaccessible. This is by design — encryption without a backdoor. Preventive measures:
  • Always create a recovery key (-recovery)
  • Store recovery key in multiple secure locations
  • Document your encryption setup

​
Changing Password Doesn’t Work

Ensure you’re providing the correct current credentials: 
# Unlock with current password
cloudstic key passwd -encryption-password "current passphrase"

# Or with platform key
cloudstic key passwd -encryption-key <current-hex-key>

# Or with recovery key
cloudstic key passwd -recovery-key "word1 word2 ... word24"

​
Recovery Key Format

Recovery keys use the BIP39 mnemonic standard:
  • 24 words from a standardized word list
  • Each word encodes ~11 bits of entropy
  • Total: 256 bits of entropy (same as the master key)
  • Words are lowercase, space-separated
  • Order matters
Example (do not use this): 
abandon ability able about above absent absorb abstract absurd abuse access accident
account accuse achieve acid acoustic acquire across act action actor actress actual

​
Unencrypted Repositories

You can create an unencrypted repository (not recommended): 
cloudstic init -no-encryption
Unencrypted repositories are not recommended. Your backup data is stored in plaintext and can be read by anyone with storage access.
Use cases for unencrypted repositories:
  • Testing and development
  • Backups of already-encrypted data
  • Air-gapped systems with physical security

​
Next Steps

First Backup

Create your first encrypted backup

Restoring Files

Use your encryption key to restore backups

Automation

Automate backups with platform keys

Check Command

Verify encrypted data integrity

Build docs developers (and LLMs) love

Get started for freeTalk to us