User Configuration¶

This page documents every user-facing BorgBoi configuration field, its default, and its allowed values.

Where Configuration Comes From¶

BorgBoi loads configuration from:

1. Defaults defined in code
2. ~/.borgboi/config.yaml (or BORGBOI_HOME/.borgboi/config.yaml)
3. BORGBOI_* environment variable overrides
4. CLI flags for --offline and --debug (for command execution)

Default config.yaml¶

aws:
  dynamodb_repos_table: bb-repos
  dynamodb_archives_table: bb-archives
  s3_bucket: bb-backups
  region: us-west-1

borg:
  executable_path: borg
  default_repo_path: ~/.borgboi/repositories
  compression: zstd,6
  checkpoint_interval: 900
  storage_quota: 100G
  additional_free_space: 2G
  retention:
    keep_daily: 7
    keep_weekly: 4
    keep_monthly: 6
    keep_yearly: 0

ui:
  theme: catppuccin
  show_progress: true
  color_output: true
  table_style: rounded

offline: false
debug: false

Load Flow With Environment Variables¶

flowchart TD
    A[Start get_config] --> B[Resolve home directory]
    B --> C{BORGBOI_HOME set?}
    C -- Yes --> D[Use BORGBOI_HOME]
    C -- No --> E{SUDO_USER set and home exists?}
    E -- Yes --> F[Use sudo user's home]
    E -- No --> G[Use current user home]
    D --> H[Compute config path]
    F --> H
    G --> H
    H --> I{config.yaml exists?}
    I -- No --> J[Write default config.yaml]
    I -- Yes --> K[Read YAML data]
    J --> K
    K --> L[Apply BORGBOI_* overrides]
    L --> M[Validate with Pydantic model]
    M --> N[Optional warning checks]
    N --> O[Return effective Config]

sequenceDiagram
    participant CLI as CLI Command
    participant CFG as get_config()
    participant YAML as config.yaml
    participant ENV as Environment

    CLI->>CFG: load config
    CFG->>YAML: read YAML (or create defaults)
    YAML-->>CFG: raw config dict
    loop for each known config path
        CFG->>ENV: read mapped BORGBOI_* variable
        alt env var is set
            ENV-->>CFG: string value
            CFG->>CFG: coerce bool/int when applicable
            CFG->>CFG: overwrite matching config path
        else env var not set
            ENV-->>CFG: None
        end
    end
    CFG-->>CLI: final merged config

Allowed Values By Field¶

Top-Level Fields¶

aws Section¶

borg Section¶

borg.retention subsection¶

ui Section¶

Environment Variables¶

Use BORGBOI_ variables to override config file values at runtime.

Home/Config Location¶

Field Override Variables¶

Environment Variable Coercion Rules¶

When overrides are read from environment variables:

• Boolean values are parsed from: true, 1, yes, false, 0, no (case-insensitive).
• Integer parsing is applied to:
• borg.checkpoint_interval
• borg.retention.keep_daily
• borg.retention.keep_weekly
• borg.retention.keep_monthly
• borg.retention.keep_yearly
• All other values remain strings.

Effective-Config Examples¶

# Override only offline mode and bucket for this shell
export BORGBOI_OFFLINE=1
export BORGBOI_AWS__S3_BUCKET=my-team-bucket

bb config show --format tree

# Use a custom BorgBoi home directory
export BORGBOI_HOME=/srv/borgboi-user
bb config show

# One-off command-level override (without exporting)
BORGBOI_BORG__COMPRESSION=zstd,9 bb backup daily --name my-docs-backup

Validation and Warnings¶

BorgBoi validates the final merged config and may warn (without failing) for:

• Missing Borg executable in PATH
• Invalid compression algorithm
• Negative retention values
• Negative checkpoint interval
• Missing required AWS fields while not in offline mode

Use this command to inspect the effective final values, including env-var sourced values:

bb config show --format tree