Skip to main content

Restic

@magistr/resticv2026.11.08.1· MIT· 13d agoBEHAVIORS
01README

Drive restic backups from swamp: read repository state, initialize, back up, list snapshots, verify integrity, apply retention and report size — every run lands as versioned swamp data.

Methods:

  • status — reachable / initialized / snapshot count / newest snapshot age (read-only; use it as the pre-flight step of a backup workflow)
  • init — create the repository; no-op when it already exists
  • backup — back up paths; restic's summary plus unreadable-file errors (exit 3 is recorded as complete: false, not thrown)
  • snapshots — list snapshots, filtered by host/tag/latest
  • check — integrity check, optionally reading a subset of pack data; a failed check is data (ok: false), not an exception
  • forget — keep policy, dry-run by default, optional prune
  • stats — size and compression statistics
  • unlock — remove stale locks (e.g. left by a killed prune); live locks are kept

Works with any restic backend. Secrets (password, rest-server basic-auth) are sensitive global arguments, passed to restic only via environment variables and redacted from all errors. Requires the restic binary (>= 0.17) on the host running the method.

02Release Notes

2026.11.08.1

Added

  • unlock method: lists locks, runs restic unlock (stale locks only, never --remove-all), lists again, and records no-locks / removed-stale / locks-still-held.
03Behaviors1
@magistr/resticv2026.11.08.1extensions/models/restic.ts

Global Arguments

ArgumentTypeDescription
repositorystringrestic repository URL, e.g. rest:http://backup.example.lan:8000/laptop/
passwordstringRepository encryption password (RESTIC_PASSWORD)
restUsername?stringrest-server HTTP basic-auth user (RESTIC_REST_USERNAME)
restPassword?stringrest-server HTTP basic-auth password (RESTIC_REST_PASSWORD)
paths?arrayDefault paths to back up
excludes?arrayExclude patterns passed as --exclude
excludeCaches?booleanSkip directories holding a CACHEDIR.TAG
hostname?stringOverride the host name recorded in snapshots
tags?arrayTags added to every backup snapshot
binary?stringrestic executable
cacheDir?stringOverride --cache-dir
fn status()
Read repository state (initialized, snapshot count, newest snapshot age) without modifying it
fn init()
Initialize the repository; no-op when it already exists
fn backup(paths?: array, tags?: array, dryRun?: boolean, maxErrors?: number)
Back up paths; records the restic summary and any unreadable files
ArgumentTypeDescription
paths?arrayPaths to back up (default: globalArguments.paths)
tags?arrayExtra snapshot tags
dryRun?booleanPass --dry-run
maxErrors?numberMax file errors to record
fn snapshots(host?: string, tag?: string, latest?: number)
List snapshots, optionally filtered by host/tag/latest
ArgumentTypeDescription
host?stringOnly snapshots from this host
tag?stringOnly snapshots with this tag
latest?numberOnly the newest N per host/path group
fn check(readDataSubset?: string)
Verify repository integrity, optionally reading a subset of pack data
ArgumentTypeDescription
readDataSubset?stringAlso read and verify pack data, e.g. '5%', '1/10', '2G'
fn forget(keepLast?: number, keepHourly?: number, keepDaily?: number, keepWeekly?: number, keepMonthly?: number, keepYearly?: number, keepWithin?: string, prune?: boolean, dryRun?: boolean)
Apply a keep policy (dry-run by default); optionally prune. Fails against an append-only rest-server
ArgumentTypeDescription
keepLast?number
keepHourly?number
keepDaily?number
keepWeekly?number
keepMonthly?number
keepYearly?number
keepWithin?stringe.g. '30d', '1y6M'
prune?booleanAlso prune unreferenced data
dryRun?booleanOnly report what would be removed (default true)
fn stats(mode?: enum)
Repository size and compression statistics
ArgumentTypeDescription
mode?enum
fn unlock()
Remove stale locks (left by a killed or crashed restic); locks held by a live process are kept and reported
04Previous Versions11
2026.10.25.10MIT

2026.10.25.10

  • Repo-wide republish; no functional change.
2026.10.15.9MIT

2026.10.15.9

Changed

  • Repo-wide maintenance release: version bump to republish the current source. No schema change.
2026.10.15.8MIT

2026.10.15.8

Changed

  • Repo-wide maintenance release: version bump to republish the current source. No schema change.
2026.10.15.6MIT

2026.10.15.6

Changed

  • Repo-wide maintenance release: version bump to republish the current source. No schema change.
2026.10.15.5MIT

2026.10.15.5

Changed

  • Repo-wide maintenance release: version bump to republish the current source. No schema change.
2026.10.15.4MIT

2026.10.15.4

Changed

  • Repo-wide maintenance release: version bump to republish the current source. No schema change.
2026.10.15.3MIT

2026.10.15.3

Changed

  • Repo-wide maintenance release: version bump to republish the current source. No schema change.
2026.10.15.2MIT

2026.10.15.2

Changed

  • Repo-wide maintenance release: version bump to republish the current source. No schema change.
2026.10.15.1MIT

2026.10.15.1

Changed

  • Repo-wide maintenance release: version bump to republish the current source. No schema change.
2026.10.14.2MIT(was none)

2026.10.14.2

Changed

  • Repo-wide maintenance release: version bump to republish the current source. No schema change.
2026.09.29.1

2026.09.29.1

  • Initial release: status, init, backup, snapshots, check, forget, stats methods for @magistr/restic.
05Stats
A
100 / 100
Downloads
89
Archive size
14.7 KB
  • Has README or module doc2/2earned
  • README has a code example1/1earned
  • README is substantive1/1earned
  • Most symbols documented1/1earned
  • No slow types (deprecated)1/1earned
  • Dependencies pass trust audit2/2earned
  • Docs keep secrets in a vault1/1earned
  • Has description1/1earned
  • Platform support declared (or universal)2/2earned
  • License2/2earned
  • Verified public repository2/2earned
06Platforms
07Labels