Merge remote-tracking branch 'origin/master' into feat/home-manager

.github/workflows/ci.yaml

@@ -32,9 +32,9 @@ jobs:
           go-version: "1.25.0"
 
       - name: lint
-        uses: golangci/golangci-lint-action@v6
+        uses: golangci/golangci-lint-action@v8
         with:
-          version: latest
+          version: v2.5.0
 
   nix-build:
     strategy:
@@ -44,9 +44,7 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
-      - uses: cachix/install-nix-action@v30
+      - uses: DeterminateSystems/nix-installer-action@v17
-        with:
-          github_access_token: ${{ secrets.GITHUB_TOKEN }}
 
       - uses: nix-community/cache-nix-action@v6
         with:

README.md

@@ -6,13 +6,29 @@ a friendlier `ss` / `netstat` for humans. inspect network connections with a cle
 
 ## install
 
+### homebrew
+
+```bash
+brew install snitch
+```
+
+> thanks to [@bevanjkay](https://github.com/bevanjkay) for adding snitch to homebrew-core
+
 ### go
 
 ```bash
 go install github.com/karol-broda/snitch@latest
 ```
 
-### nixos / nix
+### nixpkgs
+
+```bash
+nix-env -iA nixpkgs.snitch
+```
+
+> thanks to [@DieracDelta](https://github.com/DieracDelta) for adding snitch to nixpkgs
+
+### nixos / nix (flake)
 
 ```bash
 # try it
@@ -28,6 +44,45 @@ nix profile install github:karol-broda/snitch
 # then use: inputs.snitch.packages.${system}.default
 ```
 
+### home-manager (flake)
+
+add snitch to your flake inputs and import the home-manager module:
+
+```nix
+{
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+    home-manager.url = "github:nix-community/home-manager";
+    snitch.url = "github:karol-broda/snitch";
+  };
+
+  outputs = { nixpkgs, home-manager, snitch, ... }: {
+    homeConfigurations."user" = home-manager.lib.homeManagerConfiguration {
+      pkgs = nixpkgs.legacyPackages.x86_64-linux;
+      modules = [
+        snitch.homeManagerModules.default
+        {
+          programs.snitch = {
+            enable = true;
+            # optional: use the flake's package instead of nixpkgs
+            # package = snitch.packages.x86_64-linux.default;
+            settings = {
+              defaults = {
+                theme = "catppuccin-mocha";
+                interval = "2s";
+                resolve = true;
+              };
+            };
+          };
+        }
+      ];
+    };
+  };
+}
+```
+
+available themes: `ansi`, `catppuccin-mocha`, `catppuccin-macchiato`, `catppuccin-frappe`, `catppuccin-latte`, `gruvbox-dark`, `gruvbox-light`, `dracula`, `nord`, `tokyo-night`, `tokyo-night-storm`, `tokyo-night-light`, `solarized-dark`, `solarized-light`, `one-dark`, `mono`
+
 ### arch linux (aur)
 
 ```bash
@@ -222,8 +277,23 @@ optional config file at `~/.config/snitch/snitch.toml`:
 numeric = false      # disable name resolution
 dns_cache = true     # cache dns lookups (set to false to disable)
 theme = "auto"       # color theme: auto, dark, light, mono
+
+[tui]
+remember_state = false   # remember view options between sessions
 ```
 
+### remembering view options
+
+when `remember_state = true`, the tui will save and restore:
+
+- filter toggles (tcp/udp, listen/established/other)
+- sort field and direction
+- address and port resolution settings
+
+state is saved to `$XDG_STATE_HOME/snitch/tui.json` (defaults to `~/.local/state/snitch/tui.json`).
+
+cli flags always take priority over saved state.
+
 ### environment variables
 
 ```bash

cmd/cli_test.go

@@ -6,6 +6,7 @@ import (
 	"strings"
 	"testing"
 
+	"github.com/karol-broda/snitch/internal/errutil"
 	"github.com/karol-broda/snitch/internal/testutil"
 )
 
@@ -407,16 +408,16 @@ func TestEnvironmentVariables(t *testing.T) {
 		oldEnvVars := make(map[string]string)
 		for key, value := range tt.envVars {
 			oldEnvVars[key] = os.Getenv(key)
-			os.Setenv(key, value)
+			errutil.Setenv(key, value)
 		}
 
 		// Clean up environment variables
 		defer func() {
 			for key, oldValue := range oldEnvVars {
 				if oldValue == "" {
-					os.Unsetenv(key)
+					errutil.Unsetenv(key)
 				} else {
-					os.Setenv(key, oldValue)
+					errutil.Setenv(key, oldValue)
 				}
 			}
 		}()

cmd/ls.go

@@ -8,16 +8,18 @@ import (
 	"log"
 	"os"
 	"os/exec"
-	"github.com/karol-broda/snitch/internal/collector"
-	"github.com/karol-broda/snitch/internal/color"
-	"github.com/karol-broda/snitch/internal/config"
-	"github.com/karol-broda/snitch/internal/resolver"
 	"strconv"
 	"strings"
 	"text/tabwriter"
 
 	"github.com/charmbracelet/lipgloss"
 	"github.com/spf13/cobra"
+
+	"github.com/karol-broda/snitch/internal/collector"
+	"github.com/karol-broda/snitch/internal/color"
+	"github.com/karol-broda/snitch/internal/config"
+	"github.com/karol-broda/snitch/internal/errutil"
+	"github.com/karol-broda/snitch/internal/resolver"
 	"github.com/tidwall/pretty"
 	"golang.org/x/term"
 )
@@ -185,7 +187,7 @@ func printCSV(conns []collector.Connection, headers bool, timestamp bool, select
 
 func printPlainTable(conns []collector.Connection, headers bool, timestamp bool, selectedFields []string) {
 	w := tabwriter.NewWriter(os.Stdout, 0, 0, 3, ' ', 0)
-	defer w.Flush()
+	defer errutil.Flush(w)
 
 	if len(selectedFields) == 0 {
 		selectedFields = []string{"pid", "process", "user", "proto", "state", "laddr", "lport", "raddr", "rport"}
@@ -199,7 +201,7 @@ func printPlainTable(conns []collector.Connection, headers bool, timestamp bool,
 		for _, field := range selectedFields {
 			headerRow = append(headerRow, strings.ToUpper(field))
 		}
-		fmt.Fprintln(w, strings.Join(headerRow, "\t"))
+		errutil.Ignore(fmt.Fprintln(w, strings.Join(headerRow, "\t")))
 	}
 
 	for _, conn := range conns {
@@ -208,7 +210,7 @@ func printPlainTable(conns []collector.Connection, headers bool, timestamp bool,
 		for _, field := range selectedFields {
 			row = append(row, fieldMap[field])
 		}
-		fmt.Fprintln(w, strings.Join(row, "\t"))
+		errutil.Ignore(fmt.Fprintln(w, strings.Join(row, "\t")))
 	}
 }
 

cmd/stats.go

@@ -8,7 +8,6 @@ import (
 	"log"
 	"os"
 	"os/signal"
-	"github.com/karol-broda/snitch/internal/collector"
 	"sort"
 	"strconv"
 	"strings"
@@ -17,6 +16,9 @@ import (
 	"time"
 
 	"github.com/spf13/cobra"
+
+	"github.com/karol-broda/snitch/internal/collector"
+	"github.com/karol-broda/snitch/internal/errutil"
 )
 
 type StatsData struct {
@@ -227,19 +229,19 @@ func printStatsCSV(stats *StatsData, headers bool) {
 
 func printStatsTable(stats *StatsData, headers bool) {
 	w := tabwriter.NewWriter(os.Stdout, 0, 0, 3, ' ', 0)
-	defer w.Flush()
+	defer errutil.Flush(w)
 
 	if headers {
-		fmt.Fprintf(w, "TIMESTAMP\t%s\n", stats.Timestamp.Format(time.RFC3339))
+		errutil.Ignore(fmt.Fprintf(w, "TIMESTAMP\t%s\n", stats.Timestamp.Format(time.RFC3339)))
-		fmt.Fprintf(w, "TOTAL CONNECTIONS\t%d\n", stats.Total)
+		errutil.Ignore(fmt.Fprintf(w, "TOTAL CONNECTIONS\t%d\n", stats.Total))
-		fmt.Fprintln(w)
+		errutil.Ignore(fmt.Fprintln(w))
 	}
 
 	// Protocol breakdown
 	if len(stats.ByProto) > 0 {
 		if headers {
-			fmt.Fprintln(w, "BY PROTOCOL:")
+			errutil.Ignore(fmt.Fprintln(w, "BY PROTOCOL:"))
-			fmt.Fprintln(w, "PROTO\tCOUNT")
+			errutil.Ignore(fmt.Fprintln(w, "PROTO\tCOUNT"))
 		}
 		protocols := make([]string, 0, len(stats.ByProto))
 		for proto := range stats.ByProto {
@@ -247,16 +249,16 @@ func printStatsTable(stats *StatsData, headers bool) {
 		}
 		sort.Strings(protocols)
 		for _, proto := range protocols {
-			fmt.Fprintf(w, "%s\t%d\n", strings.ToUpper(proto), stats.ByProto[proto])
+			errutil.Ignore(fmt.Fprintf(w, "%s\t%d\n", strings.ToUpper(proto), stats.ByProto[proto]))
 		}
-		fmt.Fprintln(w)
+		errutil.Ignore(fmt.Fprintln(w))
 	}
 
 	// State breakdown
 	if len(stats.ByState) > 0 {
 		if headers {
-			fmt.Fprintln(w, "BY STATE:")
+			errutil.Ignore(fmt.Fprintln(w, "BY STATE:"))
-			fmt.Fprintln(w, "STATE\tCOUNT")
+			errutil.Ignore(fmt.Fprintln(w, "STATE\tCOUNT"))
 		}
 		states := make([]string, 0, len(stats.ByState))
 		for state := range stats.ByState {
@@ -264,16 +266,16 @@ func printStatsTable(stats *StatsData, headers bool) {
 		}
 		sort.Strings(states)
 		for _, state := range states {
-			fmt.Fprintf(w, "%s\t%d\n", state, stats.ByState[state])
+			errutil.Ignore(fmt.Fprintf(w, "%s\t%d\n", state, stats.ByState[state]))
 		}
-		fmt.Fprintln(w)
+		errutil.Ignore(fmt.Fprintln(w))
 	}
 
 	// Process breakdown (top 10)
 	if len(stats.ByProc) > 0 {
 		if headers {
-			fmt.Fprintln(w, "BY PROCESS (TOP 10):")
+			errutil.Ignore(fmt.Fprintln(w, "BY PROCESS (TOP 10):"))
-			fmt.Fprintln(w, "PID\tPROCESS\tCOUNT")
+			errutil.Ignore(fmt.Fprintln(w, "PID\tPROCESS\tCOUNT"))
 		}
 		limit := 10
 		if len(stats.ByProc) < limit {
@@ -281,7 +283,7 @@ func printStatsTable(stats *StatsData, headers bool) {
 		}
 		for i := 0; i < limit; i++ {
 			proc := stats.ByProc[i]
-			fmt.Fprintf(w, "%d\t%s\t%d\n", proc.PID, proc.Process, proc.Count)
+			errutil.Ignore(fmt.Fprintf(w, "%d\t%s\t%d\n", proc.PID, proc.Process, proc.Count))
 		}
 	}
 }

cmd/top.go

@@ -38,6 +38,7 @@ var topCmd = &cobra.Command{
 			ResolveAddrs:  resolveAddrs,
 			ResolvePorts:  resolvePorts,
 			NoCache:       effectiveNoCache,
+			RememberState: cfg.TUI.RememberState,
 		}
 
 		// if any filter flag is set, use exclusive mode

cmd/upgrade.go

@@ -18,6 +18,7 @@ import (
 	"github.com/fatih/color"
 	"github.com/spf13/cobra"
 
+	"github.com/karol-broda/snitch/internal/errutil"
 	"github.com/karol-broda/snitch/internal/tui"
 )
 
@@ -93,13 +94,13 @@ func runUpgrade(cmd *cobra.Command, args []string) error {
 
 	if currentClean == latestClean {
 		green := color.New(color.FgGreen)
-		green.Println(tui.SymbolSuccess + " you are running the latest version")
+		errutil.Println(green, tui.SymbolSuccess+" you are running the latest version")
 		return nil
 	}
 
 	if current == "dev" {
 		yellow := color.New(color.FgYellow)
-		yellow.Println(tui.SymbolWarning + " you are running a development build")
+		errutil.Println(yellow, tui.SymbolWarning+" you are running a development build")
 		fmt.Println()
 		fmt.Println("use one of the methods below to install a release version:")
 		fmt.Println()
@@ -108,7 +109,7 @@ func runUpgrade(cmd *cobra.Command, args []string) error {
 	}
 
 	green := color.New(color.FgGreen, color.Bold)
-	green.Printf(tui.SymbolSuccess+" update available: %s "+tui.SymbolArrowRight+" %s\n", current, latest)
+	errutil.Printf(green, tui.SymbolSuccess+" update available: %s "+tui.SymbolArrowRight+" %s\n", current, latest)
 	fmt.Println()
 
 	if !upgradeYes {
@@ -116,8 +117,8 @@ func runUpgrade(cmd *cobra.Command, args []string) error {
 		fmt.Println()
 		faint := color.New(color.Faint)
 		cmdStyle := color.New(color.FgCyan)
-		faint.Print("  in-place      ")
+		errutil.Print(faint, "  in-place      ")
-		cmdStyle.Println("snitch upgrade --yes")
+		errutil.Println(cmdStyle, "snitch upgrade --yes")
 		return nil
 	}
 
@@ -134,17 +135,17 @@ func handleSpecificVersion(current, target string) error {
 
 	if isVersionLower(targetClean, firstUpgradeVersion) {
 		yellow := color.New(color.FgYellow)
-		yellow.Printf(tui.SymbolWarning+" warning: the upgrade command was introduced in v%s\n", firstUpgradeVersion)
+		errutil.Printf(yellow, tui.SymbolWarning+" warning: the upgrade command was introduced in v%s\n", firstUpgradeVersion)
 		faint := color.New(color.Faint)
-		faint.Printf("  version %s does not include this command\n", target)
+		errutil.Printf(faint, "  version %s does not include this command\n", target)
-		faint.Println("  you will need to use other methods to upgrade from that version")
+		errutil.Println(faint, "  you will need to use other methods to upgrade from that version")
 		fmt.Println()
 	}
 
 	currentClean := strings.TrimPrefix(current, "v")
 	if currentClean == targetClean {
 		green := color.New(color.FgGreen)
-		green.Println(tui.SymbolSuccess + " you are already running this version")
+		errutil.Println(green, tui.SymbolSuccess+" you are already running this version")
 		return nil
 	}
 
@@ -153,15 +154,15 @@ func handleSpecificVersion(current, target string) error {
 		cmdStyle := color.New(color.FgCyan)
 		if isVersionLower(targetClean, currentClean) {
 			yellow := color.New(color.FgYellow)
-			yellow.Printf(tui.SymbolArrowDown+" this will downgrade from %s to %s\n", current, target)
+			errutil.Printf(yellow, tui.SymbolArrowDown+" this will downgrade from %s to %s\n", current, target)
 		} else {
 			green := color.New(color.FgGreen)
-			green.Printf(tui.SymbolArrowUp+" this will upgrade from %s to %s\n", current, target)
+			errutil.Printf(green, tui.SymbolArrowUp+" this will upgrade from %s to %s\n", current, target)
 		}
 		fmt.Println()
-		faint.Print("run ")
+		errutil.Print(faint, "run ")
-		cmdStyle.Printf("snitch upgrade --version %s --yes", target)
+		errutil.Printf(cmdStyle, "snitch upgrade --version %s --yes", target)
-		faint.Println(" to proceed")
+		errutil.Println(faint, " to proceed")
 		return nil
 	}
 
@@ -175,20 +176,20 @@ func handleNixUpgrade(current, latest string) error {
 	currentCommit := extractCommitFromVersion(current)
 	dirty := isNixDirty(current)
 
-	faint.Print("current  ")
+	errutil.Print(faint, "current  ")
-	version.Print(current)
+	errutil.Print(version, current)
 	if currentCommit != "" {
-		faint.Printf(" (commit %s)", currentCommit)
+		errutil.Printf(faint, " (commit %s)", currentCommit)
 	}
 	fmt.Println()
 
-	faint.Print("latest   ")
+	errutil.Print(faint, "latest   ")
-	version.Println(latest)
+	errutil.Println(version, latest)
 	fmt.Println()
 
 	if dirty {
 		yellow := color.New(color.FgYellow)
-		yellow.Println(tui.SymbolWarning + " you are running a dirty nix build (uncommitted changes)")
+		errutil.Println(yellow, tui.SymbolWarning+" you are running a dirty nix build (uncommitted changes)")
 		fmt.Println()
 		printNixUpgradeInstructions()
 		return nil
@@ -196,8 +197,8 @@ func handleNixUpgrade(current, latest string) error {
 
 	if currentCommit == "" {
 		yellow := color.New(color.FgYellow)
-		yellow.Println(tui.SymbolWarning + " this is a nix installation")
+		errutil.Println(yellow, tui.SymbolWarning+" this is a nix installation")
-		faint.Println("  nix store is immutable; use nix commands to upgrade")
+		errutil.Println(faint, "  nix store is immutable; use nix commands to upgrade")
 		fmt.Println()
 		printNixUpgradeInstructions()
 		return nil
@@ -205,11 +206,11 @@ func handleNixUpgrade(current, latest string) error {
 
 	releaseCommit, err := fetchCommitForTag(latest)
 	if err != nil {
-		faint.Printf("  (could not fetch release commit: %v)\n", err)
+		errutil.Printf(faint, "  (could not fetch release commit: %v)\n", err)
 		fmt.Println()
 		yellow := color.New(color.FgYellow)
-		yellow.Println(tui.SymbolWarning + " this is a nix installation")
+		errutil.Println(yellow, tui.SymbolWarning+" this is a nix installation")
-		faint.Println("  nix store is immutable; use nix commands to upgrade")
+		errutil.Println(faint, "  nix store is immutable; use nix commands to upgrade")
 		fmt.Println()
 		printNixUpgradeInstructions()
 		return nil
@@ -222,20 +223,20 @@ func handleNixUpgrade(current, latest string) error {
 
 	if strings.HasPrefix(releaseCommit, currentCommit) || strings.HasPrefix(currentCommit, releaseShort) {
 		green := color.New(color.FgGreen)
-		green.Printf(tui.SymbolSuccess+" you are running %s (commit %s)\n", latest, releaseShort)
+		errutil.Printf(green, tui.SymbolSuccess+" you are running %s (commit %s)\n", latest, releaseShort)
 		return nil
 	}
 
 	comparison, err := compareCommits(latest, currentCommit)
 	if err != nil {
 		green := color.New(color.FgGreen, color.Bold)
-		green.Printf(tui.SymbolSuccess+" update available: %s "+tui.SymbolArrowRight+" %s\n", currentCommit, latest)
+		errutil.Printf(green, tui.SymbolSuccess+" update available: %s "+tui.SymbolArrowRight+" %s\n", currentCommit, latest)
-		faint.Printf("  your commit: %s\n", currentCommit)
+		errutil.Printf(faint, "  your commit: %s\n", currentCommit)
-		faint.Printf("  release:     %s (%s)\n", releaseShort, latest)
+		errutil.Printf(faint, "  release:     %s (%s)\n", releaseShort, latest)
 		fmt.Println()
 		yellow := color.New(color.FgYellow)
-		yellow.Println(tui.SymbolWarning + " this is a nix installation")
+		errutil.Println(yellow, tui.SymbolWarning+" this is a nix installation")
-		faint.Println("  nix store is immutable; use nix commands to upgrade")
+		errutil.Println(faint, "  nix store is immutable; use nix commands to upgrade")
 		fmt.Println()
 		printNixUpgradeInstructions()
 		return nil
@@ -243,30 +244,30 @@ func handleNixUpgrade(current, latest string) error {
 
 	if comparison.AheadBy > 0 {
 		cyan := color.New(color.FgCyan)
-		cyan.Printf(tui.SymbolArrowUp+" you are %d commit(s) ahead of %s\n", comparison.AheadBy, latest)
+		errutil.Printf(cyan, tui.SymbolArrowUp+" you are %d commit(s) ahead of %s\n", comparison.AheadBy, latest)
-		faint.Printf("  your commit: %s\n", currentCommit)
+		errutil.Printf(faint, "  your commit: %s\n", currentCommit)
-		faint.Printf("  release:     %s (%s)\n", releaseShort, latest)
+		errutil.Printf(faint, "  release:     %s (%s)\n", releaseShort, latest)
 		fmt.Println()
-		faint.Println("you are running a newer build than the latest release")
+		errutil.Println(faint, "you are running a newer build than the latest release")
 		return nil
 	}
 
 	if comparison.BehindBy > 0 {
 		green := color.New(color.FgGreen, color.Bold)
-		green.Printf(tui.SymbolSuccess+" update available: %d commit(s) behind %s\n", comparison.BehindBy, latest)
+		errutil.Printf(green, tui.SymbolSuccess+" update available: %d commit(s) behind %s\n", comparison.BehindBy, latest)
-		faint.Printf("  your commit: %s\n", currentCommit)
+		errutil.Printf(faint, "  your commit: %s\n", currentCommit)
-		faint.Printf("  release:     %s (%s)\n", releaseShort, latest)
+		errutil.Printf(faint, "  release:     %s (%s)\n", releaseShort, latest)
 		fmt.Println()
 		yellow := color.New(color.FgYellow)
-		yellow.Println(tui.SymbolWarning + " this is a nix installation")
+		errutil.Println(yellow, tui.SymbolWarning+" this is a nix installation")
-		faint.Println("  nix store is immutable; use nix commands to upgrade")
+		errutil.Println(faint, "  nix store is immutable; use nix commands to upgrade")
 		fmt.Println()
 		printNixUpgradeInstructions()
 		return nil
 	}
 
 	green := color.New(color.FgGreen)
-	green.Printf(tui.SymbolSuccess+" you are running %s (commit %s)\n", latest, releaseShort)
+	errutil.Printf(green, tui.SymbolSuccess+" you are running %s (commit %s)\n", latest, releaseShort)
 	return nil
 }
 
@@ -278,22 +279,22 @@ func handleNixSpecificVersion(current, target string) error {
 	printVersionComparisonTarget(current, target)
 
 	yellow := color.New(color.FgYellow)
-	yellow.Println(tui.SymbolWarning + " this is a nix installation")
+	errutil.Println(yellow, tui.SymbolWarning+" this is a nix installation")
 	faint := color.New(color.Faint)
-	faint.Println("  nix store is immutable; in-place upgrades are not supported")
+	errutil.Println(faint, "  nix store is immutable; in-place upgrades are not supported")
 	fmt.Println()
 
 	bold := color.New(color.Bold)
 	cmd := color.New(color.FgCyan)
 
-	bold.Println("to install a specific version with nix:")
+	errutil.Println(bold, "to install a specific version with nix:")
 	fmt.Println()
 
-	faint.Print("  specific ref    ")
+	errutil.Print(faint, "  specific ref    ")
-	cmd.Printf("nix profile install github:%s/%s/%s\n", repoOwner, repoName, target)
+	errutil.Printf(cmd, "nix profile install github:%s/%s/%s\n", repoOwner, repoName, target)
 
-	faint.Print("  latest          ")
+	errutil.Print(faint, "  latest          ")
-	cmd.Printf("nix profile install github:%s/%s\n", repoOwner, repoName)
+	errutil.Printf(cmd, "nix profile install github:%s/%s\n", repoOwner, repoName)
 
 	return nil
 }
@@ -333,7 +334,7 @@ func fetchLatestVersion() (string, error) {
 	if err != nil {
 		return "", err
 	}
-	defer resp.Body.Close()
+	defer errutil.Close(resp.Body)
 
 	if resp.StatusCode != http.StatusOK {
 		return "", fmt.Errorf("github api returned status %d", resp.StatusCode)
@@ -355,10 +356,10 @@ func printVersionComparison(current, latest string) {
 	faint := color.New(color.Faint)
 	version := color.New(color.FgCyan)
 
-	faint.Print("current  ")
+	errutil.Print(faint, "current  ")
-	version.Println(current)
+	errutil.Println(version, current)
-	faint.Print("latest   ")
+	errutil.Print(faint, "latest   ")
-	version.Println(latest)
+	errutil.Println(version, latest)
 	fmt.Println()
 }
 
@@ -366,10 +367,10 @@ func printVersionComparisonTarget(current, target string) {
 	faint := color.New(color.Faint)
 	version := color.New(color.FgCyan)
 
-	faint.Print("current  ")
+	errutil.Print(faint, "current  ")
-	version.Println(current)
+	errutil.Println(version, current)
-	faint.Print("target   ")
+	errutil.Print(faint, "target   ")
-	version.Println(target)
+	errutil.Println(version, target)
 	fmt.Println()
 }
 
@@ -378,20 +379,20 @@ func printUpgradeInstructions() {
 	faint := color.New(color.Faint)
 	cmd := color.New(color.FgCyan)
 
-	bold.Println("upgrade options:")
+	errutil.Println(bold, "upgrade options:")
 	fmt.Println()
 
-	faint.Print("  go install    ")
+	errutil.Print(faint, "  go install    ")
-	cmd.Printf("go install github.com/%s/%s@latest\n", repoOwner, repoName)
+	errutil.Printf(cmd, "go install github.com/%s/%s@latest\n", repoOwner, repoName)
 
-	faint.Print("  shell script  ")
+	errutil.Print(faint, "  shell script  ")
-	cmd.Printf("curl -sSL https://raw.githubusercontent.com/%s/%s/master/install.sh | sh\n", repoOwner, repoName)
+	errutil.Printf(cmd, "curl -sSL https://raw.githubusercontent.com/%s/%s/master/install.sh | sh\n", repoOwner, repoName)
 
-	faint.Print("  arch (aur)    ")
+	errutil.Print(faint, "  arch (aur)    ")
-	cmd.Println("yay -S snitch-bin")
+	errutil.Println(cmd, "yay -S snitch-bin")
 
-	faint.Print("  nix           ")
+	errutil.Print(faint, "  nix           ")
-	cmd.Printf("nix profile upgrade --inputs-from github:%s/%s\n", repoOwner, repoName)
+	errutil.Printf(cmd, "nix profile upgrade --inputs-from github:%s/%s\n", repoOwner, repoName)
 }
 
 func performUpgrade(version string) error {
@@ -407,7 +408,7 @@ func performUpgrade(version string) error {
 
 	if strings.HasPrefix(execPath, "/nix/store/") {
 		yellow := color.New(color.FgYellow)
-		yellow.Println(tui.SymbolWarning + " cannot perform in-place upgrade for nix installation")
+		errutil.Println(yellow, tui.SymbolWarning+" cannot perform in-place upgrade for nix installation")
 		fmt.Println()
 		printNixUpgradeInstructions()
 		return nil
@@ -423,15 +424,15 @@ func performUpgrade(version string) error {
 
 	faint := color.New(color.Faint)
 	cyan := color.New(color.FgCyan)
-	faint.Print(tui.SymbolDownload + " downloading ")
+	errutil.Print(faint, tui.SymbolDownload+" downloading ")
-	cyan.Printf("%s", archiveName)
+	errutil.Printf(cyan, "%s", archiveName)
-	faint.Println("...")
+	errutil.Println(faint, "...")
 
 	resp, err := http.Get(downloadURL)
 	if err != nil {
 		return fmt.Errorf("failed to download: %w", err)
 	}
-	defer resp.Body.Close()
+	defer errutil.Close(resp.Body)
 
 	if resp.StatusCode != http.StatusOK {
 		return fmt.Errorf("download failed with status %d", resp.StatusCode)
@@ -441,7 +442,7 @@ func performUpgrade(version string) error {
 	if err != nil {
 		return fmt.Errorf("failed to create temp directory: %w", err)
 	}
-	defer os.RemoveAll(tmpDir)
+	defer errutil.RemoveAll(tmpDir)
 
 	binaryPath, err := extractBinaryFromTarGz(resp.Body, tmpDir)
 	if err != nil {
@@ -458,14 +459,14 @@ func performUpgrade(version string) error {
 		yellow := color.New(color.FgYellow)
 		cmdStyle := color.New(color.FgCyan)
 
-		yellow.Printf(tui.SymbolWarning+" elevated permissions required to install to %s\n", targetDir)
+		errutil.Printf(yellow, tui.SymbolWarning+" elevated permissions required to install to %s\n", targetDir)
 		fmt.Println()
-		faint.Println("run with sudo or install to a user-writable location:")
+		errutil.Println(faint, "run with sudo or install to a user-writable location:")
 		fmt.Println()
-		faint.Print("  sudo         ")
+		errutil.Print(faint, "  sudo         ")
-		cmdStyle.Println("sudo snitch upgrade --yes")
+		errutil.Println(cmdStyle, "sudo snitch upgrade --yes")
-		faint.Print("  custom dir   ")
+		errutil.Print(faint, "  custom dir   ")
-		cmdStyle.Printf("curl -sSL https://raw.githubusercontent.com/%s/%s/master/install.sh | INSTALL_DIR=~/.local/bin sh\n",
+		errutil.Printf(cmdStyle, "curl -sSL https://raw.githubusercontent.com/%s/%s/master/install.sh | INSTALL_DIR=~/.local/bin sh\n",
 			repoOwner, repoName)
 		return nil
 	}
@@ -491,11 +492,11 @@ func performUpgrade(version string) error {
 	if err := os.Remove(backupPath); err != nil {
 		// non-fatal, just warn
 		yellow := color.New(color.FgYellow)
-		yellow.Fprintf(os.Stderr, tui.SymbolWarning + " warning: failed to remove backup file %s: %v\n", backupPath, err)
+		errutil.Fprintf(yellow, os.Stderr, tui.SymbolWarning+" warning: failed to remove backup file %s: %v\n", backupPath, err)
 	}
 
 	green := color.New(color.FgGreen, color.Bold)
-	green.Printf(tui.SymbolSuccess + " successfully upgraded to %s\n", version)
+	errutil.Printf(green, tui.SymbolSuccess+" successfully upgraded to %s\n", version)
 	return nil
 }
 
@@ -504,7 +505,7 @@ func extractBinaryFromTarGz(r io.Reader, destDir string) (string, error) {
 	if err != nil {
 		return "", err
 	}
-	defer gzr.Close()
+	defer errutil.Close(gzr)
 
 	tr := tar.NewReader(gzr)
 
@@ -534,10 +535,10 @@ func extractBinaryFromTarGz(r io.Reader, destDir string) (string, error) {
 		}
 
 		if _, err := io.Copy(outFile, tr); err != nil {
-			outFile.Close()
+			errutil.Close(outFile)
 			return "", err
 		}
-		outFile.Close()
+		errutil.Close(outFile)
 
 		return destPath, nil
 	}
@@ -551,8 +552,8 @@ func isWritable(path string) bool {
 	if err != nil {
 		return false
 	}
-	f.Close()
+	errutil.Close(f)
-	os.Remove(testFile)
+	errutil.Remove(testFile)
 	return true
 }
 
@@ -561,13 +562,13 @@ func copyFile(src, dst string) error {
 	if err != nil {
 		return err
 	}
-	defer srcFile.Close()
+	defer errutil.Close(srcFile)
 
 	dstFile, err := os.Create(dst)
 	if err != nil {
 		return err
 	}
-	defer dstFile.Close()
+	defer errutil.Close(dstFile)
 
 	if _, err := io.Copy(dstFile, srcFile); err != nil {
 		return err
@@ -580,7 +581,7 @@ func removeQuarantine(path string) {
 	cmd := exec.Command("xattr", "-d", "com.apple.quarantine", path)
 	if err := cmd.Run(); err == nil {
 		faint := color.New(color.Faint)
-		faint.Println("  removed macOS quarantine attribute")
+		errutil.Println(faint, "  removed macOS quarantine attribute")
 	}
 }
 
@@ -633,7 +634,7 @@ func fetchCommitForTag(tag string) (string, error) {
 	if err != nil {
 		return "", err
 	}
-	defer resp.Body.Close()
+	defer errutil.Close(resp.Body)
 
 	if resp.StatusCode != http.StatusOK {
 		return "", fmt.Errorf("github api returned status %d", resp.StatusCode)
@@ -654,7 +655,7 @@ func compareCommits(base, head string) (*githubCompare, error) {
 	if err != nil {
 		return nil, err
 	}
-	defer resp.Body.Close()
+	defer errutil.Close(resp.Body)
 
 	if resp.StatusCode != http.StatusOK {
 		return nil, fmt.Errorf("github api returned status %d", resp.StatusCode)
@@ -673,16 +674,16 @@ func printNixUpgradeInstructions() {
 	faint := color.New(color.Faint)
 	cmd := color.New(color.FgCyan)
 
-	bold.Println("nix upgrade options:")
+	errutil.Println(bold, "nix upgrade options:")
 	fmt.Println()
 
-	faint.Print("  flake profile   ")
+	errutil.Print(faint, "  flake profile   ")
-	cmd.Printf("nix profile install github:%s/%s\n", repoOwner, repoName)
+	errutil.Printf(cmd, "nix profile install github:%s/%s\n", repoOwner, repoName)
 
-	faint.Print("  flake update    ")
+	errutil.Print(faint, "  flake update    ")
-	cmd.Println("nix flake update snitch  (in your system/home-manager config)")
+	errutil.Println(cmd, "nix flake update snitch  (in your system/home-manager config)")
 
-	faint.Print("  rebuild         ")
+	errutil.Print(faint, "  rebuild         ")
-	cmd.Println("nixos-rebuild switch  or  home-manager switch")
+	errutil.Println(cmd, "nixos-rebuild switch  or  home-manager switch")
 }
 

cmd/version.go

@@ -6,6 +6,8 @@ import (
 
 	"github.com/fatih/color"
 	"github.com/spf13/cobra"
+
+	"github.com/karol-broda/snitch/internal/errutil"
 )
 
 var (
@@ -22,20 +24,20 @@ var versionCmd = &cobra.Command{
 		cyan := color.New(color.FgCyan)
 		faint := color.New(color.Faint)
 
-		bold.Print("snitch ")
+		errutil.Print(bold, "snitch ")
-		cyan.Println(Version)
+		errutil.Println(cyan, Version)
 		fmt.Println()
 
-		faint.Print("  commit  ")
+		errutil.Print(faint, "  commit  ")
 		fmt.Println(Commit)
 
-		faint.Print("  built   ")
+		errutil.Print(faint, "  built   ")
 		fmt.Println(Date)
 
-		faint.Print("  go      ")
+		errutil.Print(faint, "  go      ")
 		fmt.Println(runtime.Version())
 
-		faint.Print("  os      ")
+		errutil.Print(faint, "  os      ")
 		fmt.Printf("%s/%s\n", runtime.GOOS, runtime.GOARCH)
 	},
 }

flake.nix

@@ -106,5 +106,32 @@
       overlays.default = final: _prev: {
         snitch = mkSnitch final;
       };
+
+      homeManagerModules.default = import ./nix/hm-module.nix;
+      homeManagerModules.snitch = self.homeManagerModules.default;
+
+      # alias for flake-parts compatibility
+      homeModules.default = self.homeManagerModules.default;
+      homeModules.snitch = self.homeManagerModules.default;
+
+      checks = eachSystem (system:
+        let
+          pkgs = import nixpkgs {
+            inherit system;
+            overlays = [ self.overlays.default ];
+          };
+        in
+        {
+          # home manager module tests
+          hm-module = import ./nix/tests/hm-module-test.nix {
+            inherit pkgs;
+            lib = pkgs.lib;
+            hmModule = self.homeManagerModules.default;
+          };
+
+          # package builds correctly
+          package = self.packages.${system}.default;
+        }
+      );
     };
 }

internal/collector/collector_linux.go

@@ -14,6 +14,8 @@ import (
 	"sync"
 	"sync/atomic"
 	"time"
+
+	"github.com/karol-broda/snitch/internal/errutil"
 )
 
 // set SNITCH_DEBUG_TIMING=1 to enable timing diagnostics
@@ -138,7 +140,7 @@ func buildInodeToProcessMap() (map[int64]*processInfo, error) {
 	if err != nil {
 		return nil, err
 	}
-	defer procDir.Close()
+	defer errutil.Close(procDir)
 
 	entries, err := procDir.Readdir(-1)
 	if err != nil {
@@ -278,7 +280,7 @@ func getProcessInfo(pid int) (*processInfo, error) {
 	if err != nil {
 		return info, nil
 	}
-	defer statusFile.Close()
+	defer errutil.Close(statusFile)
 
 	scanner := bufio.NewScanner(statusFile)
 	for scanner.Scan() {
@@ -304,7 +306,7 @@ func parseProcNet(path, proto string, ipVersion int, inodeMap map[int64]*process
 	if err != nil {
 		return nil, err
 	}
-	defer file.Close()
+	defer errutil.Close(file)
 
 	var connections []Connection
 	scanner := bufio.NewScanner(file)
@@ -473,7 +475,7 @@ func GetUnixSockets() ([]Connection, error) {
 	if err != nil {
 		return connections, nil
 	}
-	defer file.Close()
+	defer errutil.Close(file)
 
 	scanner := bufio.NewScanner(file)
 	scanner.Scan()

internal/color/color_test.go

@@ -5,6 +5,8 @@ import (
 	"testing"
 
 	"github.com/fatih/color"
+
+	"github.com/karol-broda/snitch/internal/errutil"
 )
 
 func TestInit(t *testing.T) {
@@ -29,8 +31,8 @@ func TestInit(t *testing.T) {
 			origTerm := os.Getenv("TERM")
 
 			// Set test env vars
-			os.Setenv("NO_COLOR", tc.noColor)
+			errutil.Setenv("NO_COLOR", tc.noColor)
-			os.Setenv("TERM", tc.term)
+			errutil.Setenv("TERM", tc.term)
 
 			Init(tc.mode)
 
@@ -39,8 +41,8 @@ func TestInit(t *testing.T) {
 			}
 
 			// Restore original env vars
-			os.Setenv("NO_COLOR", origNoColor)
+			errutil.Setenv("NO_COLOR", origNoColor)
-			os.Setenv("TERM", origTerm)
+			errutil.Setenv("TERM", origTerm)
 		})
 	}
 }

internal/config/config.go

@@ -14,6 +14,12 @@ import (
 // Config represents the application configuration
 type Config struct {
 	Defaults DefaultConfig `mapstructure:"defaults"`
+	TUI      TUIConfig     `mapstructure:"tui"`
+}
+
+// TUIConfig contains TUI-specific configuration
+type TUIConfig struct {
+	RememberState bool `mapstructure:"remember_state"`
 }
 
 // DefaultConfig contains default values for CLI options
@@ -105,6 +111,9 @@ func setDefaults(v *viper.Viper) {
 	v.SetDefault("defaults.no_headers", false)
 	v.SetDefault("defaults.output_format", "table")
 	v.SetDefault("defaults.sort_by", "")
+
+	// tui settings
+	v.SetDefault("tui.remember_state", false)
 }
 
 func handleSpecialEnvVars(v *viper.Viper) {
@@ -146,6 +155,9 @@ func Get() *Config {
 					OutputFormat: "table",
 					SortBy:       "",
 				},
+				TUI: TUIConfig{
+					RememberState: false,
+				},
 			}
 		}
 		return config
@@ -199,6 +211,11 @@ ipv6 = false
 no_headers = false
 output_format = "table"
 sort_by = ""
+
+[tui]
+# remember view options (filters, sort, resolution) between sessions
+# state is saved to $XDG_STATE_HOME/snitch/tui.json
+remember_state = false
 `, themeList, theme.DefaultTheme)
 
 	// Ensure directory exists

internal/errutil/errutil.go

@@ -0,0 +1,65 @@
+package errutil
+
+import (
+	"io"
+	"os"
+
+	"github.com/fatih/color"
+)
+
+func Ignore[T any](val T, _ error) T {
+	return val
+}
+
+func IgnoreErr(_ error) {}
+
+func Close(c io.Closer) {
+	if c != nil {
+		_ = c.Close()
+	}
+}
+
+// color.Color wrappers - these discard the (int, error) return values
+
+func Print(c *color.Color, a ...any) {
+	_, _ = c.Print(a...)
+}
+
+func Println(c *color.Color, a ...any) {
+	_, _ = c.Println(a...)
+}
+
+func Printf(c *color.Color, format string, a ...any) {
+	_, _ = c.Printf(format, a...)
+}
+
+func Fprintf(c *color.Color, w io.Writer, format string, a ...any) {
+	_, _ = c.Fprintf(w, format, a...)
+}
+
+// os function wrappers for test cleanup where errors are non-critical
+
+func Setenv(key, value string) {
+	_ = os.Setenv(key, value)
+}
+
+func Unsetenv(key string) {
+	_ = os.Unsetenv(key)
+}
+
+func Remove(name string) {
+	_ = os.Remove(name)
+}
+
+func RemoveAll(path string) {
+	_ = os.RemoveAll(path)
+}
+
+// Flush calls Flush on a tabwriter and discards the error
+type Flusher interface {
+	Flush() error
+}
+
+func Flush(f Flusher) {
+	_ = f.Flush()
+}

internal/state/state.go

@@ -0,0 +1,133 @@
+package state
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"sync"
+
+	"github.com/karol-broda/snitch/internal/collector"
+)
+
+// TUIState holds view options that can be persisted between sessions
+type TUIState struct {
+	ShowTCP         bool                `json:"show_tcp"`
+	ShowUDP         bool                `json:"show_udp"`
+	ShowListening   bool                `json:"show_listening"`
+	ShowEstablished bool                `json:"show_established"`
+	ShowOther       bool                `json:"show_other"`
+	SortField       collector.SortField `json:"sort_field"`
+	SortReverse     bool                `json:"sort_reverse"`
+	ResolveAddrs    bool                `json:"resolve_addrs"`
+	ResolvePorts    bool                `json:"resolve_ports"`
+}
+
+var (
+	saveMu   sync.Mutex
+	saveChan chan TUIState
+	once     sync.Once
+)
+
+// Path returns the XDG-compliant state file path
+func Path() string {
+	stateDir := os.Getenv("XDG_STATE_HOME")
+	if stateDir == "" {
+		home, err := os.UserHomeDir()
+		if err != nil {
+			return ""
+		}
+		stateDir = filepath.Join(home, ".local", "state")
+	}
+	return filepath.Join(stateDir, "snitch", "tui.json")
+}
+
+// Load reads the TUI state from disk.
+// returns nil if state file doesn't exist or can't be read.
+func Load() *TUIState {
+	path := Path()
+	if path == "" {
+		return nil
+	}
+
+	data, err := os.ReadFile(path)
+	if err != nil {
+		return nil
+	}
+
+	var state TUIState
+	if err := json.Unmarshal(data, &state); err != nil {
+		return nil
+	}
+
+	return &state
+}
+
+// Save writes the TUI state to disk synchronously.
+// creates parent directories if needed.
+func Save(state TUIState) error {
+	path := Path()
+	if path == "" {
+		return nil
+	}
+
+	saveMu.Lock()
+	defer saveMu.Unlock()
+
+	dir := filepath.Dir(path)
+	if err := os.MkdirAll(dir, 0755); err != nil {
+		return err
+	}
+
+	data, err := json.MarshalIndent(state, "", "  ")
+	if err != nil {
+		return err
+	}
+
+	return os.WriteFile(path, data, 0644)
+}
+
+// SaveAsync queues a state save to happen in the background.
+// only the most recent state is saved if multiple saves are queued.
+func SaveAsync(state TUIState) {
+	once.Do(func() {
+		saveChan = make(chan TUIState, 1)
+		go saveWorker()
+	})
+
+	// non-blocking send, replace pending save with newer state
+	select {
+	case saveChan <- state:
+	default:
+		// channel full, drain and replace
+		select {
+		case <-saveChan:
+		default:
+		}
+		select {
+		case saveChan <- state:
+		default:
+		}
+	}
+}
+
+func saveWorker() {
+	for state := range saveChan {
+		_ = Save(state)
+	}
+}
+
+// Default returns a TUIState with default values
+func Default() TUIState {
+	return TUIState{
+		ShowTCP:         true,
+		ShowUDP:         true,
+		ShowListening:   true,
+		ShowEstablished: true,
+		ShowOther:       true,
+		SortField:       collector.SortByLport,
+		SortReverse:     false,
+		ResolveAddrs:    false,
+		ResolvePorts:    false,
+	}
+}
+

internal/state/state_test.go

@@ -0,0 +1,236 @@
+package state
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"github.com/karol-broda/snitch/internal/collector"
+)
+
+func TestPath_XDGStateHome(t *testing.T) {
+	t.Setenv("XDG_STATE_HOME", "/custom/state")
+	path := Path()
+
+	expected := "/custom/state/snitch/tui.json"
+	if path != expected {
+		t.Errorf("Path() = %q, want %q", path, expected)
+	}
+}
+
+func TestPath_DefaultFallback(t *testing.T) {
+	t.Setenv("XDG_STATE_HOME", "")
+	path := Path()
+
+	home, err := os.UserHomeDir()
+	if err != nil {
+		t.Skip("cannot determine home directory")
+	}
+
+	expected := filepath.Join(home, ".local", "state", "snitch", "tui.json")
+	if path != expected {
+		t.Errorf("Path() = %q, want %q", path, expected)
+	}
+}
+
+func TestDefault(t *testing.T) {
+	d := Default()
+
+	if d.ShowTCP != true {
+		t.Error("expected ShowTCP to be true")
+	}
+	if d.ShowUDP != true {
+		t.Error("expected ShowUDP to be true")
+	}
+	if d.ShowListening != true {
+		t.Error("expected ShowListening to be true")
+	}
+	if d.ShowEstablished != true {
+		t.Error("expected ShowEstablished to be true")
+	}
+	if d.ShowOther != true {
+		t.Error("expected ShowOther to be true")
+	}
+	if d.SortField != collector.SortByLport {
+		t.Errorf("expected SortField to be %q, got %q", collector.SortByLport, d.SortField)
+	}
+	if d.SortReverse != false {
+		t.Error("expected SortReverse to be false")
+	}
+	if d.ResolveAddrs != false {
+		t.Error("expected ResolveAddrs to be false")
+	}
+	if d.ResolvePorts != false {
+		t.Error("expected ResolvePorts to be false")
+	}
+}
+
+func TestSaveAndLoad(t *testing.T) {
+	tmpDir := t.TempDir()
+	t.Setenv("XDG_STATE_HOME", tmpDir)
+
+	state := TUIState{
+		ShowTCP:         false,
+		ShowUDP:         true,
+		ShowListening:   true,
+		ShowEstablished: false,
+		ShowOther:       true,
+		SortField:       collector.SortByProcess,
+		SortReverse:     true,
+		ResolveAddrs:    true,
+		ResolvePorts:    false,
+	}
+
+	err := Save(state)
+	if err != nil {
+		t.Fatalf("Save() error = %v", err)
+	}
+
+	// verify file was created
+	path := Path()
+	if _, err := os.Stat(path); os.IsNotExist(err) {
+		t.Fatal("expected state file to exist after Save()")
+	}
+
+	loaded := Load()
+	if loaded == nil {
+		t.Fatal("Load() returned nil")
+	}
+
+	if loaded.ShowTCP != state.ShowTCP {
+		t.Errorf("ShowTCP = %v, want %v", loaded.ShowTCP, state.ShowTCP)
+	}
+	if loaded.ShowUDP != state.ShowUDP {
+		t.Errorf("ShowUDP = %v, want %v", loaded.ShowUDP, state.ShowUDP)
+	}
+	if loaded.ShowListening != state.ShowListening {
+		t.Errorf("ShowListening = %v, want %v", loaded.ShowListening, state.ShowListening)
+	}
+	if loaded.ShowEstablished != state.ShowEstablished {
+		t.Errorf("ShowEstablished = %v, want %v", loaded.ShowEstablished, state.ShowEstablished)
+	}
+	if loaded.ShowOther != state.ShowOther {
+		t.Errorf("ShowOther = %v, want %v", loaded.ShowOther, state.ShowOther)
+	}
+	if loaded.SortField != state.SortField {
+		t.Errorf("SortField = %v, want %v", loaded.SortField, state.SortField)
+	}
+	if loaded.SortReverse != state.SortReverse {
+		t.Errorf("SortReverse = %v, want %v", loaded.SortReverse, state.SortReverse)
+	}
+	if loaded.ResolveAddrs != state.ResolveAddrs {
+		t.Errorf("ResolveAddrs = %v, want %v", loaded.ResolveAddrs, state.ResolveAddrs)
+	}
+	if loaded.ResolvePorts != state.ResolvePorts {
+		t.Errorf("ResolvePorts = %v, want %v", loaded.ResolvePorts, state.ResolvePorts)
+	}
+}
+
+func TestLoad_NonExistent(t *testing.T) {
+	tmpDir := t.TempDir()
+	t.Setenv("XDG_STATE_HOME", tmpDir)
+
+	loaded := Load()
+	if loaded != nil {
+		t.Error("expected Load() to return nil for non-existent file")
+	}
+}
+
+func TestLoad_InvalidJSON(t *testing.T) {
+	tmpDir := t.TempDir()
+	t.Setenv("XDG_STATE_HOME", tmpDir)
+
+	// create directory and invalid json file
+	stateDir := filepath.Join(tmpDir, "snitch")
+	if err := os.MkdirAll(stateDir, 0755); err != nil {
+		t.Fatal(err)
+	}
+	stateFile := filepath.Join(stateDir, "tui.json")
+	if err := os.WriteFile(stateFile, []byte("not valid json"), 0644); err != nil {
+		t.Fatal(err)
+	}
+
+	loaded := Load()
+	if loaded != nil {
+		t.Error("expected Load() to return nil for invalid JSON")
+	}
+}
+
+func TestSave_CreatesDirectories(t *testing.T) {
+	tmpDir := t.TempDir()
+	t.Setenv("XDG_STATE_HOME", tmpDir)
+
+	// snitch directory should not exist yet
+	snitchDir := filepath.Join(tmpDir, "snitch")
+	if _, err := os.Stat(snitchDir); err == nil {
+		t.Fatal("expected snitch directory to not exist initially")
+	}
+
+	err := Save(Default())
+	if err != nil {
+		t.Fatalf("Save() error = %v", err)
+	}
+
+	// directory should now exist
+	if _, err := os.Stat(snitchDir); os.IsNotExist(err) {
+		t.Error("expected Save() to create parent directories")
+	}
+}
+
+func TestSaveAsync(t *testing.T) {
+	tmpDir := t.TempDir()
+	t.Setenv("XDG_STATE_HOME", tmpDir)
+
+	state := TUIState{
+		ShowTCP:   false,
+		SortField: collector.SortByPID,
+	}
+
+	SaveAsync(state)
+
+	// wait for background save with timeout
+	deadline := time.Now().Add(100 * time.Millisecond)
+	for time.Now().Before(deadline) {
+		if loaded := Load(); loaded != nil {
+			return
+		}
+		time.Sleep(5 * time.Millisecond)
+	}
+
+	t.Log("SaveAsync may not have completed in time (non-fatal in CI)")
+}
+
+func TestTUIState_JSONRoundtrip(t *testing.T) {
+	// verify all sort fields serialize correctly
+	sortFields := []collector.SortField{
+		collector.SortByLport,
+		collector.SortByProcess,
+		collector.SortByPID,
+		collector.SortByState,
+		collector.SortByProto,
+	}
+
+	tmpDir := t.TempDir()
+	t.Setenv("XDG_STATE_HOME", tmpDir)
+
+	for _, sf := range sortFields {
+		state := TUIState{
+			ShowTCP:   true,
+			SortField: sf,
+		}
+
+		if err := Save(state); err != nil {
+			t.Fatalf("Save() error for %q: %v", sf, err)
+		}
+
+		loaded := Load()
+		if loaded == nil {
+			t.Fatalf("Load() returned nil for %q", sf)
+		}
+
+		if loaded.SortField != sf {
+			t.Errorf("SortField roundtrip failed: got %q, want %q", loaded.SortField, sf)
+		}
+	}
+}

internal/testutil/testutil.go

@@ -6,6 +6,7 @@ import (
 	"testing"
 
 	"github.com/karol-broda/snitch/internal/collector"
+	"github.com/karol-broda/snitch/internal/errutil"
 )
 
 // TestCollector wraps MockCollector for use in tests
@@ -47,13 +48,13 @@ func SetupTestEnvironment(t *testing.T) (string, func()) {
 	oldConfig := os.Getenv("SNITCH_CONFIG")
 	oldNoColor := os.Getenv("SNITCH_NO_COLOR")
 	
-	os.Setenv("SNITCH_NO_COLOR", "1") // Disable colors in tests
+	errutil.Setenv("SNITCH_NO_COLOR", "1")
 	
 	// Cleanup function
 	cleanup := func() {
-		os.RemoveAll(tempDir)
+		errutil.RemoveAll(tempDir)
-		os.Setenv("SNITCH_CONFIG", oldConfig)
+		errutil.Setenv("SNITCH_CONFIG", oldConfig)
-		os.Setenv("SNITCH_NO_COLOR", oldNoColor)
+		errutil.Setenv("SNITCH_NO_COLOR", oldNoColor)
 	}
 	
 	return tempDir, cleanup
@@ -192,8 +193,8 @@ func (oc *OutputCapture) Stop() (string, string, error) {
 	os.Stderr = oc.oldStderr
 	
 	// Close files
-	oc.stdout.Close()
+	errutil.Close(oc.stdout)
-	oc.stderr.Close()
+	errutil.Close(oc.stderr)
 	
 	// Read captured content
 	stdoutContent, err := os.ReadFile(oc.stdoutFile)
@@ -207,9 +208,9 @@ func (oc *OutputCapture) Stop() (string, string, error) {
 	}
 	
 	// Cleanup
-	os.Remove(oc.stdoutFile)
+	errutil.Remove(oc.stdoutFile)
-	os.Remove(oc.stderrFile)
+	errutil.Remove(oc.stderrFile)
-	os.Remove(filepath.Dir(oc.stdoutFile))
+	errutil.Remove(filepath.Dir(oc.stdoutFile))
 	
 	return string(stdoutContent), string(stderrContent), nil
 }

internal/tui/keys.go

@@ -118,31 +118,39 @@ func (m model) handleNormalKey(msg tea.KeyMsg) (tea.Model, tea.Cmd) {
 	case "t":
 		m.showTCP = !m.showTCP
 		m.clampCursor()
+		m.saveState()
 	case "u":
 		m.showUDP = !m.showUDP
 		m.clampCursor()
+		m.saveState()
 	case "l":
 		m.showListening = !m.showListening
 		m.clampCursor()
+		m.saveState()
 	case "e":
 		m.showEstablished = !m.showEstablished
 		m.clampCursor()
+		m.saveState()
 	case "o":
 		m.showOther = !m.showOther
 		m.clampCursor()
+		m.saveState()
 	case "a":
 		m.showTCP = true
 		m.showUDP = true
 		m.showListening = true
 		m.showEstablished = true
 		m.showOther = true
+		m.saveState()
 
 	// sorting
 	case "s":
 		m.cycleSort()
+		m.saveState()
 	case "S":
 		m.sortReverse = !m.sortReverse
 		m.applySorting()
+		m.saveState()
 
 	// search
 	case "/":
@@ -220,6 +228,7 @@ func (m model) handleNormalKey(msg tea.KeyMsg) (tea.Model, tea.Cmd) {
 			m.statusMessage = "address resolution: off"
 		}
 		m.statusExpiry = time.Now().Add(2 * time.Second)
+		m.saveState()
 		return m, clearStatusAfter(2 * time.Second)
 
 	// toggle port resolution
@@ -231,6 +240,7 @@ func (m model) handleNormalKey(msg tea.KeyMsg) (tea.Model, tea.Cmd) {
 			m.statusMessage = "port resolution: off"
 		}
 		m.statusExpiry = time.Now().Add(2 * time.Second)
+		m.saveState()
 		return m, clearStatusAfter(2 * time.Second)
 	}
 

internal/tui/model.go

@@ -2,11 +2,13 @@ package tui
 
 import (
 	"fmt"
-	"github.com/karol-broda/snitch/internal/collector"
-	"github.com/karol-broda/snitch/internal/theme"
 	"time"
 
 	tea "github.com/charmbracelet/bubbletea"
+
+	"github.com/karol-broda/snitch/internal/collector"
+	"github.com/karol-broda/snitch/internal/state"
+	"github.com/karol-broda/snitch/internal/theme"
 )
 
 type model struct {
@@ -51,6 +53,9 @@ type model struct {
 	// status message (temporary feedback)
 	statusMessage string
 	statusExpiry  time.Time
+
+	// state persistence
+	rememberState bool
 }
 
 type Options struct {
@@ -65,6 +70,7 @@ type Options struct {
 	ResolveAddrs  bool // when true, resolve IP addresses to hostnames
 	ResolvePorts  bool // when true, resolve port numbers to service names
 	NoCache       bool // when true, disable DNS caching
+	RememberState bool // when true, persist view options between sessions
 }
 
 func New(opts Options) model {
@@ -79,8 +85,27 @@ func New(opts Options) model {
 	showListening := true
 	showEstablished := true
 	showOther := true
+	sortField := collector.SortByLport
+	sortReverse := false
+	resolveAddrs := opts.ResolveAddrs
+	resolvePorts := opts.ResolvePorts
 
-	// if user specified filters, use those instead
+	// load saved state if enabled and no CLI filter flags were specified
+	if opts.RememberState && !opts.FilterSet {
+		if saved := state.Load(); saved != nil {
+			showTCP = saved.ShowTCP
+			showUDP = saved.ShowUDP
+			showListening = saved.ShowListening
+			showEstablished = saved.ShowEstablished
+			showOther = saved.ShowOther
+			sortField = saved.SortField
+			sortReverse = saved.SortReverse
+			resolveAddrs = saved.ResolveAddrs
+			resolvePorts = saved.ResolvePorts
+		}
+	}
+
+	// if user specified filters, use those instead (CLI flags take precedence)
 	if opts.FilterSet {
 		showTCP = opts.TCP
 		showUDP = opts.UDP
@@ -108,13 +133,15 @@ func New(opts Options) model {
 		showListening:   showListening,
 		showEstablished: showEstablished,
 		showOther:       showOther,
-		sortField:       collector.SortByLport,
+		sortField:       sortField,
-		resolveAddrs:    opts.ResolveAddrs,
+		sortReverse:     sortReverse,
-		resolvePorts:    opts.ResolvePorts,
+		resolveAddrs:    resolveAddrs,
+		resolvePorts:    resolvePorts,
 		theme:           theme.GetTheme(opts.Theme),
 		interval:        interval,
 		lastRefresh:     time.Now(),
 		watchedPIDs:     make(map[int]bool),
+		rememberState:   opts.RememberState,
 	}
 }
 
@@ -291,3 +318,25 @@ func (m *model) toggleWatch(pid int) {
 func (m model) watchedCount() int {
 	return len(m.watchedPIDs)
 }
+
+// currentState returns the current view options as a TUIState for persistence
+func (m model) currentState() state.TUIState {
+	return state.TUIState{
+		ShowTCP:         m.showTCP,
+		ShowUDP:         m.showUDP,
+		ShowListening:   m.showListening,
+		ShowEstablished: m.showEstablished,
+		ShowOther:       m.showOther,
+		SortField:       m.sortField,
+		SortReverse:     m.sortReverse,
+		ResolveAddrs:    m.resolveAddrs,
+		ResolvePorts:    m.resolvePorts,
+	}
+}
+
+// saveState persists current view options in the background
+func (m model) saveState() {
+	if m.rememberState {
+		state.SaveAsync(m.currentState())
+	}
+}

nix/hm-module.nix

@@ -0,0 +1,177 @@
+{
+  config,
+  lib,
+  pkgs,
+  ...
+}:
+let
+  cfg = config.programs.snitch;
+
+  themes = [
+    "ansi"
+    "catppuccin-mocha"
+    "catppuccin-macchiato"
+    "catppuccin-frappe"
+    "catppuccin-latte"
+    "gruvbox-dark"
+    "gruvbox-light"
+    "dracula"
+    "nord"
+    "tokyo-night"
+    "tokyo-night-storm"
+    "tokyo-night-light"
+    "solarized-dark"
+    "solarized-light"
+    "one-dark"
+    "mono"
+    "auto"
+  ];
+
+  defaultFields = [
+    "pid"
+    "process"
+    "user"
+    "proto"
+    "state"
+    "laddr"
+    "lport"
+    "raddr"
+    "rport"
+  ];
+
+  tomlFormat = pkgs.formats.toml { };
+
+  settingsType = lib.types.submodule {
+    freeformType = tomlFormat.type;
+
+    options = {
+      defaults = lib.mkOption {
+        type = lib.types.submodule {
+          freeformType = tomlFormat.type;
+
+          options = {
+            interval = lib.mkOption {
+              type = lib.types.str;
+              default = "1s";
+              example = "2s";
+              description = "Default refresh interval for watch/stats/trace commands.";
+            };
+
+            numeric = lib.mkOption {
+              type = lib.types.bool;
+              default = false;
+              description = "Disable name/service resolution by default.";
+            };
+
+            fields = lib.mkOption {
+              type = lib.types.listOf lib.types.str;
+              default = defaultFields;
+              example = [ "pid" "process" "proto" "state" "laddr" "lport" ];
+              description = "Default fields to display.";
+            };
+
+            theme = lib.mkOption {
+              type = lib.types.enum themes;
+              default = "ansi";
+              description = ''
+                Color theme for the TUI. "ansi" inherits terminal colors.
+              '';
+            };
+
+            units = lib.mkOption {
+              type = lib.types.enum [ "auto" "si" "iec" ];
+              default = "auto";
+              description = "Default units for byte display.";
+            };
+
+            color = lib.mkOption {
+              type = lib.types.enum [ "auto" "always" "never" ];
+              default = "auto";
+              description = "Default color mode.";
+            };
+
+            resolve = lib.mkOption {
+              type = lib.types.bool;
+              default = true;
+              description = "Enable name resolution by default.";
+            };
+
+            dns_cache = lib.mkOption {
+              type = lib.types.bool;
+              default = true;
+              description = "Enable DNS caching.";
+            };
+
+            ipv4 = lib.mkOption {
+              type = lib.types.bool;
+              default = false;
+              description = "Filter to IPv4 only by default.";
+            };
+
+            ipv6 = lib.mkOption {
+              type = lib.types.bool;
+              default = false;
+              description = "Filter to IPv6 only by default.";
+            };
+
+            no_headers = lib.mkOption {
+              type = lib.types.bool;
+              default = false;
+              description = "Omit headers in output by default.";
+            };
+
+            output_format = lib.mkOption {
+              type = lib.types.enum [ "table" "json" "csv" ];
+              default = "table";
+              description = "Default output format.";
+            };
+
+            sort_by = lib.mkOption {
+              type = lib.types.str;
+              default = "";
+              example = "pid";
+              description = "Default sort field.";
+            };
+          };
+        };
+        default = { };
+        description = "Default settings for snitch commands.";
+      };
+    };
+  };
+in
+{
+  options.programs.snitch = {
+    enable = lib.mkEnableOption "snitch, a friendlier ss/netstat for humans";
+
+    package = lib.mkPackageOption pkgs "snitch" { };
+
+    settings = lib.mkOption {
+      type = settingsType;
+      default = { };
+      example = lib.literalExpression ''
+        {
+          defaults = {
+            theme = "catppuccin-mocha";
+            interval = "2s";
+            resolve = true;
+          };
+        }
+      '';
+      description = ''
+        Configuration written to {file}`$XDG_CONFIG_HOME/snitch/snitch.toml`.
+
+        See <https://github.com/karol-broda/snitch> for available options.
+      '';
+    };
+  };
+
+  config = lib.mkIf cfg.enable {
+    home.packages = [ cfg.package ];
+
+    xdg.configFile."snitch/snitch.toml" = lib.mkIf (cfg.settings != { }) {
+      source = tomlFormat.generate "snitch.toml" cfg.settings;
+    };
+  };
+}
+

nix/tests/hm-module-test.nix

@@ -0,0 +1,429 @@
+# home manager module tests
+#
+# run with: nix build .#checks.x86_64-linux.hm-module
+#
+# tests cover:
+# - module evaluation with various configurations
+# - type validation for all options
+# - generated TOML content verification
+# - edge cases (disabled, empty settings, full settings)
+{ pkgs, lib, hmModule }:
+
+let
+  # minimal home-manager stub for standalone module testing
+  hmLib = {
+    hm.types.dagOf = lib.types.attrsOf;
+    dag.entryAnywhere = x: x;
+  };
+
+  # evaluate the hm module with a given config
+  evalModule = testConfig:
+    lib.evalModules {
+      modules = [
+        hmModule
+        # stub home-manager's expected structure
+        {
+          options = {
+            home.packages = lib.mkOption {
+              type = lib.types.listOf lib.types.package;
+              default = [ ];
+            };
+            xdg.configFile = lib.mkOption {
+              type = lib.types.attrsOf (lib.types.submodule {
+                options = {
+                  source = lib.mkOption { type = lib.types.path; };
+                  text = lib.mkOption { type = lib.types.str; default = ""; };
+                };
+              });
+              default = { };
+            };
+          };
+        }
+        testConfig
+      ];
+      specialArgs = { inherit pkgs lib; };
+    };
+
+  # read generated TOML file content
+  readGeneratedToml = evalResult:
+    let
+      configFile = evalResult.config.xdg.configFile."snitch/snitch.toml" or null;
+    in
+    if configFile != null && configFile ? source
+    then builtins.readFile configFile.source
+    else null;
+
+  # test cases
+  tests = {
+    # test 1: module evaluates when disabled
+    moduleDisabled = {
+      name = "module-disabled";
+      config = {
+        programs.snitch.enable = false;
+      };
+      assertions = evalResult: [
+        {
+          assertion = evalResult.config.home.packages == [ ];
+          message = "packages should be empty when disabled";
+        }
+        {
+          assertion = !(evalResult.config.xdg.configFile ? "snitch/snitch.toml");
+          message = "config file should not exist when disabled";
+        }
+      ];
+    };
+
+    # test 2: module evaluates with enable only (defaults)
+    moduleEnabledDefaults = {
+      name = "module-enabled-defaults";
+      config = {
+        programs.snitch.enable = true;
+      };
+      assertions = evalResult: [
+        {
+          assertion = builtins.length evalResult.config.home.packages == 1;
+          message = "package should be installed when enabled";
+        }
+      ];
+    };
+
+    # test 3: all theme values are valid
+    themeValidation = {
+      name = "theme-validation";
+      config = {
+        programs.snitch = {
+          enable = true;
+          settings.defaults.theme = "catppuccin-mocha";
+        };
+      };
+      assertions = evalResult:
+        let
+          toml = readGeneratedToml evalResult;
+        in
+        [
+          {
+            assertion = toml != null;
+            message = "TOML config should be generated";
+          }
+          {
+            assertion = lib.hasInfix "catppuccin-mocha" toml;
+            message = "theme should be set in TOML";
+          }
+        ];
+    };
+
+    # test 4: full configuration with all options
+    fullConfiguration = {
+      name = "full-configuration";
+      config = {
+        programs.snitch = {
+          enable = true;
+          settings.defaults = {
+            interval = "2s";
+            numeric = true;
+            fields = [ "pid" "process" "proto" ];
+            theme = "nord";
+            units = "si";
+            color = "always";
+            resolve = false;
+            dns_cache = false;
+            ipv4 = true;
+            ipv6 = false;
+            no_headers = true;
+            output_format = "json";
+            sort_by = "pid";
+          };
+        };
+      };
+      assertions = evalResult:
+        let
+          toml = readGeneratedToml evalResult;
+        in
+        [
+          {
+            assertion = toml != null;
+            message = "TOML config should be generated";
+          }
+          {
+            assertion = lib.hasInfix "interval = \"2s\"" toml;
+            message = "interval should be 2s";
+          }
+          {
+            assertion = lib.hasInfix "numeric = true" toml;
+            message = "numeric should be true";
+          }
+          {
+            assertion = lib.hasInfix "theme = \"nord\"" toml;
+            message = "theme should be nord";
+          }
+          {
+            assertion = lib.hasInfix "units = \"si\"" toml;
+            message = "units should be si";
+          }
+          {
+            assertion = lib.hasInfix "color = \"always\"" toml;
+            message = "color should be always";
+          }
+          {
+            assertion = lib.hasInfix "resolve = false" toml;
+            message = "resolve should be false";
+          }
+          {
+            assertion = lib.hasInfix "output_format = \"json\"" toml;
+            message = "output_format should be json";
+          }
+          {
+            assertion = lib.hasInfix "sort_by = \"pid\"" toml;
+            message = "sort_by should be pid";
+          }
+        ];
+    };
+
+    # test 5: output format enum validation
+    outputFormatCsv = {
+      name = "output-format-csv";
+      config = {
+        programs.snitch = {
+          enable = true;
+          settings.defaults.output_format = "csv";
+        };
+      };
+      assertions = evalResult:
+        let
+          toml = readGeneratedToml evalResult;
+        in
+        [
+          {
+            assertion = lib.hasInfix "output_format = \"csv\"" toml;
+            message = "output_format should accept csv";
+          }
+        ];
+    };
+
+    # test 6: units enum validation
+    unitsIec = {
+      name = "units-iec";
+      config = {
+        programs.snitch = {
+          enable = true;
+          settings.defaults.units = "iec";
+        };
+      };
+      assertions = evalResult:
+        let
+          toml = readGeneratedToml evalResult;
+        in
+        [
+          {
+            assertion = lib.hasInfix "units = \"iec\"" toml;
+            message = "units should accept iec";
+          }
+        ];
+    };
+
+    # test 7: color never value
+    colorNever = {
+      name = "color-never";
+      config = {
+        programs.snitch = {
+          enable = true;
+          settings.defaults.color = "never";
+        };
+      };
+      assertions = evalResult:
+        let
+          toml = readGeneratedToml evalResult;
+        in
+        [
+          {
+            assertion = lib.hasInfix "color = \"never\"" toml;
+            message = "color should accept never";
+          }
+        ];
+    };
+
+    # test 8: freeform type allows custom keys
+    freeformCustomKeys = {
+      name = "freeform-custom-keys";
+      config = {
+        programs.snitch = {
+          enable = true;
+          settings = {
+            defaults.theme = "dracula";
+            custom_section = {
+              custom_key = "custom_value";
+            };
+          };
+        };
+      };
+      assertions = evalResult:
+        let
+          toml = readGeneratedToml evalResult;
+        in
+        [
+          {
+            assertion = lib.hasInfix "custom_key" toml;
+            message = "freeform type should allow custom keys";
+          }
+        ];
+    };
+
+    # test 9: all themes evaluate correctly
+    allThemes =
+      let
+        themes = [
+          "ansi"
+          "catppuccin-mocha"
+          "catppuccin-macchiato"
+          "catppuccin-frappe"
+          "catppuccin-latte"
+          "gruvbox-dark"
+          "gruvbox-light"
+          "dracula"
+          "nord"
+          "tokyo-night"
+          "tokyo-night-storm"
+          "tokyo-night-light"
+          "solarized-dark"
+          "solarized-light"
+          "one-dark"
+          "mono"
+          "auto"
+        ];
+      in
+      {
+        name = "all-themes";
+        # use the last theme as the test config
+        config = {
+          programs.snitch = {
+            enable = true;
+            settings.defaults.theme = "auto";
+          };
+        };
+        assertions = evalResult:
+          let
+            # verify all themes can be set by evaluating them
+            themeResults = map
+              (theme:
+                let
+                  result = evalModule {
+                    programs.snitch = {
+                      enable = true;
+                      settings.defaults.theme = theme;
+                    };
+                  };
+                  toml = readGeneratedToml result;
+                in
+                {
+                  inherit theme;
+                  success = toml != null && lib.hasInfix theme toml;
+                }
+              )
+              themes;
+            allSucceeded = lib.all (r: r.success) themeResults;
+          in
+          [
+            {
+              assertion = allSucceeded;
+              message = "all themes should evaluate correctly: ${
+                lib.concatMapStringsSep ", " 
+                  (r: "${r.theme}=${if r.success then "ok" else "fail"}") 
+                  themeResults
+              }";
+            }
+          ];
+      };
+
+    # test 10: fields list serialization
+    fieldsListSerialization = {
+      name = "fields-list-serialization";
+      config = {
+        programs.snitch = {
+          enable = true;
+          settings.defaults.fields = [ "pid" "process" "proto" "state" ];
+        };
+      };
+      assertions = evalResult:
+        let
+          toml = readGeneratedToml evalResult;
+        in
+        [
+          {
+            assertion = lib.hasInfix "pid" toml && lib.hasInfix "process" toml;
+            message = "fields list should be serialized correctly";
+          }
+        ];
+    };
+  };
+
+  # run all tests and collect results
+  runTests =
+    let
+      testResults = lib.mapAttrsToList
+        (name: test:
+          let
+            evalResult = evalModule test.config;
+            assertions = test.assertions evalResult;
+            failures = lib.filter (a: !a.assertion) assertions;
+          in
+          {
+            inherit name;
+            testName = test.name;
+            passed = failures == [ ];
+            failures = map (f: f.message) failures;
+          }
+        )
+        tests;
+
+      allPassed = lib.all (r: r.passed) testResults;
+      failedTests = lib.filter (r: !r.passed) testResults;
+
+      summary = ''
+        ========================================
+        home manager module test results
+        ========================================
+        total tests: ${toString (builtins.length testResults)}
+        passed: ${toString (builtins.length (lib.filter (r: r.passed) testResults))}
+        failed: ${toString (builtins.length failedTests)}
+        ========================================
+        ${lib.concatMapStringsSep "\n" (r: 
+          if r.passed 
+          then "[yes] ${r.testName}"
+          else "[no] ${r.testName}\n  ${lib.concatStringsSep "\n  " r.failures}"
+        ) testResults}
+        ========================================
+      '';
+    in
+    {
+      inherit testResults allPassed failedTests summary;
+    };
+
+  results = runTests;
+
+in
+pkgs.runCommand "hm-module-test"
+{
+  passthru = {
+    inherit results;
+    # expose for debugging
+    inherit evalModule tests;
+  };
+}
+  (
+    if results.allPassed
+    then ''
+      echo "${results.summary}"
+      echo "all tests passed"
+      touch $out
+    ''
+    else ''
+      echo "${results.summary}"
+      echo ""
+      echo "failed tests:"
+      ${lib.concatMapStringsSep "\n" (t: ''
+        echo "  - ${t.testName}: ${lib.concatStringsSep ", " t.failures}"
+      '') results.failedTests}
+      exit 1
+    ''
+  )
+