Backup system

Automatic snapshots with deduplication

On this page

Overview
Quick start
Storage architecture
CLI commands
Retention policies
Deduplication
Doctor integration

Overview

The backup system creates versioned snapshots of your configuration files before each write. If a config is deleted or broken, you can restore it from any previous snapshot.

Backups are automatic and deduplication prevents storing identical content twice. Everything lives in $XDG_DATA_HOME/klaudiush/backups/ (default ~/.local/share/klaudiush/backups/) so there's one place to manage all your configs.

Quick start

Backups are enabled by default. You can tune behavior in .klaudiush/config.toml:

[backup]
enabled = true
auto_backup = true
max_backups = 10
max_age = "720h"     # 30 days
async_backup = true

View backups

# List all backups
klaudiush backup list

# Filter by project
klaudiush backup list --project /path/to/project

# Global config only
klaudiush backup list --global

Restore a config

# Preview restore
klaudiush backup restore abc123def456 --dry-run

# Restore (creates backup of current config first)
klaudiush backup restore abc123def456

# Force restore without backup
klaudiush backup restore abc123def456 --force

Dry run first

Use --dry-run to preview what restore will do before changing anything.

Storage architecture

All backups live in a centralized directory. Global config and per-project configs are separated into their own snapshot directories.

backups/ - ~/.local/share/klaudiush/backups/
- global/
  - snapshots/
    - 001_20250102_150405.full.toml
    - 002_20250102_160000.full.toml
  - metadata.json
- projects/
  - Users_bart_project1/
    - snapshots/
    - metadata.json
- audit.jsonl
- .retention

Each snapshot is a complete copy of the config file (full snapshots). A SHA256 checksum is stored alongside the content for integrity validation on restore.

CLI commands

Command	Description
`backup list`	List snapshots, filter by project or global
`backup create`	Create a manual snapshot with optional tag
`backup restore`	Restore from a snapshot (backs up current first)
`backup delete`	Delete one or more snapshots
`backup prune`	Remove old snapshots per retention policy
`backup status`	Show storage stats
`backup audit`	View the audit log of operations

Retention policies

Three policies control how long snapshots are kept. When multiple policies are set, all must pass for a snapshot to be retained.

[backup]
max_backups = 10       # max snapshots per config
max_age = "720h"       # 30 days
max_size = 52428800    # 50MB total storage

Run klaudiush backup prune --dry-run to preview which snapshots would be deleted.

Deduplication

Before creating a snapshot, the system computes a SHA256 hash and checks if that hash already exists. If the content hasn't changed, it returns the existing snapshot ID instead of creating a duplicate. This keeps storage lean even with frequent auto-backups.

Doctor integration

The doctor command checks your backup setup - directories, metadata, and checksums.

# Validate backup system
klaudiush doctor --category backup

# Auto-fix issues
klaudiush doctor --category backup --fix

With --fix, doctor repairs the backup directory structure and removes corrupted snapshots.