locutus

A simple, opinionated wrapper for the venerable BorgBackup.

Features

• Friendlier CLI: No need to remember archive names or full repo paths.
• Index-based archive access: Refer to backups by index (most recent is 0), or by name.
• Scriptable: All commands are suitable for cron or other automation.
• Transparent: Directly uses Borg; never hides or obfuscates underlying repo.  Backups can be fully managed by borg directly, made easier by sourcing locutus.rc in your shell.

---

Installation

Requires Python 3.11+, BorgBackup (CLI), and a UNIX-like OS.

From source

Clone the repo and install with uv or pip:

git clone https://github.com/figtree-dev/locutus.git
cd locutus
uv tool install .

For development/testing:

uv venv
uv source .venv/bin/activate
uv sync --extra dev

(See pyproject.toml for dev dependencies.)

---

Quick Start

1. Setup your backup environment

locutus init

• Prompts for your repo and passphrase, creates the rc file.
• Edit ~/.config/locutus/locutus.toml to set your include/exclude/prune rules.

2. Create a backup

locutus backup

3. List archives

locutus list

• Archives are in chronological order with reverse indexing, such as 1: ..., 0: ....

4. Mount an archive or the entire repo

locutus mount 0 ~/mnt/backup      # mount most recent archive
locutus mount ~/mnt/backup        # mount all archives

5. Restore files from an archive

locutus restore 0 ~/restore-dir

6. Unmount a mountpoint

locutus umount ~/mnt/backup

---

Configuration

• Main config: ~/.config/locutus/locutus.toml (edit by hand, see sample below)
• Profile/RC: ~/.config/locutus/locutus.rc (holds BORG_REPO and BORG_PASSPHRASE)

Sample locutus.toml:

[includes]
paths = [
    "/etc",
    "/home",
    "/var/www"
]

[excludes]
paths = [
    "*.cache",
    "/tmp",
    "/home/*/Downloads"
]

[prune]
keep_last    = 7
keep_daily   = 7
keep_weekly  = 4
keep_monthly = 6

[compact]
enabled = true

Sample locutus.rc:

export BORG_REPO="user@host:/path/to/repo"
export BORG_PASSPHRASE="your-strong-password"

---

Development

• Source code: src/locutus/

• Tests: test/

• Run tests:

  uv venv
  source .venv/bin/activate
  uv sync --extra dev
  pytest
  

• All CLI entry points are in main.py with subcommands for each workflow.

---

Limitations / Roadmap

• Linux/UNIX only (uses Borg and fusermount).
• No built-in scheduling (use cron/systemd).
• One config/profile at a time.

---

License

GPLv3 (see LICENSE)

---

Author

Alexander Wainwright (code@figtree.dev)

---

Pull requests welcome.