Merge feature/exclude-list-refinement

Removed /.docker (small, contains registry auth config worth keeping)
and /Library/Parallels (small app support; the actual VM disks live in
~/Parallels) from the default excludes.

Added recommended excludes for data that should never be backed up:
- Language/toolchain caches (npm, cargo, rustup, go modules, maven,
  vagrant boxes, node_modules, __pycache__, .venv)
- VM disk images (Parallels, VMware Fusion, VirtualBox, OrbStack, UTM)
- Downloaded LLM models (ollama, LM Studio)
- Cloud-synced storage (~/Library/CloudStorage, iCloud Drive) — synced
  elsewhere, and dataless placeholder files would be force-downloaded
- Android SDK and emulator images

README.md

@@ -46,66 +46,34 @@ go install git.eeqj.de/sneak/vaultik@latest
 
 ## quick start
 
-1. **generate keypair**
+```sh
+# 1. Install
+go install git.eeqj.de/sneak/vaultik@latest
 
-   ```sh
-   age-keygen -o agekey.txt
-   grep 'public key:' agekey.txt
-   ```
+# 2. Generate an age keypair (store the private key somewhere safe, offline)
+age-keygen -o key.txt
+# the public key is printed to stdout and also in key.txt
 
-2. **write config** (see `config.example.yml` for all options)
+# 3. Create a default config file
+vaultik init
+# Writes to the platform config directory with commented defaults:
+#   macOS: ~/Library/Application Support/vaultik/config.yml
+#   Linux: ~/.config/vaultik/config.yml
+#   root:  /etc/vaultik/config.yml
 
-   ```yaml
-   snapshots:
-     system:
-       paths:
-         - /etc
-         - /var/lib
-       exclude:
-         - '*.cache'
-     home:
-       paths:
-         - /home/user/documents
-         - /home/user/photos
+# 4. Edit the config: set age_recipients, snapshots, and storage_url
+#    (init prints the path it wrote to)
 
-   exclude:
-     - '*.log'
-     - '*.tmp'
-     - '.git'
-     - 'node_modules'
+# 5. Run your first backup
+vaultik snapshot create
 
-   age_recipients:
-     - age1YOUR_PUBLIC_KEY_HERE
+# 6. Verify it worked
+vaultik snapshot list
+vaultik snapshot verify <snapshot-id>
 
-   # Storage backend (pick one):
-   storage_url: "s3://mybucket/backups?endpoint=s3.example.com&region=us-east-1"
-   # storage_url: "file:///mnt/backups"
-   # storage_url: "rclone://myremote/path/to/backups"
-
-   # For s3:// URLs, credentials are still required:
-   s3:
-     access_key_id: ...
-     secret_access_key: ...
-   ```
-
-3. **run**
-
-   ```sh
-   # Back up all configured snapshots
-   vaultik --config /etc/vaultik.yml snapshot create
-
-   # Back up specific snapshots by name
-   vaultik --config /etc/vaultik.yml snapshot create home system
-
-   # Silent mode for cron
-   vaultik --config /etc/vaultik.yml snapshot create --cron
-
-   # Back up and clean up old snapshots + orphan blobs in one shot
-   vaultik --config /etc/vaultik.yml snapshot create --prune
-
-   # Daily cron: back up, keep last 4 weeks of snapshots
-   vaultik --config /etc/vaultik.yml snapshot create --cron --prune --keep-newer-than 4w
-   ```
+# 7. Set up a daily cron job (keeps last 4 weeks of snapshots)
+# 0 3 * * * vaultik snapshot create --cron --prune --keep-newer-than 4w
+```
 
 ---
 
@@ -114,6 +82,7 @@ go install git.eeqj.de/sneak/vaultik@latest
 ### commands
 
 ```sh
+vaultik [--config <path>] init
 vaultik [--config <path>] snapshot create [snapshot-names...] [--cron] [--prune] [--keep-newer-than <duration>] [--skip-errors]
 vaultik [--config <path>] snapshot list [--json]
 vaultik [--config <path>] snapshot verify <snapshot-id> [--deep] [--json]
@@ -132,7 +101,7 @@ vaultik version
 
 ### global flags
 
-* `--config <path>`: Path to config file (default: `$VAULTIK_CONFIG` or `/etc/vaultik/config.yml`)
+* `--config <path>`: Path to config file (default: `$VAULTIK_CONFIG`, then platform config dir, then `/etc/vaultik/config.yml`)
 * `--verbose`, `-v`: Enable verbose output
 * `--debug`: Enable debug output
 * `--quiet`, `-q`: Suppress non-error output
@@ -145,6 +114,12 @@ vaultik version
 
 ### command details
 
+**init**: Write a default config file with commented explanations for every
+setting. Writes to the path from `--config`, `$VAULTIK_CONFIG`, or the
+platform config directory (`~/Library/Application Support/vaultik/` on macOS,
+`~/.config/vaultik/` on Linux, `/etc/vaultik/` as root). Refuses to overwrite an
+existing file. Created with mode `0600` since it will contain credentials.
+
 **snapshot create**: Perform incremental backup of configured snapshots.
 * Optional snapshot names argument to create specific snapshots (default: all)
 * `--cron`: Silent unless error (for crontab)

internal/cli/entry_test.go

@@ -18,7 +18,7 @@ func TestCLIEntry(t *testing.T) {
 	}
 
 	// Verify all subcommands are registered
-	expectedCommands := []string{"snapshot", "store", "restore", "prune", "info", "version", "remote", "database"}
+	expectedCommands := []string{"init", "snapshot", "store", "restore", "prune", "info", "version", "remote", "database"}
 	for _, expected := range expectedCommands {
 		found := false
 		for _, cmd := range cmd.Commands() {

internal/cli/init.go

@@ -0,0 +1,247 @@
+package cli
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+
+	"github.com/spf13/cobra"
+)
+
+const defaultConfigTemplate = `# vaultik configuration
+# Documentation: https://git.eeqj.de/sneak/vaultik
+
+# ─── REQUIRED ────────────────────────────────────────────────────────────────
+
+# Age recipient public keys for encryption.
+# Backups are encrypted to ALL listed recipients. Any one of the corresponding
+# private keys can decrypt. Generate a keypair with:
+#   age-keygen -o key.txt && grep 'public key' key.txt
+age_recipients:
+  - age1REPLACE_WITH_YOUR_PUBLIC_KEY
+
+# Named snapshots. Each snapshot backs up one or more paths and can have its
+# own exclude patterns in addition to the global excludes below.
+#
+# Exclude pattern semantics:
+#   - Patterns starting with / are anchored to the snapshot path root
+#     (e.g. "/Library/Caches" matches only ~/Library/Caches in a ~ snapshot)
+#   - Patterns without a leading / match anywhere in the tree
+#     (e.g. ".cache" matches any directory named .cache at any depth)
+#   - Globs are supported: *, **, ?
+snapshots:
+  home:
+    paths:
+      - "~"
+    exclude:
+      # Trash, temp, and filesystem metadata
+      - "/.Trash"
+      - "/.Trashes"
+      - "/.fseventsd"
+      - "/.Spotlight-V100"
+      - "/.TemporaryItems"
+      - "/tmp"
+      - "/.rnd"
+      - ".DS_Store"
+      # Caches and package manager state (rebuildable)
+      - ".cache"
+      - ".bundle"
+      - "/.cpan/build"
+      - "/.cpan/sources"
+      - "/.gradle/caches"
+      - "/.dropbox"
+      - "/.minikube/cache"
+      - "/.local/share/containers/podman/machine"
+      - "/.persepolis"
+      - "/Library/Caches"
+      - "/Library/Logs"
+      - "/Library/Cookies"
+      - "/Library/Metadata"
+      - "/Library/Suggestions"
+      - "/Library/PubSub"
+      - "/Library/Homebrew"
+      - "/Library/Developer"
+      - "/Library/Google/GoogleSoftwareUpdate"
+      - "/Library/Preferences/Macromedia/Flash Player"
+      - "/Library/Preferences/SDMHelpData"
+      - "/Library/VoiceTrigger/SAT"
+      # Language/toolchain package caches (rebuildable from registries)
+      - "/.npm"
+      - "/.cargo/registry"
+      - "/.cargo/git"
+      - "/.rustup/toolchains"
+      - "/go/pkg/mod"
+      - "/.m2/repository"
+      - "/.vagrant.d/boxes"
+      - "node_modules"
+      - "__pycache__"
+      - ".venv"
+      # Virtual machine disk images (huge; remove these lines to back them up)
+      - "/Parallels"
+      - "/Virtual Machines.localized"
+      - "/VirtualBox VMs"
+      - "/.orbstack"
+      - "/Library/Containers/com.utmapp.UTM"
+      # Downloaded LLM models (huge, re-downloadable)
+      - "/.ollama/models"
+      - "/.lmstudio/models"
+      # Cloud-synced storage. These are synced to a provider already, and on
+      # modern macOS may contain dataless placeholder files that the backup
+      # would force-download in full.
+      - "/Library/CloudStorage"
+      - "/Library/Mobile Documents"
+      # Android SDK and emulator images (re-downloadable)
+      - "/Library/Android/sdk"
+      - "/.android/avd"
+      # Cloud-synced or restorable-from-server data
+      - "/Library/Mail"
+      - "/Library/Mail Downloads"
+      - "/Library/Safari"
+      - "/Library/Application Support/Evernote"
+      - "/Library/Application Support/MobileSync"
+      - "/Library/Application Support/SyncServices"
+      - "/Library/Application Support/protonmail/bridge/cache"
+      - "/Library/Application Support/Syncthing/index-*"
+      - "/Library/Syncthing/folders"
+      - "/Documents/Dropbox/.dropbox.cache"
+      # Large rebuildable app data (games, media caches, device backups)
+      - "/Applications/Fortnite"
+      - "/Documents/Steam Content"
+      - "/Library/Application Support/Ableton"
+      - "/Library/Application Support/CrossOver Games"
+      - "/Library/Application Support/SecondLife/cache"
+      - "/Library/Application Support/Steam/SteamApps"
+      - "/Library/Containers/com.docker.docker"
+      - "/Library/Group Containers/group.com.apple.secure-control-center-preferences"
+      - "/Library/iTunes/iPad Software Updates"
+      - "/Library/iTunes/iPhone Software Updates"
+      - "/Movies/CacheClip"
+      - "/Movies/ProxyMedia"
+      - "/Music/iTunes/Album Artwork"
+      - "/Pictures/iPod Photo Cache"
+
+  # Third-party applications. OS-provided apps live in /System/Applications
+  # on modern macOS and are never in /Applications, but Apple-installed
+  # App Store apps (Safari, GarageBand, iWork, iMovie) are excluded since
+  # they are re-downloadable.
+  apps:
+    paths:
+      - /Applications
+    exclude:
+      - ".DS_Store"
+      - "/Safari.app"
+      - "/GarageBand.app"
+      - "/iMovie.app"
+      - "/Keynote.app"
+      - "/Numbers.app"
+      - "/Pages.app"
+      - "/Xcode.app"
+      - "/Spotify.app"
+      - "/Steam.app"
+      - "/VirtualBox.app"
+      - "/Utilities/Adobe Installers"
+
+# Storage backend (pick ONE of the three forms below).
+#
+# S3-compatible:
+#   storage_url: "s3://mybucket/backups?endpoint=s3.example.com&region=us-east-1"
+#   (also set s3.access_key_id and s3.secret_access_key below)
+#
+# Local filesystem:
+#   storage_url: "file:///mnt/backups/vaultik"
+#
+# Rclone (requires rclone configured separately):
+#   storage_url: "rclone://myremote/path/to/backups"
+storage_url: ""
+
+# ─── S3 CREDENTIALS (required for s3:// storage_url) ────────────────────────
+
+# s3:
+#   access_key_id: YOUR_ACCESS_KEY
+#   secret_access_key: YOUR_SECRET_KEY
+#   # region: us-east-1        # Default: us-east-1
+#   # use_ssl: true            # Default: true
+#   # part_size: 5MB           # Multipart upload part size. Default: 5MB
+
+# ─── OPTIONAL ────────────────────────────────────────────────────────────────
+
+# Global exclude patterns applied to ALL snapshots.
+# Snapshot-specific excludes are additive.
+# exclude:
+#   - "*.log"
+#   - "*.tmp"
+#   - ".git"
+#   - "node_modules"
+
+# Average chunk size for content-defined chunking (FastCDC).
+# Smaller = better deduplication but more metadata overhead.
+# Accepts: 1MB, 10M, 64KB, etc.
+# Default: 10MB
+# chunk_size: 10MB
+
+# Maximum blob size before splitting into a new blob.
+# Accepts: 1GB, 10G, 500MB, etc.
+# Default: 10GB
+# blob_size_limit: 10GB
+
+# Zstd compression level (1-19). Higher = better ratio but slower.
+# Default: 3
+# compression_level: 3
+
+# Hostname used in snapshot IDs. Default: system hostname.
+# hostname: myserver
+
+# Path to the local SQLite index database.
+# Default: ~/.local/share/berlin.sneak.app.vaultik/index.sqlite
+# index_path: /path/to/index.sqlite
+`
+
+// NewInitCommand creates the init command that writes a default config file.
+func NewInitCommand() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "init",
+		Short: "Write a default config file",
+		Long: `Creates a default configuration file with commented explanations
+for every setting. If a config file already exists at the target path,
+the command refuses to overwrite it.
+
+The config is written to the path from --config, $VAULTIK_CONFIG, or
+the platform default config directory (e.g. ~/Library/Application Support/
+on macOS, ~/.config/ on Linux, /etc/vaultik/ as root).`,
+		Args: cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			path := configPathForInit()
+
+			if _, err := os.Stat(path); err == nil {
+				return fmt.Errorf("config file already exists: %s", path)
+			}
+
+			dir := filepath.Dir(path)
+			if err := os.MkdirAll(dir, 0o755); err != nil {
+				return fmt.Errorf("creating config directory %s: %w", dir, err)
+			}
+
+			if err := os.WriteFile(path, []byte(defaultConfigTemplate), 0o600); err != nil {
+				return fmt.Errorf("writing config file: %w", err)
+			}
+
+			fmt.Printf("Config written to %s\n", path)
+			fmt.Println("Edit it to set your age_recipients, snapshots, and storage_url.")
+			return nil
+		},
+	}
+
+	return cmd
+}
+
+// configPathForInit returns the config path to write, checking --config flag,
+// VAULTIK_CONFIG env, and the platform default.
+func configPathForInit() string {
+	if rootFlags.ConfigPath != "" {
+		return rootFlags.ConfigPath
+	}
+	if envPath := os.Getenv("VAULTIK_CONFIG"); envPath != "" {
+		return envPath
+	}
+	return DefaultConfigPath()
+}

internal/cli/init_test.go

@@ -0,0 +1,43 @@
+package cli
+
+import (
+	"testing"
+
+	"git.eeqj.de/sneak/vaultik/internal/config"
+	"gopkg.in/yaml.v3"
+)
+
+// TestDefaultConfigTemplateParses ensures the init template is valid YAML
+// that unmarshals into the Config struct with the expected snapshots.
+func TestDefaultConfigTemplateParses(t *testing.T) {
+	var cfg config.Config
+	if err := yaml.Unmarshal([]byte(defaultConfigTemplate), &cfg); err != nil {
+		t.Fatalf("default config template is not valid YAML: %v", err)
+	}
+
+	if len(cfg.AgeRecipients) != 1 {
+		t.Errorf("expected 1 placeholder age recipient, got %d", len(cfg.AgeRecipients))
+	}
+
+	home, ok := cfg.Snapshots["home"]
+	if !ok {
+		t.Fatal("expected 'home' snapshot in default config")
+	}
+	if len(home.Paths) == 0 {
+		t.Error("home snapshot should have at least one path")
+	}
+	if len(home.Exclude) == 0 {
+		t.Error("home snapshot should have exclude patterns")
+	}
+
+	apps, ok := cfg.Snapshots["apps"]
+	if !ok {
+		t.Fatal("expected 'apps' snapshot in default config")
+	}
+	if len(apps.Paths) != 1 || apps.Paths[0] != "/Applications" {
+		t.Errorf("apps snapshot should back up /Applications, got %v", apps.Paths)
+	}
+	if len(apps.Exclude) == 0 {
+		t.Error("apps snapshot should have exclude patterns")
+	}
+}

internal/cli/root.go

@@ -3,7 +3,9 @@ package cli
 import (
 	"fmt"
 	"os"
+	"path/filepath"
 
+	"github.com/adrg/xdg"
 	"github.com/spf13/cobra"
 )
 
@@ -32,13 +34,14 @@ on the source system.`,
 	}
 
 	// Add global flags
-	cmd.PersistentFlags().StringVar(&rootFlags.ConfigPath, "config", "", "Path to config file (default: $VAULTIK_CONFIG or /etc/vaultik/config.yml)")
+	cmd.PersistentFlags().StringVar(&rootFlags.ConfigPath, "config", "", "Path to config file (default: $VAULTIK_CONFIG or platform config dir)")
 	cmd.PersistentFlags().BoolVarP(&rootFlags.Verbose, "verbose", "v", false, "Enable verbose output")
 	cmd.PersistentFlags().BoolVar(&rootFlags.Debug, "debug", false, "Enable debug output")
 	cmd.PersistentFlags().BoolVarP(&rootFlags.Quiet, "quiet", "q", false, "Suppress non-error output")
 
 	// Add subcommands
 	cmd.AddCommand(
+		NewInitCommand(),
 		NewRestoreCommand(),
 		NewPruneCommand(),
 		NewStoreCommand(),
@@ -59,25 +62,41 @@ func GetRootFlags() RootFlags {
 }
 
 // ResolveConfigPath resolves the config file path from flags, environment, or default.
-// It checks in order: 1) --config flag, 2) VAULTIK_CONFIG environment variable,
-// 3) default location /etc/vaultik/config.yml. Returns an error if no valid
-// config file can be found through any of these methods.
+// Search order: --config flag, VAULTIK_CONFIG env, XDG config dir, /etc/vaultik/config.yml.
 func ResolveConfigPath() (string, error) {
-	// First check global flag
 	if rootFlags.ConfigPath != "" {
 		return rootFlags.ConfigPath, nil
 	}
 
-	// Then check environment variable
 	if envPath := os.Getenv("VAULTIK_CONFIG"); envPath != "" {
 		return envPath, nil
 	}
 
-	// Finally check default location
-	defaultPath := "/etc/vaultik/config.yml"
-	if _, err := os.Stat(defaultPath); err == nil {
-		return defaultPath, nil
+	for _, path := range defaultConfigPaths() {
+		if _, err := os.Stat(path); err == nil {
+			return path, nil
+		}
 	}
 
-	return "", fmt.Errorf("no config file found; specify one with --config, set VAULTIK_CONFIG, or create %s", defaultPath)
+	return "", fmt.Errorf("no config file found; run 'vaultik init' to create one, or specify with --config")
+}
+
+// defaultConfigPaths returns the ordered list of config paths to search.
+// On macOS: ~/Library/Application Support/vaultik/config.yml
+// On Linux: ~/.config/vaultik/config.yml
+// Fallback: /etc/vaultik/config.yml
+func defaultConfigPaths() []string {
+	return []string{
+		filepath.Join(xdg.ConfigHome, "vaultik", "config.yml"),
+		"/etc/vaultik/config.yml",
+	}
+}
+
+// DefaultConfigPath returns the platform-appropriate default config path.
+// Used by the init command and in help text.
+func DefaultConfigPath() string {
+	if os.Getuid() == 0 {
+		return "/etc/vaultik/config.yml"
+	}
+	return filepath.Join(xdg.ConfigHome, "vaultik", "config.yml")
 }