Getting Started¶

Installation¶

BorgBoi isn't published to PyPI yet, so it is recommended to install it from the GitHub repo with uv.

uv tool install git+https://github.com/fullerzz/borgboi

Additionally, BorgBackup needs to be installed on your system for BorgBoi to work.

Read installation methods here: https://borgbackup.readthedocs.io/en/stable/installation.html.

Provision AWS Resources¶

For BorgBoi to function properly in online mode, it requires an S3 bucket and DynamoDB table.

Use the IAC present in the terraform directory to provision these resources on AWS with Terraform or OpenTofu.

The Terraform/OpenTofu configuration also provisions S3 Inventory for the backup bucket so bb s3 stats can report upcoming Intelligent-Tiering FA->IA transition estimates.

Configuration¶

BorgBoi uses a configuration file located at ~/.borgboi/config.yaml. You can view the current configuration with:

bb config show

You can inspect the current Cyclopts-generated help output at any time with:

bb --help
bb repo --help
bb backup run --help

For a complete reference of every field, environment variable, and allowed value, see User Configuration.

Configuration File¶

Create or edit ~/.borgboi/config.yaml:

aws:
  s3_bucket: my-borgboi-bucket
  dynamodb_repos_table: bb-repos
  region: us-west-1

borg:
  compression: zstd,6
  storage_quota: 100G
  retention:
    keep_daily: 7
    keep_weekly: 4
    keep_monthly: 6
    keep_yearly: 0

offline: false

Environment Variables¶

Configuration can be overridden using environment variables with the BORGBOI_ prefix:

AWS Credentials¶

Before running BorgBoi in online mode, make sure the shell BorgBoi runs in has access to AWS credentials with sufficient permissions for the DynamoDB table and S3 bucket.

Offline Mode¶

BorgBoi supports offline mode for users who prefer not to use AWS services or want to use BorgBoi without cloud dependencies.

Enabling Offline Mode¶

You can enable offline mode in three ways:

1. Configuration File: Set offline: true in ~/.borgboi/config.yaml
2. Environment Variable: Set BORGBOI_OFFLINE=1 in your environment
3. Command Flag: Add --offline before any BorgBoi subcommand, such as bb --offline repo list

How Offline Mode Works¶

In offline mode:

• Repository metadata is stored locally in ~/.borgboi/.database/borgboi.db instead of DynamoDB
• No S3 synchronization occurs during backups
• All Borg operations work normally (create, backup, extract, etc.)
• AWS credentials are not required

Offline Mode Limitations¶

• Repository restoration from S3 is not available
• Repository metadata is not shared across systems
• No cloud backup of repository metadata

Create a BorgBoi Repo¶

You can create a Borg repository with the following BorgBoi command:

bb repo create --path /opt/borg-repos/docs \
    --backup-target ~/Documents \
    --name my-docs-backup

Create an Exclusions File¶

Backup commands expect an exclusions file to exist before they run. Create a repository-specific file with:

bb exclusions create --path /opt/borg-repos/docs \
    --source ~/borgboi-excludes.txt

If you prefer a shared default file, place it at ~/.borgboi/excludes.txt.

Perform a Daily Backup¶

Run a daily backup with automatic pruning and compaction:

bb backup daily --name my-docs-backup

This command creates a new archive, prunes old archives based on retention policy, compacts the repository, and syncs to S3 (unless --no-s3-sync is specified or running in offline mode). You can also target the repository with --path.

If you want Borg's native streaming output instead of the default JSON-backed summary table, use:

bb backup run --name my-docs-backup --no-json

List Your Repositories¶

View all managed repositories:

bb repo list

View Repository Info¶

Get detailed information about a repository:

bb repo info --name my-docs-backup

List Archives¶

View all archives in a repository:

bb backup list --name my-docs-backup