Quick Start

This guide creates one generic S3-compatible backup. A mounted local disk uses the same workflow; see Configuration.

1. Install

make install-deps
make install

make install-deps installs the required Homebrew tools. make install creates the uv environment.

2. Configure a repository

Copy the commented template:

cp config.template.yaml config.yaml

Edit its first storage, restic repository, and job entries:

  • replace every CHANGE_ME used by the available repository;
  • configure either S3 storage and credentials or an absolute local storage path;
  • configure the repository bucket and key_prefix for S3, or relative path for local storage;
  • give the backup job a useful job-id such as documents;
  • use type: files and list local files or directories under source.paths;
  • omit tag unless it should differ from the job ID;
  • list one or more available repository IDs under restic-repository-ids;
  • delete unused example entries if desired.

Keep the repository password safe: restic cannot decrypt snapshots without it.

Set the config path once for the shell and validate it:

export RESTIC_BACKUPS_CONFIG="$PWD/config.yaml"
uv run restic-backups check-config
uv run restic-backups generic repository list
uv run restic-backups job list

The list output separates Repositories from Jobs. Every configured restic repository appears in the repository table, even before a configured backup references it.

3. Initialize and back up

Initialize a new repository once:

uv run restic-backups generic repository init personal-b2

Then create a snapshot from the paths configured for documents:

uv run restic-backups job run documents
uv run restic-backups generic snapshot list documents

Running generic repository init again is safe: an existing repository is detected and skipped. Omit the repository ID to choose interactively, or pass --all to initialize every available repository. job run preselects a sole available destination; when several are available, use Space to choose one or more. Disabled storage and its repositories remain visible but unselectable. The job’s paths and default or configured tag are used for every selected repository.

4. Verify a restore

mkdir -p /tmp/restic-restore-check
uv run restic-backups generic restic run --backup documents \
  restore latest --target /tmp/restic-restore-check

Inspect the restored files before relying on the backup. Continue with Generic Backups for repository commands or GitHub Backups for explicit repositories or an entire GitHub organization or user, or Voice Memos Backups for the macOS workflow.

Warning

Do not commit config.yaml, credentials, repository passwords, or restored data. Use SOPS before committing a config.