{"id":30523950,"url":"https://github.com/fullerzz/borgboi","last_synced_at":"2026-05-29T05:01:25.163Z","repository":{"id":271037975,"uuid":"912216392","full_name":"fullerzz/borgboi","owner":"fullerzz","description":"Wrapper around Borg for to taking backups of my system and syncing with S3.","archived":false,"fork":false,"pushed_at":"2026-05-18T17:33:36.000Z","size":3055,"stargazers_count":1,"open_issues_count":7,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-18T19:34:11.595Z","etag":null,"topics":["backup","borg","borgbackup","click","python","s3"],"latest_commit_sha":null,"homepage":"https://fullerzz.github.io/borgboi/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fullerzz.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-01-04T23:46:20.000Z","updated_at":"2026-05-13T03:35:21.000Z","dependencies_parsed_at":"2026-02-25T02:00:31.293Z","dependency_job_id":null,"html_url":"https://github.com/fullerzz/borgboi","commit_stats":null,"previous_names":["fullerzz/borgboi"],"tags_count":72,"template":false,"template_full_name":null,"purl":"pkg:github/fullerzz/borgboi","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fullerzz%2Fborgboi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fullerzz%2Fborgboi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fullerzz%2Fborgboi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fullerzz%2Fborgboi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fullerzz","download_url":"https://codeload.github.com/fullerzz/borgboi/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fullerzz%2Fborgboi/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33637485,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-29T02:00:06.066Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["backup","borg","borgbackup","click","python","s3"],"created_at":"2025-08-26T20:52:10.888Z","updated_at":"2026-05-29T05:01:25.157Z","avatar_url":"https://github.com/fullerzz.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# BorgBoi 👦🏼\n\nBorgBoi is a CLI and TUI wrapper around [BorgBackup](https://borgbackup.readthedocs.io/en/stable/index.html) for managing repositories, running recurring backups, and optionally syncing Borg repositories to AWS S3.\n\nIt 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.\n\n\u003cimg src=\"docs/images/borgboi_logo.svg\" alt=\"BorgBoi logo\" width=\"400\" /\u003e\n\n## What It Does\n\n- Creates and manages Borg repositories from a single CLI.\n- Runs daily backup workflows that create archives, prune old data, and compact repositories.\n- Syncs repositories to S3 and restores them when cloud mode is enabled.\n- Copies local repositories to mounted NFS or SMB storage with `rsync`.\n- Supports offline mode with local SQLite-backed metadata storage and no AWS dependency.\n- Stores repository passphrases in per-repo files under `~/.borgboi/passphrases/`.\n- Exposes a Cyclopts-powered CLI with grouped subcommands for repository, backup, S3, exclusions, and config workflows.\n- Includes a Textual TUI for browsing repositories, opening a full-screen config viewer, and viewing or editing shared and repo-specific excludes files.\n\n## Prerequisites\n\n- Python 3.12 or newer\n- [BorgBackup](https://borgbackup.readthedocs.io/en/stable/installation.html) installed and available in `PATH`\n- `rsync` installed and available in `PATH` if you want to copy repositories to mounted NFS or SMB drives\n- AWS credentials with access to your S3 bucket and DynamoDB tables if you want online mode\n\n\u003e [!IMPORTANT]\n\u003e BorgBoi wraps BorgBackup, but does not install Borg itself. Install BorgBackup separately before running repository or backup commands.\n\n## Installation\n\nBorgBoi is not currently published to PyPI. The recommended install path is with [`uv`](https://docs.astral.sh/uv/):\n\n```bash\nuv tool install git+https://github.com/fullerzz/borgboi\n```\n\nThe installed CLI is available as either `bb` or `borgboi`.\n\n## Quick Start\n\nInspect the effective configuration:\n\n```bash\nbb config show\n```\n\nExplore the generated help and version output:\n\n```bash\nbb --help\nbb version\n```\n\nLaunch the interactive dashboard:\n\n```bash\nbb tui\n```\n\nCreate a repository:\n\n```bash\nbb repo create \\\n\t--path /opt/borg-repos/docs \\\n\t--backup-target ~/Documents \\\n\t--name my-docs-backup\n```\n\nCreate an exclusions file before running backups:\n\n```bash\nbb exclusions create \\\n\t--path /opt/borg-repos/docs \\\n\t--source ~/borgboi-excludes.txt\n```\n\nRun the daily backup workflow:\n\n```bash\nbb backup daily --name my-docs-backup\n```\n\nPreview copying the repository to a mounted NAS or file share:\n\n```bash\nbb repo rsync --name my-docs-backup --destination /Volumes/Backups/my-docs-backup --dry-run\n```\n\nInspect repositories and archives:\n\n```bash\nbb repo list\nbb backup list --name my-docs-backup\nbb backup diff --name my-docs-backup\nbb repo info --name my-docs-backup\n```\n\n## Cloud And Offline Modes\n\nIn its default online mode, BorgBoi uses AWS services for metadata and repository synchronization:\n\n- DynamoDB stores repository metadata.\n- S3 stores synced Borg repository data.\n- AWS credentials are required for S3 and DynamoDB operations.\n\nOffline mode disables AWS usage and keeps metadata locally in SQLite while preserving the local Borg workflow.\n\n\u003e [!NOTE]\n\u003e 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.\n\nEnable offline mode with any of these options:\n\n- Set `offline: true` in `~/.borgboi/config.yaml`\n- Export `BORGBOI_OFFLINE=1`\n- Pass `--offline` to a BorgBoi command\n\nExample:\n\n```bash\nexport BORGBOI_OFFLINE=1\nbb repo create --path /opt/borg-repos/docs --backup-target ~/Documents --name my-docs-backup\nbb backup daily --name my-docs-backup\n\n# or apply it as a root CLI flag for one command\nbb --offline repo list\n```\n\n## Configuration\n\nBorgBoi loads configuration from `~/.borgboi/config.yaml` and environment variables prefixed with `BORGBOI_`.\n\n- Nested configuration values use double underscores, such as `BORGBOI_AWS__S3_BUCKET`.\n- `BORGBOI_HOME` changes the base home directory used to resolve `.borgboi` paths.\n- When running under `sudo`, `SUDO_USER` is used to resolve the original user's home directory when possible.\n\nUse `bb config show --format tree` to inspect the merged effective configuration.\n\n## Command Surface\n\nThe primary command surface includes grouped subcommands plus root commands:\n\n- `repo` for repository lifecycle operations\n- `backup` for archive creation, listing, diff, restore, and deletion\n- `s3` for sync, restore, and bucket stats\n- `exclusions` for managing backup exclusion files\n- `config` for displaying effective configuration\n- `tui` for the interactive Textual dashboard\n- `version` for printing the installed BorgBoi version\n\nEvery command also inherits the root-level `--offline` and `--debug` flags. Use `bb --help`, `bb tui --help`, or `bb \u003cgroup\u003e \u003ccommand\u003e --help` to inspect the current Cyclopts-generated help output.\n\n## Documentation\n\nPrimary documentation is published at [fullerzz.github.io/borgboi](https://fullerzz.github.io/borgboi/).\n\n- [Docs Home](https://fullerzz.github.io/borgboi/)\n- [Getting Started](https://fullerzz.github.io/borgboi/pages/getting-started/)\n- [Commands Reference](https://fullerzz.github.io/borgboi/pages/commands/)\n- [TUI Guide](https://fullerzz.github.io/borgboi/pages/tui/)\n- [User Configuration](https://fullerzz.github.io/borgboi/pages/user-configuration/)\n- [SQLite Database](https://fullerzz.github.io/borgboi/pages/sqlite-database/)\n\n## Development\n\nFor local development:\n\n```bash\nuv sync\njust test\njust lint\njust serve-docs\n```\n\nNormal 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.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffullerzz%2Fborgboi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffullerzz%2Fborgboi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffullerzz%2Fborgboi/lists"}