> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudstic.com/llms.txt
> Use this file to discover all available pages before exploring further.

# cloudstic init

> Initialize a new Cloudstic repository with encryption

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

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

## Basic Usage

```bash theme={null}
cloudstic init [options]
```

## Encryption Modes

### Password-Based Encryption (Recommended)

```bash theme={null}
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:

```bash theme={null}
$ 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:

```bash theme={null}
cloudstic init -encryption-key "0123456789abcdef..." -prompt
```

### Platform Key Only

```bash theme={null}
cloudstic init -encryption-key "0123456789abcdef..." # 64 hex chars = 32 bytes
```

### With Recovery Key

Generate a 24-word BIP39 recovery phrase during initialization:

```bash theme={null}
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).
```

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

### Unencrypted Repository (Not Recommended)

```bash theme={null}
cloudstic init -no-encryption
```

**Output:**

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

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

## Command Flags

<ParamField path="-add-recovery-key" type="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.
</ParamField>

<ParamField path="-no-encryption" type="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).
</ParamField>

<ParamField path="-prompt" type="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.
</ParamField>

<ParamField path="--no-prompt" type="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.
</ParamField>

### Global Flags (All Commands)

<ParamField path="-store" type="string" default="local:./backup_store" env="CLOUDSTIC_STORE">
  Storage backend URI. Formats: `local:<path>`, `s3:<bucket>[/<prefix>]`, `b2:<bucket>[/<prefix>]`, `sftp://[user@]host[:port]/<path>`.
</ParamField>

<ParamField path="-encryption-key" type="string" default="" env="CLOUDSTIC_ENCRYPTION_KEY">
  Platform key as 64 hexadecimal characters (32 bytes). Used for platform-managed encryption in automated environments.
</ParamField>

<ParamField path="-password" type="string" default="" env="CLOUDSTIC_PASSWORD">
  Repository password for password-based encryption. If not provided and no other credentials are set, and running interactively, you will be prompted.
</ParamField>

<ParamField path="-kms-key-arn" type="string" default="" env="CLOUDSTIC_KMS_KEY_ARN">
  AWS KMS key ARN for envelope encryption. Requires AWS credentials with KMS decrypt permissions.
</ParamField>

<ParamField path="-kms-region" type="string" default="" env="CLOUDSTIC_KMS_REGION">
  AWS region for KMS operations. Defaults to AWS SDK's standard discovery logic if not provided.
</ParamField>

<ParamField path="-kms-endpoint" type="string" default="" env="CLOUDSTIC_KMS_ENDPOINT">
  Custom endpoint URL for KMS operations (e.g., for local testing with LocalStack).
</ParamField>

<ParamField path="-verbose" type="boolean" default="false">
  Log detailed operations.
</ParamField>

<ParamField path="-quiet" type="boolean" default="false">
  Suppress progress output (keeps final summary).
</ParamField>

<ParamField path="-json" type="boolean" default="false">
  Write the command result as JSON to stdout instead of the human-readable initialization summary.
</ParamField>

<ParamField path="-debug" type="boolean" default="false">
  Log every store request with network call details, timing, and sizes.
</ParamField>

### S3-Specific Flags

<ParamField path="-s3-endpoint" type="string" default="" env="CLOUDSTIC_S3_ENDPOINT">
  S3-compatible endpoint URL (for MinIO, Cloudflare R2, DigitalOcean Spaces, etc.).
</ParamField>

<ParamField path="-s3-region" type="string" default="us-east-1" env="CLOUDSTIC_S3_REGION">
  S3 region.
</ParamField>

<ParamField path="-s3-access-key" type="string" default="" env="AWS_ACCESS_KEY_ID">
  S3 access key ID.
</ParamField>

<ParamField path="-s3-secret-key" type="string" default="" env="AWS_SECRET_ACCESS_KEY">
  S3 secret access key.
</ParamField>

### SFTP Store Credentials

<ParamField path="-store-sftp-password" type="string" default="" env="CLOUDSTIC_STORE_SFTP_PASSWORD">
  SFTP store password.
</ParamField>

<ParamField path="-store-sftp-key" type="string" default="" env="CLOUDSTIC_STORE_SFTP_KEY">
  Path to SSH private key for SFTP store authentication.
</ParamField>

<ParamField path="-store-sftp-known-hosts" type="string" default="" env="CLOUDSTIC_STORE_SFTP_KNOWN_HOSTS">
  Path to custom `known_hosts` file for host key validation.
</ParamField>

<ParamField path="-store-sftp-insecure" type="boolean" default="false" env="CLOUDSTIC_STORE_SFTP_INSECURE">
  Skip host key validation (INSECURE).
</ParamField>

### Backblaze B2 Flags

<ParamField path="-b2-key-id" type="string" default="" env="B2_KEY_ID">
  Backblaze B2 application key ID.
</ParamField>

<ParamField path="-b2-app-key" type="string" default="" env="B2_APP_KEY">
  Backblaze B2 application key.
</ParamField>

## Examples

### Local Repository with Password

```bash theme={null}
cloudstic init -password "my-secure-passphrase"
```

### S3 Repository with Recovery Key

```bash theme={null}
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

```bash theme={null}
cloudstic init \
  -store s3:my-backups \
  -s3-endpoint https://minio.example.com \
  -s3-region us-east-1 \
  -password "my-secure-passphrase"
```

### SFTP Repository

```bash theme={null}
cloudstic init \
  -store sftp://backupuser@backup.example.com/home/backupuser/cloudstic \
  -store-sftp-key ~/.ssh/id_rsa \
  -password "my-secure-passphrase"
```

### Backblaze B2

```bash theme={null}
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.

```bash theme={null}
# 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:

```bash theme={null}
openssl rand -hex 32
```

## Related Commands

* [cloudstic backup](/commands/backup): Create your first backup after initializing
* [cloudstic key add-recovery](/commands/key-add-recovery): Add a recovery key to an existing repository
* [cloudstic key passwd](/commands/key-passwd): Change the repository password
* [cloudstic check](/commands/check): Verify repository integrity