snapshot-user

name	snapshot-user
description	Operate the `snapshot` per-service backup orchestrator — enable / list / take / restore / push / pull backups for file trees, postgres databases, wireguard configs, and (filed) filesystem-level snapshots. Trigger when the user wants to schedule backups, restore from a prior snapshot, sync backups across accounts, or learn the per-service plugin model.

snapshot-user skill

1. Design principles

• Educational. Each service is a small libexec plugin you can read end-to-end.
• Functional. Every verb is a thin wrapper over the underlying primitive (rsync, pg_dump, cp).
• Decentralized. Each account holds its own snapshot store; sync is symmetric pull/push.
• Simple. snapshot calls only account at runtime; SSH endpoints from account remote-url.

2. The model

A service is a backup-able state class. Today:

Service	Plugin	Backend
file	libexec/snapshot/file	rsync(1)
postgres	libexec/snapshot/postgres	pg_dump(1)
wireguard	libexec/snapshot/wireguard	cp /etc/wireguard
zfs/btrfs/lvm	(filed FEAT-058; pending)	filesystem snapshots

Backups live under $XDG_DATA_HOME/snapshot/<service>/, named with a timestamp. Retention follows max-backups (grandfather-father-son per FEAT-059, pending).

3. Workflow recipes

1. List supported services.

   snapshot services
   

2. Enable a service.

   snapshot enable postgres
   snapshot enabled postgres
   

3. Take a backup.

   snapshot backup postgres
   snapshot last postgres
   

   Per-service flags (cpk-local additions per FEAT-326):

   snapshot backup postgres --schema-only
   # forwards pg_dump's --schema-only -- dump has table
   # definitions but no row data. Used by clone-org
   # --schema-only and seed-data --handler=postgres.
   

4. Restore.

   snapshot restore postgres
   snapshot restore file --to v1.0.0
   snapshot restore wireguard --to 20260530-101122
   

   Default id is latest; --to <id> (cpk-local addition per FEAT-327) restores from a named snapshot. The id must match a directory under $(snapshot config get target)/<id>/; see snapshot list for the available ids.

5. Garbage-collect old backups.

   snapshot clean
   snapshot used
   snapshot free
   

   Retention is driven by snapshot config get max-backups. When the cpk orchestrator runs cpk hosts snapshot <host> backup, it pushes the host's .cpk/config/retention to this key before each backup-modifying subcommand (FEAT-327 slice 3) so the ring prunes per-host without a fleet-wide tweak.

6. Push to a peer.

   snapshot push postgres [e-mail]
   snapshot pull postgres [e-mail]
   snapshot remote [e-mail]
   

4. Guardrails

1. snapshot restore overwrites live state. Take a fresh backup first.
2. snapshot clean is irreversible — it removes old backup files per the retention policy.
3. Per-service config lives at $SELF_CONFIG/<service> — manual edits there change behaviour; check what's there before tweaking.
4. Pull respects account online — silently warn-and-skip if the peer is unreachable.
5. Filesystem-snapshot services aren't implemented yet (FEAT-058 pending). Use file/postgres/ wireguard today; ZFS/btrfs/LVM after that ticket lands.

5. Where to read more

• man snapshot
• man msync for the sync-trio sibling
• This package's CLAUDE.md