Skip to main content
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

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

​
-name
string
required
Store reference name. Used to link profiles to this store.
​
-uri
string
required
Store URI. Formats: local:<path>, s3:<bucket>[/<prefix>], b2:<bucket>[/<prefix>], sftp://[user@]host[:port]/<path>.

​
S3/S3-Compatible Options

​
-s3-region
string
S3 region (e.g., us-east-1, eu-west-1).
​
-s3-profile
string
AWS shared config profile name.
​
-s3-endpoint
string
S3-compatible endpoint URL (for MinIO, Cloudflare R2, etc.).
​
-s3-access-key
string
S3 static access key (stored directly in YAML).
​
-s3-secret-key
string
S3 static secret key (stored directly in YAML).
​
-s3-access-key-secret
string
Secret reference for S3 access key (for example env://AWS_ACCESS_KEY_ID, keychain://cloudstic/prod/s3-access-key).
​
-s3-secret-key-secret
string
Secret reference for S3 secret key (for example env://AWS_SECRET_ACCESS_KEY, keychain://cloudstic/prod/s3-secret-key).
​
-s3-access-key-env
string
Environment variable name for S3 access key. The env var is resolved at backup time.
​
-s3-secret-key-env
string
Environment variable name for S3 secret key. The env var is resolved at backup time.
​
-s3-profile-env
string
Environment variable name for AWS profile. The env var is resolved at backup time.

​
SFTP Store Options

​
-store-sftp-password
string
SFTP password (stored in YAML; prefer -store-sftp-password-env).
​
-store-sftp-key
string
Path to SFTP private key (stored directly in YAML).
​
-store-sftp-password-secret
string
Secret reference for SFTP password.
​
-store-sftp-key-secret
string
Secret reference for SFTP private key path.
​
-store-sftp-password-env
string
Environment variable name for SFTP password.
​
-store-sftp-key-env
string
Environment variable name for SFTP private key path.
​
-store-sftp-known-hosts
string
Path to custom known_hosts file for host key validation.
​
-store-sftp-insecure
boolean
Skip host key validation (INSECURE).

​
Encryption Options

​
-password-secret
string
Secret reference for repository password.
​
-encryption-key-secret
string
Secret reference for platform key (64-char hex).
​
-recovery-key-secret
string
Secret reference for recovery key mnemonic.
​
-password-env
string
Legacy env-var shortcut for repository password. Converted to password_secret: env://... when saved.
​
-encryption-key-env
string
Legacy env-var shortcut for platform key. Converted to encryption_key_secret: env://... when saved.
​
-recovery-key-env
string
Legacy env-var shortcut for recovery key. Converted to recovery_key_secret: env://... when saved.
​
-kms-key-arn
string
AWS KMS key ARN for envelope encryption. Stored directly (not a secret).
​
-kms-region
string
AWS KMS region.
​
-kms-endpoint
string
Custom AWS KMS endpoint URL.

​
General Options

​
-profiles-file
string
Path to the profiles YAML file.
​
--no-prompt
boolean
default:"false"
Disable interactive prompts. Missing required fields cause an error instead of prompting.

​
Examples

cloudstic store new \
  -name prod-s3 \
  -uri s3:my-bucket/backups \
  -s3-region eu-west-1 \
  -s3-profile prod

​
Interactive Store Initialization

In interactive mode (the default), after saving the basic store config, Cloudstic guides you through encryption configuration and store initialization.
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.

​
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 to run this configuration/ access validation on demand. Use cloudstic 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).
Use --no-prompt to skip interactive prompts in scripts. You can always run cloudstic store init <name> separately.

​
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