Repositories and Restic

The generic subcommand manages configured restic repositories, snapshots, and advanced restic passthrough. Use the unified job command to list and run jobs.

Set RESTIC_BACKUPS_CONFIG first, or pass --config before generic. See the Quick Start for a complete first backup.

Commands

Group	Command	Purpose	Repository access
Repository	`generic repository list`	Show configured repositories	Read-only
Repository	`generic repository init [REPOSITORY] [--all] [--from-repository SOURCE] [--copy-all-snapshots \| --copy-snapshot ID...] [--dry-run]`	Initialize new repositories	Yes
Repository	`generic repository prime-cache [REPOSITORY]`	Cache and validate repository metadata	Yes
Repository	`generic repository copy SOURCE DESTINATION [SNAPSHOT_ID...] [--dry-run]`	Copy snapshots between repositories	Yes
Repository	`generic repository prune [REPOSITORY] [OPTIONS]`	Prune or repack repository data	Yes
Repository	`generic repository destroy [REPOSITORY] [--dry-run]`	Permanently erase one repository	Yes
Job	`job list`	Show every configured job type	No
Job	`job run [JOB_ID] --repository ID... [--dry-run]`	Create snapshots in selected repositories	Yes
Snapshot	`generic snapshot list [JOB_ID] [--repository ID]`	List snapshots for a configured backup	Yes
Snapshot	`generic snapshot forget [JOB_ID] [--repository ID] [--dry-run]`	Forget one tagged snapshot and prune	Yes
Restic	`generic restic run --backup JOB_ID --repository ID ...`	Pass trailing arguments directly to restic	Depends on restic command

Commands that accept [JOB_ID] prompt when it is omitted in an interactive terminal. Repository-specific operations also prompt when a job has several available repositories. A repository on disabled storage remains visible but cannot be selected. An uninitialized repository is likewise shown in the grey disabled section everywhere except the initialization picker. The UI checks for the Restic config file locally or with an S3 metadata request; it does not download repository contents. Non-interactive callers must provide the job ID and repository ID explicitly.

The top-level TUI provides described menus for repositories, jobs, snapshots, and advanced restic commands. Advanced restic reads the installed restic version’s command list and descriptions. After selection it shows the command’s restic usage, prompts for arguments, and prints the complete copyable uv run restic-backups command. Choose Run, Print only, or Cancel. Choose Help at any level to see help for the current section or selected restic command and return to the same menu. Showing help does not load the configuration, select a backup, or contact the repository. Back returns one level without restarting the menu tree. Entering --help or -h in the argument prompt has the same local-help behavior.

For restic ls, leave the argument prompt empty to choose from the job’s available tagged snapshots. The selected full snapshot ID is inserted into the copyable command. Enter an ID or latest directly to skip the picker.

Dry runs

The interactive menu shows a Dry run checkbox for repository initialization, copying, pruning, repository destruction, backup creation, and snapshot forgetting. Press Space to toggle it, then Enter to continue. A dry run performs any reads needed to report what would happen but does not initialize, copy, or destroy a repository, upload backup data, create a snapshot, forget a snapshot, or prune data.

Advanced restic commands show the same checkbox when the installed restic version advertises a native --dry-run flag for the selected command. Commands without that flag do not show the checkbox; use Print only to inspect their complete command without running it.

Explicit commands can pass --dry-run directly to the managed write commands:

uv run restic-backups generic repository init personal --dry-run
uv run restic-backups generic repository copy personal-local personal-s3 --dry-run
uv run restic-backups generic repository prune personal --dry-run
uv run restic-backups job run documents --dry-run
uv run restic-backups generic snapshot forget documents --dry-run
uv run restic-backups generic repository destroy personal --dry-run

generic repository list shows every restic repository, even when no configured job references it. job list shows every job type.

The Initialize TUI menu offers Empty for an independent repository and From existing to reuse a source repository’s chunker parameters. After choosing a source and destination, select None, All, or Select to initialize without snapshots, copy every snapshot, or choose particular snapshots. The batch equivalents are:

uv run restic-backups generic repository init personal-sandisk \
  --from-repository personal-b2

uv run restic-backups generic repository init personal-sandisk \
  --from-repository personal-b2 --copy-all-snapshots

uv run restic-backups generic repository init personal-sandisk \
  --from-repository personal-b2 \
  --copy-snapshot 410b18a2 --copy-snapshot 4e5d5487

Plain generic repository init prompts for one repository, with All uninitialized repositories as the first option. The picker checks repository state before selection: initialized repositories appear in a disabled Initialized repositories section above the existing Disabled repositories section. Scripts must pass a repository ID or --all. An existing repository is never reinitialized.

generic repository prime-cache runs restic check --with-cache for one repository. It downloads repository indexes, snapshots, and tree metadata into the configured cache while also validating repository structure. It does not download backed-up file contents; restic only does that when --read-data is requested explicitly.

Copy snapshots between repositories

Choose Repositories → Copy to select a source, destination, and either all snapshots or particular snapshot IDs. If the destination is uninitialized, the workflow first runs restic init --from-repo SOURCE --copy-chunker-params so copied history and future direct backups use compatible chunk boundaries. An existing destination is never reinitialized. The equivalent explicit commands are:

# Copy every snapshot not already present
uv run restic-backups generic repository copy personal-local personal-s3

# Copy selected snapshots
uv run restic-backups generic repository copy \
  personal-local personal-s3 410b18a2 4e5d5487

Restic reads the selected encrypted data from the source and writes it to the destination, so remote repositories can incur retrieval, request, transfer, and upload charges. Repeated runs skip snapshots already copied. During a real copy, restic-backups runs native restic copy --verbose with live terminal output, including elapsed time, percentage, and copied pack counts. Progress refreshes once per second by default; set RESTIC_PROGRESS_FPS to override that rate.

Restic cannot change chunker parameters on an existing repository, so a destination initialized independently retains its existing parameters. Native copy also cannot use separate credentials or regions for two S3 backends; use an rclone backend for that case. See the restic copy documentation.

Prune or compact a repository

Choose Repositories → Prune / compact in the TUI. The maintenance menu uses the native restic prune options and provides:

Standard prune: remove unused data with restic’s defaults;
Minimize bandwidth: pass --max-unused unlimited and retain partly used data packs;
Metadata only: pass --repack-cacheable-only and repack only cacheable metadata;
Compact small packs: pass --repack-smaller-than SIZE;
Limit repacking: pass --max-repack-size SIZE.

Select a repository, then use the Dry run checkbox to preview the operation. A real run requires confirmation. Explicit commands expose the same flags and accept --yes for deliberate non-interactive maintenance:

uv run restic-backups generic repository prune personal --dry-run
uv run restic-backups generic repository prune personal \
  --max-unused unlimited --yes

Snapshots already share deduplicated data, so pruning does not combine them into one snapshot. It scans snapshot references, deletes wholly unused packs, and may download and re-upload partially used packs before deleting the originals. The configured local cache helps with metadata, but normal repacking still operates on repository data. Remote storage may therefore incur retrieval, request, and transfer charges. Use Metadata only, Minimize bandwidth, or --max-repack-size when limiting remote I/O matters.

Create a snapshot

Configure the local source paths once, then select the backup by its ID:

jobs:
  - job-id: documents
    type: files
    restic-repository-ids:
      - personal-b2
      - personal-local
    source:
      paths:
        - ~/Documents
        - ~/Desktop

uv run restic-backups job run documents

The TUI preselects a sole available repository. When several are available, none start selected; use Space to select one or more, then Enter to run. From a non-interactive shell, repeat --repository explicitly:

uv run restic-backups job run documents \
  --repository personal-b2 \
  --repository personal-local

The command expands ~, runs restic backup independently for each selected repository, and applies the job ID as the restic tag unless tag is explicitly configured. Every destination gets its own snapshot while restic uploads only new or changed file data already absent from that repository.

List snapshots

List snapshots with the configured backup tag:

uv run restic-backups generic snapshot list documents

The table shows each snapshot’s short restic ID, timestamp, host, paths, and tags.

Forget one snapshot

uv run restic-backups generic snapshot forget

Forgetting is interactive-only. Select a configured backup, select one snapshot with its configured restic tag, and confirm. The CLI runs restic forget --prune, so the snapshot and data no longer referenced by any other snapshot are permanently removed. The configured backup and repository remain available.

When several configured backups share a repository, their restic tags keep their snapshots distinct in the picker.

Permanently destroy a repository

uv run restic-backups generic repository destroy

Destruction is interactive-only. The CLI shows the full target, asks for a yes/no confirmation, then requires the exact repository ID. For S3 it deletes every object, object version, and delete marker below the configured bucket and key_prefix; it does not delete the bucket. For local storage it removes the configured repository directory but not the storage root. It never changes the YAML configuration.

S3 credentials need permission to list and delete objects and versions. An empty key_prefix is always rejected to prevent accidental bucket deletion.

Repository deletion is irreversible. Snapshots, indexes, repository keys, and encrypted data are all erased. The configured restic password cannot recover them.

Common operations

# Inspect and check the repository
uv run restic-backups generic snapshot list documents
uv run restic-backups generic restic run --backup documents check
uv run restic-backups generic restic run --backup documents list snapshots

# Restore a snapshot
uv run restic-backups generic restic run --backup documents \
  restore <snapshot-id> --target /tmp/documents-restore

Arguments after the backup selection are passed to restic unchanged. The CLI exports the selected repository details, password, and any S3 credentials only to the child process and does not print them. For the backup command, it also adds the configured restic tag automatically; additional --tag arguments remain supported.

Cold S3 storage

GLACIER_IR supports immediate access. GLACIER and DEEP_ARCHIVE permit uploads, but retrieval-related commands require the configured restore policy and an explicit acknowledgement:

ALLOW_ARCHIVE_RETRIEVAL=1 uv run restic-backups generic restic run \
  --backup archive restore latest --target /tmp/archive-restore

Other restic commands are rejected for cold repositories when the CLI cannot determine that they are safe. See Configuration for the archive policy fields.