Dev In The Mountain Header
A Developer In The mountains having fun

๐Ÿ—„๏ธ katbackup

โ† Back to all my apps ยท GitHub ยท Releases

Back up your Linux config files as compressed, timestamped snapshots, then restore everything or just the files you pick (CLI & TUI).

katbackup copies the dotfiles and config folders you choose into ~/.katConfigBackup (or a NAS, USB drive or synced folder) as tar.zst snapshots. Secrets like ~/.ssh only ever go into encrypted snapshots. When you need something back, you can browse a snapshot in the TUI, see what's different from what's on disk, compare a file in your own diff tool, and restore just that.

It shares the "kat" name and the vim-ish keys with the kat suite, but it's its own thing.

Features

  • ๐Ÿ“ฆ Compressed snapshots: each backup is a tar compressed with zstd, named by date and time
  • ๐Ÿ” Encryption for secrets: -e encrypts with a passphrase using age. Anything under secrets, or matching built-in credential patterns (.ssh, .gnupg, gh/hosts.ymlโ€ฆ), is only backed up into encrypted snapshots
  • ๐Ÿ”Ž Smart setup: init --tui scans your home folder and lets you pick which configs to back up
  • ๐Ÿ’ค Skips backups when nothing changed, so a daily timer doesn't fill the disk with copies
  • ๐Ÿงน Automatic pruning: keeps the newest keep snapshots (10 by default, or "all")
  • ๐Ÿ•ต๏ธ See what changed: status against the newest snapshot, diff between two snapshots, and log for the history of a single file
  • ๐ŸŽฏ Selective restore: restore everything, chosen paths, or globs like '.config/**/*.toml', from any snapshot, or into another folder
  • ๐Ÿ›Ÿ Safe restores: checksums are verified before anything on disk changes, and files that would be overwritten are kept as .katbak-<timestamp> copies
  • ๐Ÿ–ฅ๏ธ A full TUI to make, browse, compare, restore and delete snapshots
  • ๐Ÿ  Portable: paths are stored relative to $HOME, so a snapshot restores fine on another machine or under another username
  • โฐ Built for cron and systemd: --quiet --strict, clear exit codes, and protection against overlapping runs

First run

sh
katbackup init --tui    # pick which config files and folders to back up
katbackup backup -n     # dry run: list what would go into the backup
katbackup backup        # create the first snapshot
katbackup list          # see it
katbackup restore -n    # dry run: show what a restore would change

Commands

sh
katbackup backup                   # โ†’ ~/.katConfigBackup/2026-10-26_175200.tar.zst
katbackup backup -e                # encrypted; also includes your secrets
katbackup list
katbackup show [snapshot] [-t]
katbackup restore                              # everything from the latest snapshot
katbackup restore ~/.zshrc .config/nvim -n     # dry run for selected paths
katbackup restore -s 2026-10-26 --to /tmp/out  # pick a snapshot, restore somewhere else
katbackup status                               # what changed since the newest snapshot
katbackup diff [old] [new]                     # what changed between two snapshots
katbackup log ~/.zshrc                         # which snapshots changed a file
katbackup prune -k 5                           # delete old snapshots
katbackup tui

Snapshots can be named in full, by the start of the name (2026-10-26), or as latest. Most commands take --json for scripting, and --dir on any command points it at another backup folder.

TUI

katbackup tui opens the snapshot list. From there n makes a new snapshot, e an encrypted one, x deletes one, and enter opens it.

Inside a snapshot, space selects files, a selects all, c selects only the files that differ from what's on disk, and d compares a file with the snapshot's copy in your diff tool. enter reviews the selection and restores it, and b toggles keeping .katbak copies. / filters and ? shows every key.

The diff tool is whatever you set as diff_tool, falling back to your git diff.tool. katCompare works well here:

toml
diff_tool = 'katcmp-win --wait "$LOCAL" "$REMOTE"'   # or nvim -d, meld, code --wait --diffโ€ฆ

Config

~/.config/katbackup/config.toml, written for you by init:

toml
keep = 10          # snapshots to keep ("all" = never delete)
encrypt = false    # true = always encrypt
include = ["~/.zshrc", "~/.gitconfig", "~/.config/nvim", "~/.config/zellij"]
exclude = ["**/node_modules", "**/.git", "**/*.log", "**/cache"]
secrets = ["~/.ssh", "~/.config/gh/hosts.yml"]
diff_tool = 'nvim -d "$LOCAL" "$REMOTE"'   # optional
dir = "/mnt/nas/laptop"                     # optional; where snapshots go

A snapshot folder on another disk has to exist already, so an unplugged drive can't quietly turn into a folder on your local disk. Use one folder per machine, since pruning counts every snapshot in it.

Scheduling

katbackup doesn't schedule itself; use cron or a systemd user timer:

0 3 * * * $HOME/.local/bin/katbackup backup --quiet --strict

--quiet only prints warnings and errors, so cron only mails you when something needs a look, and --strict turns warnings into a failed exit code. For encrypted runs, set KATBACKUP_PASSPHRASE from a file only you can read. The README has a full systemd timer example.

Install

katbackup runs on Linux (amd64 and arm64). Grab a tarball from the releases page, or build it with Go:

sh
go install github.com/devinthemtn/katbackup/cmd/katbackup@latest

MIT licensed.

More places to find me
Mental Health
follow me on Mastodon