cloudstic store new

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

string

required

Store reference name. Used to link profiles to this store.

string

required

Store URI. Formats: local:<path>, s3:<bucket>[/<prefix>], b2:<bucket>[/<prefix>], sftp://[user@]host[:port]/<path>.

S3/S3-Compatible Options

string

S3 region (e.g., us-east-1, eu-west-1).

string

AWS shared config profile name.

string

S3-compatible endpoint URL (for MinIO, Cloudflare R2, etc.).

string

S3 static access key (stored directly in YAML).

string

S3 static secret key (stored directly in YAML).

string

Secret reference for S3 access key (for example env://AWS_ACCESS_KEY_ID, keychain://cloudstic/prod/s3-access-key).

string

Secret reference for S3 secret key (for example env://AWS_SECRET_ACCESS_KEY, keychain://cloudstic/prod/s3-secret-key).

string

Environment variable name for S3 access key. The env var is resolved at backup time.

string

Environment variable name for S3 secret key. The env var is resolved at backup time.

string

Environment variable name for AWS profile. The env var is resolved at backup time.

Backblaze B2 Options

string

B2 application key ID (stored directly in YAML).

string

B2 application key (stored directly in YAML).

string

Secret reference for the B2 key ID (for example env://B2_KEY_ID, keychain://cloudstic/prod/b2-key-id).

string

Secret reference for the B2 application key (for example env://B2_APP_KEY, keychain://cloudstic/prod/b2-app-key).

SFTP Store Options

string

SFTP password (stored in YAML; prefer -store-sftp-password-env).

string

Path to SFTP private key (stored directly in YAML).

string

Secret reference for SFTP password.

string

Secret reference for SFTP private key path.

string

Environment variable name for SFTP password.

string

Environment variable name for SFTP private key path.

string

Path to custom known_hosts file for host key validation.

boolean

Skip host key validation (INSECURE).

Encryption Options

string

Secret reference for repository password.

string

Secret reference for platform key (64-char hex).

string

Secret reference for recovery key mnemonic.

string

Legacy env-var shortcut for repository password. Converted to password_secret: env://... when saved.

string

Legacy env-var shortcut for platform key. Converted to encryption_key_secret: env://... when saved.

string

Legacy env-var shortcut for recovery key. Converted to recovery_key_secret: env://... when saved.

string

AWS KMS key ARN for envelope encryption. Stored directly (not a secret).

string

AWS KMS region.

string

Custom AWS KMS endpoint URL.

General Options

string

Path to the profiles YAML file.

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

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

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

cloudstic store new \
  -name local-backup \
  -uri local:/mnt/backup/cloudstic

cloudstic store new \
  -name remote-sftp \
  -uri sftp://backup@server.example.com/backups \
  -store-sftp-key-secret env://SFTP_KEY_PATH

cloudstic store new \
  -name ci-b2 \
  -uri b2:ci-bucket/backups \
  -b2-key-id-secret env://B2_KEY_ID \
  -b2-app-key-secret keychain://cloudstic/ci/b2-app-key

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

Onboarding

Interactive Mode

Repository Management

Backup & Restore

Maintenance

Key Management

Configuration

Utilities

Usage

Options

S3/S3-Compatible Options

Backblaze B2 Options

SFTP Store Options

Encryption Options

General Options

Examples

Interactive Store Initialization

Step 1: Encryption Configuration

Step 2: Connectivity Check and Init

Full interactive example (macOS Keychain)

Secret references

See Also

​Usage

​Options

​S3/S3-Compatible Options

​Backblaze B2 Options

​SFTP Store Options

​Encryption Options

​General Options

​Examples

​Interactive Store Initialization

​Step 1: Encryption Configuration

​Step 2: Connectivity Check and Init

​Full interactive example (macOS Keychain)

​Secret references

​See Also

Usage

Options

S3/S3-Compatible Options

Backblaze B2 Options

SFTP Store Options

Encryption Options

General Options

Examples

Interactive Store Initialization

Step 1: Encryption Configuration

Step 2: Connectivity Check and Init

Full interactive example (macOS Keychain)

Secret references

See Also