> ## 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.

# Using Profiles

> Save and reuse backup configurations with profiles, stores, and auth entries

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 |

```yaml profiles.yaml theme={null}
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
```

<Note>
  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`.
</Note>

## Quick Start with Profiles

<Steps>
  <Step title="Create a store">
    Define where your backups are stored:

    ```bash theme={null}
    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.
  </Step>

  <Step title="Create a profile">
    Link a source to your store:

    ```bash theme={null}
    cloudstic profile new \
      -name documents \
      -source local:~/Documents \
      -store-ref prod-s3
    ```
  </Step>

  <Step title="Run backups with your profile">
    ```bash theme={null}
    cloudstic backup -profile documents
    ```

    All flags from the profile (store, encryption, source) are applied automatically.
  </Step>
</Steps>

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

```bash theme={null}
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:

```bash theme={null}
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                             |

<Warning>
  Encryption secrets are **never stored in the YAML file**. Use secret references (`env://`, `keychain://`, `wincred://`, `secret-service://`) so only references are saved.
</Warning>

### List and Inspect Stores

```bash theme={null}
# 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

```bash theme={null}
cloudstic auth new \
  -name google-main \
  -provider google \
  -google-token-file ~/.config/cloudstic/tokens/google-main_token.json
```

### Run the OAuth Login Flow

```bash theme={null}
cloudstic auth login -name google-main
```

This opens your browser for OAuth authorization and saves the token to the configured file.

<Tip>
  Run `auth login` once per auth entry. The token is refreshed automatically on subsequent backups.
</Tip>

### List and Inspect Auth Entries

```bash theme={null}
# 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:

```bash theme={null}
# 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:

```bash theme={null}
# Add an exclusion to an existing profile
cloudstic profile new \
  -name documents \
  -exclude "*.log"
```

### List and Inspect Profiles

```bash theme={null}
# 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

```bash theme={null}
cloudstic backup -profile documents
```

### All Enabled Profiles

```bash theme={null}
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:

```bash theme={null}
# 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`:

```bash theme={null}
# 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:

```bash theme={null}
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:

```bash ~/bin/backup.sh theme={null}
#!/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:

```bash theme={null}
# 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:...
```

<Tip>
  Use `-all-profiles` in your automation scripts. Add or remove profiles from `profiles.yaml` without touching the backup script.
</Tip>

## Profiles File Format

The profiles file is a YAML file with three top-level maps:

```yaml profiles.yaml theme={null}
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

<CardGroup cols={2}>
  <Card title="Store Commands" icon="database" href="/commands/store-new">
    Create and manage stores
  </Card>

  <Card title="Auth Commands" icon="key" href="/commands/auth-new">
    Set up cloud authentication
  </Card>

  <Card title="Profile Commands" icon="id-card" href="/commands/profile-new">
    Create and manage profiles
  </Card>

  <Card title="Automation" icon="robot" href="/guides/automation">
    Automate backups with profiles
  </Card>
</CardGroup>