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.

Shell Completion¶

BorgBoi supports shell completion for its CLI. To enable it, run:

bb --install-completion

This modifies your shell RC file (.bashrc, .zshrc, etc.) to source the completion script. After restarting your shell (or sourcing your RC file), you'll have tab-completion for all commands and options.

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

logging:
  enabled: false
  level: info
  max_bytes: 10485760
  backup_count: 5

telemetry:
  enabled: false
  service_name: borgboi
  trace_endpoint: null
  export_logs: false
  logs_endpoint: null
  capture_tui: true

offline: false

Environment Variables¶

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

OpenTelemetry With docker-otel-lgtm¶

For local tracing with Tempo and optional log export to Loki, start docker-otel-lgtm and set the default OTLP environment variables:

export BORGBOI_TELEMETRY__ENABLED=true
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318

If you also want BorgBoi logs to be exported through the OpenTelemetry collector to Loki:

export BORGBOI_TELEMETRY__EXPORT_LOGS=true

docker-otel-lgtm serves Grafana at http://localhost:3000 with the default credentials admin / admin.

Sending Traces Directly to Another OTLP Endpoint¶

Set telemetry.trace_endpoint when traces should bypass the default OTEL_EXPORTER_OTLP_ENDPOINT value:

export BORGBOI_TELEMETRY__ENABLED=true
export BORGBOI_TELEMETRY__TRACE_ENDPOINT=http://tempo:4318/v1/traces
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf

Sending Logs Directly to Loki¶

Loki 3.x exposes a native OTLP logs endpoint at /otlp/v1/logs, so you can bypass the OpenTelemetry collector and push BorgBoi logs straight into Loki while keeping traces pointed at Tempo (or any other OTLP trace backend).

Set telemetry.logs_endpoint to Loki's OTLP logs URL and leave OTEL_EXPORTER_OTLP_ENDPOINT pointed at the trace backend:

export BORGBOI_TELEMETRY__ENABLED=true
export BORGBOI_TELEMETRY__EXPORT_LOGS=true
export BORGBOI_TELEMETRY__LOGS_ENDPOINT=http://loki:3100/otlp/v1/logs
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_ENDPOINT=http://tempo:4318

The resolved log records still carry the active trace_id and span_id, so Grafana's trace-to-logs correlation keeps working when you query Loki directly. Authentication headers for Loki (for example, Grafana Cloud multi-tenancy) can be supplied through the standard OTEL_EXPORTER_OTLP_LOGS_HEADERS environment variable, which the OTLP HTTP exporter reads automatically.

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.

Launch the TUI¶

Start the interactive terminal UI with:

bb tui

The TUI uses the same effective configuration as the CLI, including --offline, --debug, and BORGBOI_* environment variable overrides.

On the main screen, BorgBoi shows a repository table with each repo's name, hostname, last archive, and size.

Main TUI Keys¶

• q quits the application
• r refreshes the repository list
• c opens the full-screen config viewer
• e opens the excludes viewer and editor
• b opens the daily backup screen
• Enter or i opens the repository detail screen for the highlighted repository

Excludes Viewer Keys¶

Inside the excludes screen:

• Left and right arrow keys switch between the shared default excludes file and repo-specific tabs
• Ctrl+E enters or exits edit mode for the active file
• Ctrl+S saves the active file to disk
• Esc cancels editing or returns to the main screen

If a repo-specific excludes file does not exist, the screen shows that BorgBoi falls back to the shared default file. You can still create the missing file directly from the TUI by entering edit mode and saving it.

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

Update Repository Quota¶

Adjust the repository's configured storage cap when you need to raise or lower it:

bb repo set-quota --name my-docs-backup --quota 200G

The new quota must be at least as large as the repo's current on-disk size and no larger than the remaining disk headroom after Borg's reserved free space plus the repo's current size. Borg-style decimal quotas like 1.5T are supported.

List Archives¶

View all archives in a repository:

bb backup list --name my-docs-backup