Restic Backups

YAML configuration and a Python CLI for running multiple restic repositories, with optional SOPS decryption. The package currently includes a complete macOS Voice Memos workflow for backup, transcription, summarisation, and speaker diarization.

Backup payloads, generated metadata, model caches, and restores are excluded from Git by a default-deny .gitignore.

Install

make install-deps  # Homebrew: restic, sops, uv, ffmpeg, jq, coreutils
make install       # uv sync, including the dev group and Quarto

make init loads the selected configuration, deduplicates enabled stores referenced by a backup, and runs restic init once per repository. It does not back up files and is unnecessary for an existing repository.

CLI

Use the built-in help for available commands and options:

uv run restic-backups --help
uv run restic-backups generic --help
uv run restic-backups voice-memos --help

Configuration

Pass a plain YAML file explicitly:

uv run restic-backups --config config.yaml check-config

For SOPS, add --sops. The equivalent environment variables are RESTIC_BACKUPS_CONFIG and RESTIC_BACKUPS_SOPS=1; they also configure make config-check and make init.

The configuration separates:

• credentials: reusable S3-compatible authentication;
• restic-stores: endpoint, region, bucket, key prefix/password, and optional archive policy;
• backups: jobs linked to a store by restic-store-id.

One credential may serve many stores, and multiple backups may share a store. Disabled stores may contain CHANGE_ME; all placeholders must be replaced before enabling one.

Data and source paths

Managed local artifacts use:

data/<store-id>/<bucket>/<key-prefix>/<backup-id>/

This is metadata/workspace organization, not a restriction on backup sources. Restic may back up absolute paths anywhere on the machine. Resolve a managed directory without exposing credentials with:

uv run restic-backups generic data-dir voice-memos

AWS Glacier

Use GLACIER_IR with restore: null for normal immediate restic access. Cold GLACIER and DEEP_ARCHIVE stores require a configured retrieval tier, days, and timeout. Retrieval must also be acknowledged at runtime:

ALLOW_ARCHIVE_RETRIEVAL=1 uv run restic-backups generic run \
  --backup <backup-id> restore latest --target <dir>

Storage-class changes apply only to new objects. Use a new key_prefix instead of mixing storage policies in one repository.

Documentation

make docs          # render docs/_site
make docs-preview  # local preview server

Start with the Quarto guide. Never commit decrypted SOPS configuration or anything below data/.