Skip to main content
Profiles let you save your backup configuration once and reuse it with a single flag. Instead of repeating -store, -source, credentials, and encryption flags on every command, define a profile and run cloudstic backup -profile my-backup.

​
How Profiles Work

Cloudstic’s configuration lives in a single YAML file (profiles.yaml) with three sections:
SectionPurpose
storesNamed storage backends (URI, credentials, encryption)
authNamed cloud auth entries (OAuth tokens, credentials)
profilesNamed backup configurations that reference a store and optionally an auth
profiles.yaml
version: 1
stores:
  prod-s3:
    uri: s3:my-bucket/backups
    s3_region: eu-west-1
    s3_profile: prod
    password_secret: keychain://cloudstic/prod/repo-password
auth:
  google-main:
    provider: google
    google_token_file: ~/.config/cloudstic/tokens/google-main_token.json
profiles:
  documents:
    source: local:~/Documents
    store: prod-s3
  gdrive:
    source: gdrive-changes
    store: prod-s3
    auth_ref: google-main
The profiles file location defaults to ~/.config/cloudstic/profiles.yaml (Linux/macOS) or %APPDATA%\cloudstic\profiles.yaml (Windows). Override with -profiles-file or CLOUDSTIC_PROFILES_FILE.

​
Quick Start with Profiles

1

Create a store

Define where your backups are stored:
cloudstic store new \
  -name prod-s3 \
  -uri s3:my-bucket/backups \
  -s3-region eu-west-1 \
  -password-env BACKUP_PASSWORD
If the store hasn’t been initialized yet, you’ll be prompted to do so.
2

Create a profile

Link a source to your store:
cloudstic profile new \
  -name documents \
  -source local:~/Documents \
  -store-ref prod-s3
3

Run backups with your profile

cloudstic backup -profile documents
All flags from the profile (store, encryption, source) are applied automatically.

​
Managing Stores

Stores define the storage backend and its credentials. Secrets use env var indirection. You store the name of the environment variable, not the secret itself.

​
Create a Store

cloudstic store new \
  -name prod-s3 \
  -uri s3:my-bucket/backups \
  -s3-region eu-west-1 \
  -s3-profile prod
In interactive mode, you’ll be prompted for missing fields and offered to initialize the store: 
Store "prod-s3" saved in ~/.config/cloudstic/profiles.yaml
Store is accessible but not yet initialized.
Initialize it now? [Y/n]:

​
Store Encryption Settings

Stores can carry encryption configuration so you don’t need to pass it on every command: 
cloudstic store new \
  -name encrypted-s3 \
  -uri s3:secure-bucket/backups \
  -s3-region us-east-1 \
  -password-secret keychain://cloudstic/prod/repo-password \
  -kms-key-arn arn:aws:kms:us-east-1:123456:key/abcd
FlagPurpose
-password-secretSecret reference containing the repository password
-encryption-key-secretSecret reference containing the platform key (hex)
-recovery-key-secretSecret reference containing the recovery mnemonic
-kms-key-arnAWS KMS key ARN (stored directly, not a secret)
-kms-regionAWS KMS region
-kms-endpointCustom KMS endpoint URL
Encryption secrets are never stored in the YAML file. Use secret references (env://, keychain://, wincred://, secret-service://) so only references are saved.

​
List and Inspect Stores

# List all stores
cloudstic store list

# Show details for a specific store
cloudstic store show prod-s3
Example output: 
store: prod-s3
  uri: s3:my-bucket/backups
  auth_mode: aws-shared-profile
  s3_region: eu-west-1
  s3_profile: prod
  password_secret: keychain://cloudstic/prod/repo-password
  used_by: [documents gdrive]

​
Managing Auth Entries

Auth entries store cloud OAuth credentials (Google Drive, OneDrive) so they can be shared across multiple profiles.

​
Create an Auth Entry

cloudstic auth new \
  -name google-main \
  -provider google \
  -google-token-file ~/.config/cloudstic/tokens/google-main_token.json

​
Run the OAuth Login Flow

cloudstic auth login -name google-main
This opens your browser for OAuth authorization and saves the token to the configured file.
Run auth login once per auth entry. The token is refreshed automatically on subsequent backups.

​
List and Inspect Auth Entries

# List all auth entries
cloudstic auth list

# Show details
cloudstic auth show google-main

​
Managing Profiles

​
Create a Profile

A profile must always reference a store. For cloud sources, an auth entry is also required: 
# Local source
cloudstic profile new \
  -name documents \
  -source local:~/Documents \
  -store-ref prod-s3

# Cloud source (requires auth)
cloudstic profile new \
  -name gdrive \
  -source gdrive-changes \
  -store-ref prod-s3 \
  -auth-ref google-main
In interactive mode, if you omit -store-ref or -auth-ref, you’ll be prompted to select an existing one or create a new one. If you create a new store from profile new, Cloudstic also runs the store encryption setup flow immediately (same as store new).

​
Profile Options

FlagPurpose
-source <uri>Source URI (local, sftp, gdrive, onedrive)
-store-ref <name>Reference an existing store
-store <uri>Create/update a store inline
-auth-ref <name>Reference an existing auth entry
-tag <tag>Tag for snapshots (repeatable)
-exclude <pattern>Exclude pattern (repeatable)
-exclude-file <path>Path to exclude file
-skip-native-filesSkip Google-native files
-volume-uuid <uuid>Override local volume UUID

​
Edit an Existing Profile

Run profile new with the same name to update it. Existing values are preserved unless you override them: 
# Add an exclusion to an existing profile
cloudstic profile new \
  -name documents \
  -exclude "*.log"

​
List and Inspect Profiles

# List all stores, auth entries, and profiles
cloudstic profile list

# Show a specific profile with resolved references
cloudstic profile show documents

​
Running Backups with Profiles

​
Single Profile

cloudstic backup -profile documents

​
All Enabled Profiles

cloudstic backup -all-profiles
This runs each profile sequentially, using its own store and auth configuration. A summary is printed after all profiles complete.

​
Override Profile Settings

CLI flags take precedence over profile values: 
# Use the profile's store but override the source
cloudstic backup -profile documents -source local:~/Downloads

# Force a different store
cloudstic backup -profile documents -store local:./test-store

​
Using Profiles for Other Commands

Any command that accepts global flags (-store, -s3-region, etc.) also works with -profile: 
# List snapshots from a profile's store
cloudstic list -profile documents

# Restore from a profile's store
cloudstic restore -profile documents

# Verify store config/credentials for a named store entry
cloudstic store verify prod-s3

# Initialize a configured store later (if creation-time init was skipped/failed)
cloudstic store init prod-s3

# Check integrity of a profile's store
cloudstic check -profile documents

# Apply retention policy
cloudstic forget -profile documents -keep-daily 30 -keep-weekly 8 -prune
cloudstic store verify checks credential resolution and store access for a store entry. cloudstic store init performs initialization by store reference. cloudstic check -profile ... verifies repository integrity.

​
Non-Interactive Mode

Use --no-prompt to disable all interactive prompts. This is useful for scripts and CI/CD pipelines: 
cloudstic store new --no-prompt \
  -name ci-store \
  -uri s3:ci-bucket/backups \
  -s3-region us-east-1

cloudstic profile new --no-prompt \
  -name ci-backup \
  -source local:. \
  -store-ref ci-store
Without --no-prompt, missing required fields would trigger interactive prompts. With it, missing fields cause an error instead.

​
Profile-Based Automation

Profiles simplify automated backups significantly. Instead of managing environment variables and long flag lists, your cron job becomes:
~/bin/backup.sh
#!/bin/bash
set -euo pipefail

# Example: env-backed secret refs
export CLOUDSTIC_PASSWORD="your passphrase"

# Back up all profiles
cloudstic backup -all-profiles --no-prompt

# Apply retention to each profile
for profile in documents gdrive; do
  cloudstic forget -profile "$profile" \
    -keep-daily 30 -keep-weekly 8 -keep-monthly 12 \
    -prune --no-prompt
done
Compare this to the equivalent without profiles: 
# Without profiles: every detail on every command
cloudstic backup \
  -source local:~/Documents \
  -store s3:my-bucket/backups \
  -s3-region eu-west-1 \
  -s3-profile prod \
  -password "..." \
  -kms-key-arn arn:aws:kms:...
Use -all-profiles in your automation scripts. Add or remove profiles from profiles.yaml without touching the backup script.

​
Profiles File Format

The profiles file is a YAML file with three top-level maps:
profiles.yaml
version: 1

stores:
  <store-name>:
    uri: <store-uri>                   # required
    s3_region: <region>                # S3 only
    s3_profile: <aws-profile>          # S3 only
    s3_endpoint: <url>                 # S3-compatible only
    s3_access_key_secret: <secret-ref> # env://, keychain://, wincred://, secret-service://
    s3_secret_key_secret: <secret-ref>
    store_sftp_password_secret: <secret-ref> # SFTP only
    store_sftp_key_secret: <secret-ref>
    password_secret: <secret-ref>      # encryption
    encryption_key_secret: <secret-ref>
    recovery_key_secret: <secret-ref>
    kms_key_arn: <arn>                 # stored directly
    kms_region: <region>
    kms_endpoint: <url>

auth:
  <auth-name>:
    provider: google | onedrive
    google_credentials: <path>         # google only
    google_token_file: <path>
    onedrive_client_id: <id>           # onedrive only
    onedrive_token_file: <path>

profiles:
  <profile-name>:
    source: <source-uri>               # required
    store: <store-name>                # required (references stores section)
    auth_ref: <auth-name>              # optional (references auth section)
    tags: [tag1, tag2]
    excludes: [pattern1, pattern2]
    exclude_file: <path>
    skip_native_files: true|false
    volume_uuid: <uuid>
    enabled: true|false                # default: true

​
Next Steps

Store Commands

Create and manage stores

Auth Commands

Set up cloud authentication

Profile Commands

Create and manage profiles

Automation

Automate backups with profiles