Using Profiles - Cloudstic CLI

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:

Section	Purpose
stores	Named storage backends (URI, credentials, encryption)
auth	Named cloud auth entries (OAuth tokens, credentials)
profiles	Named 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

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.

Create a profile

Link a source to your store:

cloudstic profile new \
  -name documents \
  -source local:~/Documents \
  -store-ref prod-s3

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

Flag	Purpose
`-password-secret`	Secret reference containing the repository password
`-encryption-key-secret`	Secret reference containing the platform key (hex)
`-recovery-key-secret`	Secret reference containing the recovery mnemonic
`-kms-key-arn`	AWS KMS key ARN (stored directly, not a secret)
`-kms-region`	AWS KMS region
`-kms-endpoint`	Custom 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

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

Flag	Purpose
`-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-files`	Skip 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

​How Profiles Work

​Quick Start with Profiles

​Managing Stores

​Create a Store

​Store Encryption Settings

​List and Inspect Stores

​Managing Auth Entries

​Create an Auth Entry

​Run the OAuth Login Flow

​List and Inspect Auth Entries

​Managing Profiles

​Create a Profile

​Profile Options

​Edit an Existing Profile

​List and Inspect Profiles

​Running Backups with Profiles

​Single Profile

​All Enabled Profiles

​Override Profile Settings

​Using Profiles for Other Commands

​Non-Interactive Mode

​Profile-Based Automation

​Profiles File Format

​Next Steps

Store Commands

Auth Commands

Profile Commands

Automation

How Profiles Work

Quick Start with Profiles

Managing Stores

Create a Store

Store Encryption Settings

List and Inspect Stores

Managing Auth Entries

Create an Auth Entry

Run the OAuth Login Flow

List and Inspect Auth Entries

Managing Profiles

Create a Profile

Profile Options

Edit an Existing Profile

List and Inspect Profiles

Running Backups with Profiles

Single Profile

All Enabled Profiles

Override Profile Settings

Using Profiles for Other Commands

Non-Interactive Mode

Profile-Based Automation

Profiles File Format

Next Steps