feat: add status TUI subcommand with bubbletea

New 'healthd status' command renders check results grouped by category
with colored pass/fail indicators and recent alert history.

- One-shot mode: runs checks once, renders, exits
- Watch mode (-w): live-updating display on config interval
- Supports --only and --group filters
- Uses charmbracelet/bubbletea + lipgloss for rendering

Author: glitch418x

cmd/root.go

@@ -12,6 +12,7 @@ func NewRootCommand() *cobra.Command {
 	root.AddCommand(newDaemonCommand())
 	root.AddCommand(newInitCommand())
 	root.AddCommand(newNotifyCommand())
+	root.AddCommand(newStatusCommand())
 	root.AddCommand(newValidateCommand())
 	return root
 }

cmd/status.go

@@ -0,0 +1,68 @@
+package cmd
+
+import (
+	"errors"
+	"fmt"
+
+	tea "github.com/charmbracelet/bubbletea"
+	"github.com/spf13/cobra"
+	"github.com/uinaf/healthd/internal/config"
+	"github.com/uinaf/healthd/internal/runner"
+	"github.com/uinaf/healthd/internal/tui"
+)
+
+func newStatusCommand() *cobra.Command {
+	var configPath string
+	var only []string
+	var groups []string
+	var watch bool
+
+	cmd := &cobra.Command{
+		Use:   "status",
+		Short: "Render health check status in a terminal UI",
+		Args:  cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			cmd.SilenceUsage = true
+
+			resolvedPath, err := config.ResolvePath(configPath)
+			if err != nil {
+				return err
+			}
+
+			cfg, err := config.LoadFromPath(resolvedPath)
+			if err != nil {
+				return err
+			}
+
+			checks := runner.FilterChecks(cfg.Checks, only, groups)
+			if len(checks) == 0 {
+				return errors.New("no checks matched filters")
+			}
+
+			model := tui.NewModel(cfg, checks, watch)
+			program := tea.NewProgram(model, tea.WithOutput(cmd.OutOrStdout()), tea.WithInput(cmd.InOrStdin()))
+			finalModel, err := program.Run()
+			if err != nil {
+				return err
+			}
+
+			if !watch {
+				tuiModel, ok := finalModel.(tui.Model)
+				if !ok {
+					return fmt.Errorf("unexpected final model type %T", finalModel)
+				}
+				if !runner.AllPassed(tuiModel.Results()) {
+					return errors.New("one or more checks failed")
+				}
+			}
+
+			return nil
+		},
+	}
+
+	cmd.Flags().StringVar(&configPath, "config", "", fmt.Sprintf("config file path (default: %s)", config.DefaultConfigPath))
+	cmd.Flags().StringSliceVar(&only, "only", nil, "only run checks by name (repeat flag or pass comma-separated names)")
+	cmd.Flags().StringSliceVar(&groups, "group", nil, "only run checks by group (repeat flag or pass comma-separated groups)")
+	cmd.Flags().BoolVarP(&watch, "watch", "w", false, "watch checks on the configured interval")
+	return cmd
+}

cmd/status_test.go

@@ -0,0 +1,66 @@
+package cmd
+
+import (
+	"regexp"
+	"strings"
+	"testing"
+)
+
+var ansiEscape = regexp.MustCompile(`\x1b\[[0-9;]*[a-zA-Z]|\x1b\[\?[0-9;]*[a-zA-Z]`)
+
+func stripANSI(s string) string {
+	return ansiEscape.ReplaceAllString(s, "")
+}
+
+func TestStatusRendersAndFailsOnCheckFailure(t *testing.T) {
+	t.Parallel()
+
+	configPath := writeTestConfig(t, `
+interval = "1s"
+timeout = "1s"
+
+[[check]]
+name = "ok-check"
+group = "services"
+command = "true"
+
+[[check]]
+name = "bad-check"
+group = "services"
+command = "false"
+`)
+
+	result := executeCheckCommand(t, "status", "--config", configPath)
+	if result.err == nil {
+		t.Fatalf("expected non-nil error when checks fail")
+	}
+	cleaned := stripANSI(result.stdout)
+	if !strings.Contains(cleaned, "healthd - 2 checks - 1 ok - 1 fail") {
+		t.Fatalf("expected status header in output, got: %q", cleaned)
+	}
+	if !strings.Contains(cleaned, "services") {
+		t.Fatalf("expected group heading in output, got: %q", cleaned)
+	}
+}
+
+func TestStatusReturnsErrorWhenFiltersMatchNothing(t *testing.T) {
+	t.Parallel()
+
+	configPath := writeTestConfig(t, `
+interval = "1s"
+timeout = "1s"
+
+[[check]]
+name = "ok-check"
+group = "services"
+command = "true"
+`)
+
+	result := executeCheckCommand(t, "status", "--config", configPath, "--only", "missing")
+	if result.err == nil {
+		t.Fatal("expected filter miss to error")
+	}
+	if !strings.Contains(result.err.Error(), "no checks matched filters") {
+		t.Fatalf("unexpected error: %v", result.err)
+	}
+}

go.mod

@@ -1,6 +1,6 @@
 module github.com/uinaf/healthd
 
-go 1.22
+go 1.24.0
 
 require (
 	github.com/BurntSushi/toml v1.5.0
@@ -9,9 +9,28 @@ require (
 )
 
 require (
+	github.com/aymanbagabas/go-osc52/v2 v2.0.1 // indirect
+	github.com/charmbracelet/bubbletea v1.3.10 // indirect
+	github.com/charmbracelet/colorprofile v0.2.3-0.20250311203215-f60798e515dc // indirect
+	github.com/charmbracelet/lipgloss v1.1.0 // indirect
+	github.com/charmbracelet/x/ansi v0.10.1 // indirect
+	github.com/charmbracelet/x/cellbuf v0.0.13-0.20250311204145-2c3ea96c31dd // indirect
+	github.com/charmbracelet/x/term v0.2.1 // indirect
 	github.com/davecgh/go-spew v1.1.1 // indirect
+	github.com/erikgeiser/coninput v0.0.0-20211004153227-1c3628e74d0f // indirect
 	github.com/inconshreveable/mousetrap v1.1.0 // indirect
+	github.com/lucasb-eyer/go-colorful v1.2.0 // indirect
+	github.com/mattn/go-isatty v0.0.20 // indirect
+	github.com/mattn/go-localereader v0.0.1 // indirect
+	github.com/mattn/go-runewidth v0.0.16 // indirect
+	github.com/muesli/ansi v0.0.0-20230316100256-276c6243b2f6 // indirect
+	github.com/muesli/cancelreader v0.2.2 // indirect
+	github.com/muesli/termenv v0.16.0 // indirect
 	github.com/pmezard/go-difflib v1.0.0 // indirect
+	github.com/rivo/uniseg v0.4.7 // indirect
 	github.com/spf13/pflag v1.0.9 // indirect
+	github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e // indirect
+	golang.org/x/sys v0.36.0 // indirect
+	golang.org/x/text v0.3.8 // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect
 )

go.sum

@@ -1,19 +1,60 @@
 github.com/BurntSushi/toml v1.5.0 h1:W5quZX/G/csjUnuI8SUYlsHs9M38FC7znL0lIO+DvMg=
 github.com/BurntSushi/toml v1.5.0/go.mod h1:ukJfTF/6rtPPRCnwkur4qwRxa8vTRFBF0uk2lLoLwho=
+github.com/aymanbagabas/go-osc52/v2 v2.0.1 h1:HwpRHbFMcZLEVr42D4p7XBqjyuxQH5SMiErDT4WkJ2k=
+github.com/aymanbagabas/go-osc52/v2 v2.0.1/go.mod h1:uYgXzlJ7ZpABp8OJ+exZzJJhRNQ2ASbcXHWsFqH8hp8=
+github.com/charmbracelet/bubbletea v1.3.10 h1:otUDHWMMzQSB0Pkc87rm691KZ3SWa4KUlvF9nRvCICw=
+github.com/charmbracelet/bubbletea v1.3.10/go.mod h1:ORQfo0fk8U+po9VaNvnV95UPWA1BitP1E0N6xJPlHr4=
+github.com/charmbracelet/colorprofile v0.2.3-0.20250311203215-f60798e515dc h1:4pZI35227imm7yK2bGPcfpFEmuY1gc2YSTShr4iJBfs=
+github.com/charmbracelet/colorprofile v0.2.3-0.20250311203215-f60798e515dc/go.mod h1:X4/0JoqgTIPSFcRA/P6INZzIuyqdFY5rm8tb41s9okk=
+github.com/charmbracelet/lipgloss v1.1.0 h1:vYXsiLHVkK7fp74RkV7b2kq9+zDLoEU4MZoFqR/noCY=
+github.com/charmbracelet/lipgloss v1.1.0/go.mod h1:/6Q8FR2o+kj8rz4Dq0zQc3vYf7X+B0binUUBwA0aL30=
+github.com/charmbracelet/x/ansi v0.10.1 h1:rL3Koar5XvX0pHGfovN03f5cxLbCF2YvLeyz7D2jVDQ=
+github.com/charmbracelet/x/ansi v0.10.1/go.mod h1:3RQDQ6lDnROptfpWuUVIUG64bD2g2BgntdxH0Ya5TeE=
+github.com/charmbracelet/x/cellbuf v0.0.13-0.20250311204145-2c3ea96c31dd h1:vy0GVL4jeHEwG5YOXDmi86oYw2yuYUGqz6a8sLwg0X8=
+github.com/charmbracelet/x/cellbuf v0.0.13-0.20250311204145-2c3ea96c31dd/go.mod h1:xe0nKWGd3eJgtqZRaN9RjMtK7xUYchjzPr7q6kcvCCs=
+github.com/charmbracelet/x/term v0.2.1 h1:AQeHeLZ1OqSXhrAWpYUtZyX1T3zVxfpZuEQMIQaGIAQ=
+github.com/charmbracelet/x/term v0.2.1/go.mod h1:oQ4enTYFV7QN4m0i9mzHrViD7TQKvNEEkHUMCmsxdUg=
 github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g=
 github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/erikgeiser/coninput v0.0.0-20211004153227-1c3628e74d0f h1:Y/CXytFA4m6baUTXGLOoWe4PQhGxaX0KpnayAqC48p4=
+github.com/erikgeiser/coninput v0.0.0-20211004153227-1c3628e74d0f/go.mod h1:vw97MGsxSvLiUE2X8qFplwetxpGLQrlU1Q9AUEIzCaM=
 github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8=
 github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw=
+github.com/lucasb-eyer/go-colorful v1.2.0 h1:1nnpGOrhyZZuNyfu1QjKiUICQ74+3FNCN69Aj6K7nkY=
+github.com/lucasb-eyer/go-colorful v1.2.0/go.mod h1:R4dSotOR9KMtayYi1e77YzuveK+i7ruzyGqttikkLy0=
+github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY=
+github.com/mattn/go-isatty v0.0.20/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
+github.com/mattn/go-localereader v0.0.1 h1:ygSAOl7ZXTx4RdPYinUpg6W99U8jWvWi9Ye2JC/oIi4=
+github.com/mattn/go-localereader v0.0.1/go.mod h1:8fBrzywKY7BI3czFoHkuzRoWE9C+EiG4R1k4Cjx5p88=
+github.com/mattn/go-runewidth v0.0.16 h1:E5ScNMtiwvlvB5paMFdw9p4kSQzbXFikJ5SQO6TULQc=
+github.com/mattn/go-runewidth v0.0.16/go.mod h1:Jdepj2loyihRzMpdS35Xk/zdY8IAYHsh153qUoGf23w=
+github.com/muesli/ansi v0.0.0-20230316100256-276c6243b2f6 h1:ZK8zHtRHOkbHy6Mmr5D264iyp3TiX5OmNcI5cIARiQI=
+github.com/muesli/ansi v0.0.0-20230316100256-276c6243b2f6/go.mod h1:CJlz5H+gyd6CUWT45Oy4q24RdLyn7Md9Vj2/ldJBSIo=
+github.com/muesli/cancelreader v0.2.2 h1:3I4Kt4BQjOR54NavqnDogx/MIoWBFa0StPA8ELUXHmA=
+github.com/muesli/cancelreader v0.2.2/go.mod h1:3XuTXfFS2VjM+HTLZY9Ak0l6eUKfijIfMUZ4EgX0QYo=
+github.com/muesli/termenv v0.16.0 h1:S5AlUN9dENB57rsbnkPyfdGuWIlkmzJjbFf0Tf5FWUc=
+github.com/muesli/termenv v0.16.0/go.mod h1:ZRfOIKPFDYQoDFF4Olj7/QJbW60Ol/kL1pU3VfY/Cnk=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/rivo/uniseg v0.2.0/go.mod h1:J6wj4VEh+S6ZtnVlnTBMWIodfgj8LQOQFoIToxlJtxc=
+github.com/rivo/uniseg v0.4.7 h1:WUdvkW8uEhrYfLC4ZzdpI2ztxP1I582+49Oc5Mq64VQ=
+github.com/rivo/uniseg v0.4.7/go.mod h1:FN3SvrM+Zdj16jyLfmOkMNblXMcoc8DfTHruCPUcx88=
 github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
 github.com/spf13/cobra v1.10.1 h1:lJeBwCfmrnXthfAupyUTzJ/J4Nc1RsHC/mSRU2dll/s=
 github.com/spf13/cobra v1.10.1/go.mod h1:7SmJGaTHFVBY0jW4NXGluQoLvhqFQM+6XSKD+P4XaB0=
 github.com/spf13/pflag v1.0.9 h1:9exaQaMOCwffKiiiYk6/BndUBv+iRViNW+4lEMi0PvY=
 github.com/spf13/pflag v1.0.9/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
 github.com/stretchr/testify v1.10.0 h1:Xv5erBjTwe/5IxqUQTdXv5kgmIvbHo3QQyRwhJsOfJA=
 github.com/stretchr/testify v1.10.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
+github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e h1:JVG44RsyaB9T2KIHavMF/ppJZNG9ZpyihvCd0w101no=
+github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e/go.mod h1:RbqR21r5mrJuqunuUZ/Dhy/avygyECGrLceyNeo4LiM=
+golang.org/x/sys v0.0.0-20210809222454-d867a43fc93e/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.36.0 h1:KVRy2GtZBrk1cBYA7MKu5bEZFxQk4NIDV6RLVcC8o0k=
+golang.org/x/sys v0.36.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks=
+golang.org/x/text v0.3.8 h1:nAL+RVCQ9uMn3vJZbV+MRnydTJFPf8qqY42YiA6MrqY=
+golang.org/x/text v0.3.8/go.mod h1:E6s5w1FMmriuDzIBO73fBruAKo1PCIq6d2Q6DHfQ8WQ=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=

internal/tui/alerts.go

@@ -0,0 +1,87 @@
+package tui
+
+import (
+	"bufio"
+	"fmt"
+	"os"
+	"path/filepath"
+	"regexp"
+	"strings"
+	"time"
+)
+
+var alertLinePattern = regexp.MustCompile(`^(\S+) \[([^\]]+)\] ([^(]+) \(([^)]*)\) - (.*)$`)
+
+type AlertLine struct {
+	Time      time.Time
+	State     string
+	CheckName string
+	Group     string
+	Reason    string
+}
+
+func DefaultAlertsLogPath() (string, error) {
+	home, err := os.UserHomeDir()
+	if err != nil {
+		return "", fmt.Errorf("resolve user home: %w", err)
+	}
+	return filepath.Join(home, ".local", "state", "healthd", "alerts.log"), nil
+}
+
+func LoadRecentAlerts(path string, limit int) ([]AlertLine, error) {
+	if limit <= 0 {
+		return []AlertLine{}, nil
+	}
+
+	file, err := os.Open(path)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return []AlertLine{}, nil
+		}
+		return nil, fmt.Errorf("open alerts log %q: %w", path, err)
+	}
+	defer file.Close()
+
+	parsed := make([]AlertLine, 0, limit)
+	scanner := bufio.NewScanner(file)
+	for scanner.Scan() {
+		line := strings.TrimSpace(scanner.Text())
+		if line == "" {
+			continue
+		}
+		entry, ok := parseAlertLine(line)
+		if !ok {
+			continue
+		}
+		parsed = append(parsed, entry)
+	}
+
+	if err := scanner.Err(); err != nil {
+		return nil, fmt.Errorf("read alerts log %q: %w", path, err)
+	}
+
+	if len(parsed) <= limit {
+		return parsed, nil
+	}
+	return parsed[len(parsed)-limit:], nil
+}
+
+func parseAlertLine(line string) (AlertLine, bool) {
+	matches := alertLinePattern.FindStringSubmatch(line)
+	if len(matches) != 6 {
+		return AlertLine{}, false
+	}
+
+	ts, err := time.Parse(time.RFC3339, matches[1])
+	if err != nil {
+		return AlertLine{}, false
+	}
+
+	return AlertLine{
+		Time:      ts,
+		State:     strings.TrimSpace(matches[2]),
+		CheckName: strings.TrimSpace(matches[3]),
+		Group:     strings.TrimSpace(matches[4]),
+		Reason:    strings.TrimSpace(matches[5]),
+	}, true
+}

internal/tui/alerts_test.go

@@ -0,0 +1,47 @@
+package tui
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestLoadRecentAlertsParsesAndTails(t *testing.T) {
+	t.Parallel()
+
+	dir := t.TempDir()
+	path := filepath.Join(dir, "alerts.log")
+	content := "\n" +
+		"2026-02-27T08:37:00Z [crit] openclaw-up-to-date (services) - expected exit_code=0, got 1\n" +
+		"bad line\n" +
+		"2026-02-27T13:00:00Z [recovered] colima-running (services) - ok\n"
+	if err := os.WriteFile(path, []byte(content), 0o600); err != nil {
+		t.Fatalf("write log: %v", err)
+	}
+
+	alerts, err := LoadRecentAlerts(path, 1)
+	if err != nil {
+		t.Fatalf("LoadRecentAlerts error: %v", err)
+	}
+	if len(alerts) != 1 {
+		t.Fatalf("expected 1 alert, got %d", len(alerts))
+	}
+	if alerts[0].State != "recovered" {
+		t.Fatalf("expected recovered state, got %q", alerts[0].State)
+	}
+	if alerts[0].CheckName != "colima-running" {
+		t.Fatalf("expected check name colima-running, got %q", alerts[0].CheckName)
+	}
+}
+
+func TestLoadRecentAlertsMissingFileIsEmpty(t *testing.T) {
+	t.Parallel()
+
+	alerts, err := LoadRecentAlerts(filepath.Join(t.TempDir(), "missing.log"), 10)
+	if err != nil {
+		t.Fatalf("expected no error for missing file, got %v", err)
+	}
+	if len(alerts) != 0 {
+		t.Fatalf("expected no alerts, got %d", len(alerts))
+	}
+}