BorgBoi is a CLI and TUI wrapper around BorgBackup for managing repositories, running recurring backups, and optionally syncing Borg repositories to AWS S3.
It layers a grouped CLI, a Textual TUI, YAML-based configuration, local metadata storage, and AWS integration on top of Borg so routine backup workflows are easier to run and inspect.
- Creates and manages Borg repositories from a single CLI.
- Runs daily backup workflows that create archives, prune old data, and compact repositories.
- Syncs repositories to S3 and restores them when cloud mode is enabled.
- Copies local repositories to mounted NFS or SMB storage with
rsync. - Supports offline mode with local SQLite-backed metadata storage and no AWS dependency.
- Stores repository passphrases in per-repo files under
~/.borgboi/passphrases/. - Exposes a Cyclopts-powered CLI with grouped subcommands for repository, backup, S3, exclusions, and config workflows.
- Includes a Textual TUI for browsing repositories, opening a full-screen config viewer, and viewing or editing shared and repo-specific excludes files.
- Python 3.12 or newer
- BorgBackup installed and available in
PATH rsyncinstalled and available inPATHif you want to copy repositories to mounted NFS or SMB drives- AWS credentials with access to your S3 bucket and DynamoDB tables if you want online mode
Important
BorgBoi wraps BorgBackup, but does not install Borg itself. Install BorgBackup separately before running repository or backup commands.
BorgBoi is not currently published to PyPI. The recommended install path is with uv:
uv tool install git+https://github.com/fullerzz/borgboiThe installed CLI is available as either bb or borgboi.
Inspect the effective configuration:
bb config showExplore the generated help and version output:
bb --help
bb versionLaunch the interactive dashboard:
bb tuiCreate a repository:
bb repo create \
--path /opt/borg-repos/docs \
--backup-target ~/Documents \
--name my-docs-backupCreate an exclusions file before running backups:
bb exclusions create \
--path /opt/borg-repos/docs \
--source ~/borgboi-excludes.txtRun the daily backup workflow:
bb backup daily --name my-docs-backupPreview copying the repository to a mounted NAS or file share:
bb repo rsync --name my-docs-backup --destination /Volumes/Backups/my-docs-backup --dry-runInspect repositories and archives:
bb repo list
bb backup list --name my-docs-backup
bb backup diff --name my-docs-backup
bb repo info --name my-docs-backupIn its default online mode, BorgBoi uses AWS services for metadata and repository synchronization:
- DynamoDB stores repository metadata.
- S3 stores synced Borg repository data.
- AWS credentials are required for S3 and DynamoDB operations.
Offline mode disables AWS usage and keeps metadata locally in SQLite while preserving the local Borg workflow.
Note
Offline mode skips AWS-backed features like S3 sync and restore. Use online mode when you want cloud replication, and offline mode when you want the local Borg workflow without AWS dependencies.
Enable offline mode with any of these options:
- Set
offline: truein~/.borgboi/config.yaml - Export
BORGBOI_OFFLINE=1 - Pass
--offlineto a BorgBoi command
Example:
export BORGBOI_OFFLINE=1
bb repo create --path /opt/borg-repos/docs --backup-target ~/Documents --name my-docs-backup
bb backup daily --name my-docs-backup
# or apply it as a root CLI flag for one command
bb --offline repo listBorgBoi loads configuration from ~/.borgboi/config.yaml and environment variables prefixed with BORGBOI_.
- Nested configuration values use double underscores, such as
BORGBOI_AWS__S3_BUCKET. BORGBOI_HOMEchanges the base home directory used to resolve.borgboipaths.- When running under
sudo,SUDO_USERis used to resolve the original user's home directory when possible.
Use bb config show --format tree to inspect the merged effective configuration.
The primary command surface includes grouped subcommands plus root commands:
repofor repository lifecycle operationsbackupfor archive creation, listing, diff, restore, and deletions3for sync, restore, and bucket statsexclusionsfor managing backup exclusion filesconfigfor displaying effective configurationtuifor the interactive Textual dashboardversionfor printing the installed BorgBoi version
Every command also inherits the root-level --offline and --debug flags. Use bb --help, bb tui --help, or bb <group> <command> --help to inspect the current Cyclopts-generated help output.
Primary documentation is published at fullerzz.github.io/borgboi.
For local development:
uv sync
just test
just lint
just serve-docsNormal pytest runs use pytest-xdist and fan out across local CPUs by default. Snapshot maintenance commands must stay single-process because inline-snapshot cannot update snapshots while xdist is active, so use the dedicated just snapshot-* recipes for those workflows.