> ## 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 store new

> Create or update a store entry in profiles.yaml

Create or update a named store entry in your profiles file. Stores define the storage backend (S3, local, SFTP) along with connection credentials and encryption settings.

Use `*_secret` flags for credentials whenever possible. They store secret references (`env://`, `keychain://`, `wincred://`, `secret-service://`) instead of secret values.

## Usage

```bash theme={null}
cloudstic store new [options]
```

In interactive mode, you'll be prompted for required fields and offered to initialize the store after saving.
When updating an existing store (with no override flags), Cloudstic prompts with the
current URI prefilled and asks whether to keep current encryption settings.

## Options

<ParamField path="-name" type="string" required>
  Store reference name. Used to link profiles to this store.
</ParamField>

<ParamField path="-uri" type="string" required>
  Store URI. Formats: `local:<path>`, `s3:<bucket>[/<prefix>]`, `b2:<bucket>[/<prefix>]`, `sftp://[user@]host[:port]/<path>`.
</ParamField>

### S3/S3-Compatible Options

<ParamField path="-s3-region" type="string">
  S3 region (e.g., `us-east-1`, `eu-west-1`).
</ParamField>

<ParamField path="-s3-profile" type="string">
  AWS shared config profile name.
</ParamField>

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

<ParamField path="-s3-access-key" type="string">
  S3 static access key (stored directly in YAML).
</ParamField>

<ParamField path="-s3-secret-key" type="string">
  S3 static secret key (stored directly in YAML).
</ParamField>

<ParamField path="-s3-access-key-secret" type="string">
  Secret reference for S3 access key (for example `env://AWS_ACCESS_KEY_ID`, `keychain://cloudstic/prod/s3-access-key`).
</ParamField>

<ParamField path="-s3-secret-key-secret" type="string">
  Secret reference for S3 secret key (for example `env://AWS_SECRET_ACCESS_KEY`, `keychain://cloudstic/prod/s3-secret-key`).
</ParamField>

<ParamField path="-s3-access-key-env" type="string">
  Environment variable name for S3 access key. The env var is resolved at backup time.
</ParamField>

<ParamField path="-s3-secret-key-env" type="string">
  Environment variable name for S3 secret key. The env var is resolved at backup time.
</ParamField>

<ParamField path="-s3-profile-env" type="string">
  Environment variable name for AWS profile. The env var is resolved at backup time.
</ParamField>

### SFTP Store Options

<ParamField path="-store-sftp-password" type="string">
  SFTP password (stored in YAML; prefer `-store-sftp-password-env`).
</ParamField>

<ParamField path="-store-sftp-key" type="string">
  Path to SFTP private key (stored directly in YAML).
</ParamField>

<ParamField path="-store-sftp-password-secret" type="string">
  Secret reference for SFTP password.
</ParamField>

<ParamField path="-store-sftp-key-secret" type="string">
  Secret reference for SFTP private key path.
</ParamField>

<ParamField path="-store-sftp-password-env" type="string">
  Environment variable name for SFTP password.
</ParamField>

<ParamField path="-store-sftp-key-env" type="string">
  Environment variable name for SFTP private key path.
</ParamField>

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

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

### Encryption Options

<ParamField path="-password-secret" type="string">
  Secret reference for repository password.
</ParamField>

<ParamField path="-encryption-key-secret" type="string">
  Secret reference for platform key (64-char hex).
</ParamField>

<ParamField path="-recovery-key-secret" type="string">
  Secret reference for recovery key mnemonic.
</ParamField>

<ParamField path="-password-env" type="string">
  Legacy env-var shortcut for repository password. Converted to `password_secret: env://...` when saved.
</ParamField>

<ParamField path="-encryption-key-env" type="string">
  Legacy env-var shortcut for platform key. Converted to `encryption_key_secret: env://...` when saved.
</ParamField>

<ParamField path="-recovery-key-env" type="string">
  Legacy env-var shortcut for recovery key. Converted to `recovery_key_secret: env://...` when saved.
</ParamField>

<ParamField path="-kms-key-arn" type="string">
  AWS KMS key ARN for envelope encryption. Stored directly (not a secret).
</ParamField>

<ParamField path="-kms-region" type="string">
  AWS KMS region.
</ParamField>

<ParamField path="-kms-endpoint" type="string">
  Custom AWS KMS endpoint URL.
</ParamField>

### General Options

<ParamField path="-profiles-file" type="string" env="CLOUDSTIC_PROFILES_FILE">
  Path to the profiles YAML file.
</ParamField>

<ParamField path="--no-prompt" type="boolean" default="false">
  Disable interactive prompts. Missing required fields cause an error instead of prompting.
</ParamField>

## Examples

<CodeGroup>
  ```bash S3 with AWS Profile theme={null}
  cloudstic store new \
    -name prod-s3 \
    -uri s3:my-bucket/backups \
    -s3-region eu-west-1 \
    -s3-profile prod
  ```

  ```bash S3 with Secret References theme={null}
  cloudstic store new \
    -name ci-s3 \
    -uri s3:ci-bucket/backups \
    -s3-region us-east-1 \
    -s3-access-key-secret env://AWS_ACCESS_KEY_ID \
    -s3-secret-key-secret keychain://cloudstic/ci/s3-secret-key
  ```

  ```bash With Encryption theme={null}
  cloudstic store new \
    -name encrypted-s3 \
    -uri s3:secure-bucket/backups \
    -password-secret keychain://cloudstic/prod/repo-password \
    -kms-key-arn arn:aws:kms:us-east-1:123456:key/abcd \
    -kms-region us-east-1
  ```

  ```bash Local Store theme={null}
  cloudstic store new \
    -name local-backup \
    -uri local:/mnt/backup/cloudstic
  ```

  ```bash SFTP Store theme={null}
  cloudstic store new \
    -name remote-sftp \
    -uri sftp://backup@server.example.com/backups \
    -store-sftp-key-secret env://SFTP_KEY_PATH
  ```
</CodeGroup>

## Interactive Store Initialization

In interactive mode (the default), after saving the basic store config, Cloudstic guides you through encryption configuration and store initialization.

<Note>
  Store names must match `^[a-zA-Z0-9][a-zA-Z0-9._-]*$` (start with an alphanumeric character, then alphanumerics, dots, underscores, or hyphens). Store URIs must use a valid scheme: `local`, `s3`, `b2`, or `sftp`.
</Note>

### Step 1: Encryption Configuration

If no encryption flags are provided on the command line, you are prompted to choose an encryption method:

```
Select encryption method:
  1) Password (recommended for interactive use)
  2) Platform key (recommended for automation/CI)
  3) AWS KMS key (enterprise)
  4) No encryption (not recommended)
Choice [1]:
```

Each option prompts for the relevant settings.

* **Password** and **Platform key** prompt where to store the secret:
  * Environment variable reference (`env://...`)
  * Native secret store reference:
    * macOS: `keychain://service/account`
    * Windows: `wincred://target`
    * Linux: `secret-service://collection/item`
* **AWS KMS key**: prompts for the KMS key ARN and AWS region.
* **No encryption**: skips encryption setup. Data is stored unencrypted.

If you choose a native secret store option, Cloudstic prompts for the secret
value and stores it in the OS secret manager. `profiles.yaml` stores only the
reference.

The encryption configuration is saved to `profiles.yaml` alongside the store entry.

### Step 2: Connectivity Check and Init

After saving, Cloudstic checks whether the store is accessible and initialized:

```
Store "prod-s3" saved in ~/.config/cloudstic/profiles.yaml
Store is accessible but not yet initialized.
Initialize it now? [Y/n]: y
Repository initialized (encrypted: true).
```

If the store is already initialized:

```
Store "prod-s3" saved in ~/.config/cloudstic/profiles.yaml
Store is already initialized and accessible.
```

For encrypted repositories, Cloudstic also verifies that the configured
credentials can unlock the repository.

Use [`cloudstic store verify`](/commands/store-verify) to run this configuration/
access validation on demand. Use [`cloudstic check`](/commands/check) for full
repository integrity verification.

### Full interactive example (macOS Keychain)

```
$ cloudstic store new
Store name: prod-s3
Store URI: s3:my-bucket/backups
S3 region: eu-west-1
S3 profile: prod

Select encryption method:
  1) Password (recommended for interactive use)
  2) Platform key (recommended for automation/CI)
  3) AWS KMS key (enterprise)
  4) No encryption (not recommended)
Choice [1]: 1
Where should repository password be stored?
  1) Environment variable (env://)
  2) macOS Keychain (keychain://)
Select option number [1]: 2
Keychain service [cloudstic/store/prod-s3]:
Keychain account [password]:
Secret value: [hidden]

Store "prod-s3" saved in ~/.config/cloudstic/profiles.yaml
Store is accessible but not yet initialized.
Initialize it now? [Y/n]: y
Repository initialized (encrypted: true).
```

<Tip>
  Use `--no-prompt` to skip interactive prompts in scripts. You can always run `cloudstic store init <name>` separately.
</Tip>

## Secret references

Stores should use secret references for credentials and encryption material:

* `env://VAR_NAME`
* `keychain://service/account`
* `wincred://target`
* `secret-service://collection/item`

This means:

* `profiles.yaml` stays free of raw secret values
* You can move secrets between env vars and native secret stores without changing command flows
* Secret rotation can happen in your secret backend without rewriting profile structure

## See Also

* [cloudstic store list](/commands/store-list): List configured stores
* [cloudstic store show](/commands/store-show): Show store details
* [cloudstic store verify](/commands/store-verify): Validate store credentials and access
* [cloudstic store init](/commands/store-init): Initialize a configured store by reference
* [cloudstic profile new](/commands/profile-new): Create a profile that references a store
* [Using Profiles](/guides/profiles): Complete profiles guide