CLI

Run the installed command through uv:

uv run restic-backups

In an interactive terminal, running without a command opens a described arrow-key menu for Jobs, Repositories, and configuration validation. Choose a job before choosing run, status, snapshots, advanced restic, or its type-specific tools. Explicit subcommands remain available for scripts and scheduled jobs.

Every menu level includes Help and Back. Help shows the commands and flags for the current level, then returns to the same menu; it does not load the configuration or contact remote storage.

Press Escape to return to the previous menu. Press Ctrl+C at any prompt to exit the TUI cleanly.

Show command-line help instead:

uv run restic-backups --help

Commands that use a repository require a configuration file. Pass the global options before the command:

uv run restic-backups --config config.yaml generic repository list
uv run restic-backups --config config.sops.yaml --sops job list

The equivalent environment variables are RESTIC_BACKUPS_CONFIG and RESTIC_BACKUPS_SOPS=1. See Configuration for setup.

Commands use standard Python stderr logging with local ISO 8601 timestamps, levels, and logger names. Add --verbose before the command, or set RESTIC_BACKUPS_VERBOSE=1, to include command-level details without printing credentials or repository passwords:

uv run restic-backups --verbose generic repository init

User-facing Restic stdout and stderr use the same logger, so repository output also carries timestamps and levels. Machine-readable internal calls remain quiet unless they fail. See Logging configuration for the complete behavior and example output.

Prometheus metrics

Jobs can push their latest result to a Prometheus Pushgateway. Set its URL before running a job:

export RESTIC_BACKUPS_PROMETHEUS_PUSHGATEWAY_URL=http://pushgateway:9091
uv run restic-backups job run photos

Metrics are disabled when the environment variable is unset. See Prometheus configuration for metric names, labels, Pushgateway behavior, and a Prometheus scrape example.

Audit log

Repository-write auditing is enabled by default. restic-backups appends compact JSON objects to audit-log.json in the directory where it was started. Only operations that can initialize or change a Restic repository are audited, including backup, copy, forget, initialize, migrate, prune, recover, repair, rewrite, tag, unlock, key changes, and repository destruction. Read-only operations such as list, snapshots, status, stats, check, help, restore, GitHub discovery, and Git preparation are not recorded. Dry runs are not recorded.

Each audited write has two linked records:

a started event containing an id, start-time, hostname, command, and its exact args;
a finished event containing started-id, end-time, and successful. Workflows may also add non-secret component and destination results under details.

The started-id links completion to the corresponding started event. A started event without a matching finished event indicates an interrupted process. The file is append-only: existing records are never rewritten. It is created with owner-only permissions (0600). Job writes include their selected destinations and result details. Restic write records contain the exact raw Restic arguments, including generated repository options. Direct repository destruction is recorded as a restic-backups command because it intentionally bypasses Restic. Credentials and repository passwords are passed through the environment rather than arguments. Values attached to password-, secret-, token-, credential-, and key-like arguments are replaced with [REDACTED].

The log can still reveal repository names and local paths. Keep it private and rotate or archive it according to your own retention policy. To turn auditing off explicitly:

export RESTIC_BACKUPS_AUDIT=0

The values false, no, and off are also accepted, case-insensitively.

Root commands

Command	Purpose	Repository access
`check-config`	Load and validate configuration	No
`job ...`	List, run, and inspect every configured job type	Depends on subcommand
`generic ...`	Run generic configured repository commands	Depends on subcommand
`voice-memos ...`	Transcription, inspection, and Voice Memos-specific tools	Depends on subcommand

Use Generic Backups for restic passthrough, repository initialization, restores, and managed data directories. Use GitHub Repositories for Git history and selected GitHub-hosted data. Use Voice Memos Backups for the macOS-specific workflow.

Run subcommand help without loading a configuration:

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