add knecht

2026-04-04 14:34:22 +02:00
parent 736477cf57
commit fe6ce5249e
22 changed files with 1885 additions and 1 deletions
--- a/knecht/cmd/deploy.go
+++ b/knecht/cmd/deploy.go
@@ -0,0 +1,68 @@
+package cmd
+
+import (
+	"fmt"
+
+	"github.com/jensbecker/homelab/knecht/portainer"
+	"github.com/jensbecker/homelab/knecht/stack"
+	"github.com/spf13/cobra"
+)
+
+var deployCmd = &cobra.Command{
+	Use:   "deploy <stack>",
+	Short: "Deploy a new stack from services/<stack>/docker-compose.yml",
+	Args:  cobra.ExactArgs(1),
+	RunE: func(cmd *cobra.Command, args []string) error {
+		_, client, svcPath, err := setup()
+		if err != nil {
+			return err
+		}
+
+		name := args[0]
+		local, err := stack.Get(svcPath, name)
+		if err != nil {
+			return err
+		}
+
+		// Check if already deployed
+		existing, err := client.GetStackByName(name)
+		if err != nil {
+			return err
+		}
+		if existing != nil {
+			return fmt.Errorf("stack %q already exists (id %d) — use `knecht update %s` instead", name, existing.ID, name)
+		}
+
+		compose, err := local.ReadCompose()
+		if err != nil {
+			return err
+		}
+
+		// Collect env vars from .env.example keys — values left empty for user to set in Portainer
+		exampleKeys, err := local.EnvExampleKeys()
+		if err != nil {
+			return err
+		}
+		env := make([]portainer.EnvVar, len(exampleKeys))
+		for i, k := range exampleKeys {
+			env[i] = portainer.EnvVar{Name: k, Value: ""}
+		}
+
+		s, err := client.CreateStack(name, compose, env)
+		if err != nil {
+			return err
+		}
+		fmt.Printf("Deployed stack %q (id %d)\n", s.Name, s.ID)
+		if len(exampleKeys) > 0 {
+			fmt.Println("Set the following env vars in Portainer:")
+			for _, k := range exampleKeys {
+				fmt.Printf("  • %s\n", k)
+			}
+		}
+		return nil
+	},
+}
+
+func init() {
+	rootCmd.AddCommand(deployCmd)
+}
--- a/knecht/cmd/diff.go
+++ b/knecht/cmd/diff.go
@@ -0,0 +1,84 @@
+package cmd
+
+import (
+	"fmt"
+
+	"github.com/jensbecker/homelab/knecht/drift"
+	"github.com/jensbecker/homelab/knecht/stack"
+	"github.com/spf13/cobra"
+)
+
+var diffCmd = &cobra.Command{
+	Use:   "diff <stack>",
+	Short: "Show drift between local and deployed compose + env keys",
+	Args:  cobra.ExactArgs(1),
+	RunE: func(cmd *cobra.Command, args []string) error {
+		_, client, svcPath, err := setup()
+		if err != nil {
+			return err
+		}
+
+		name := args[0]
+		local, err := stack.Get(svcPath, name)
+		if err != nil {
+			return err
+		}
+
+		remote, err := client.GetStackByName(name)
+		if err != nil {
+			return err
+		}
+		if remote == nil {
+			fmt.Printf("Stack %q is not deployed yet.\n", name)
+			return nil
+		}
+
+		remoteCompose, err := client.GetStackFile(remote.ID)
+		if err != nil {
+			return err
+		}
+		localCompose, err := local.ReadCompose()
+		if err != nil {
+			return err
+		}
+		exampleKeys, err := local.EnvExampleKeys()
+		if err != nil {
+			return err
+		}
+
+		portainerKeys := make([]string, len(remote.Env))
+		for i, e := range remote.Env {
+			portainerKeys[i] = e.Name
+		}
+
+		// Compose diff
+		composeDiff := drift.Compose(localCompose, remoteCompose)
+		fmt.Println("=== compose diff ===")
+		if len(composeDiff) == 0 {
+			fmt.Println("  in sync")
+		} else {
+			for _, line := range composeDiff {
+				fmt.Println("  " + line)
+			}
+		}
+
+		// Env key diff
+		missingKeys, unknownKeys := drift.EnvKeys(exampleKeys, portainerKeys)
+		fmt.Println("\n=== env keys ===")
+		if len(missingKeys) == 0 && len(unknownKeys) == 0 {
+			fmt.Println("  in sync")
+		}
+		for _, k := range missingKeys {
+			fmt.Printf("  ! missing in Portainer: %s\n", k)
+		}
+		for _, k := range unknownKeys {
+			fmt.Printf("  ? unknown (not in .env.example): %s\n", k)
+		}
+
+		return nil
+	},
+}
+
+func init() {
+	rootCmd.AddCommand(diffCmd)
+}
--- a/knecht/cmd/list.go
+++ b/knecht/cmd/list.go
@@ -0,0 +1,103 @@
+package cmd
+
+import (
+	"fmt"
+
+	"github.com/jensbecker/homelab/knecht/drift"
+	"github.com/jensbecker/homelab/knecht/portainer"
+	"github.com/jensbecker/homelab/knecht/stack"
+	"github.com/spf13/cobra"
+)
+
+var listCmd = &cobra.Command{
+	Use:   "list",
+	Short: "List all stacks with status and drift",
+	RunE: func(cmd *cobra.Command, args []string) error {
+		_, client, svcPath, err := setup()
+		if err != nil {
+			return err
+		}
+
+		stacks, err := client.ListStacks()
+		if err != nil {
+			return err
+		}
+
+		locals, err := stack.Discover(svcPath)
+		if err != nil {
+			return err
+		}
+		localByName := make(map[string]stack.Local, len(locals))
+		for _, l := range locals {
+			localByName[l.Name] = l
+		}
+
+		fmt.Printf("%-20s %-10s %s\n", "STACK", "STATUS", "DRIFT")
+		fmt.Println(repeat("-", 60))
+
+		for _, s := range stacks {
+			status := statusLabel(s.Status)
+			driftSummary := "no local compose"
+
+			local, ok := localByName[s.Name]
+			if ok {
+				driftSummary, err = computeDriftSummary(client, &s, &local)
+				if err != nil {
+					driftSummary = "error: " + err.Error()
+				}
+			}
+
+			fmt.Printf("%-20s %-10s %s\n", s.Name, status, driftSummary)
+		}
+		return nil
+	},
+}
+
+func init() {
+	rootCmd.AddCommand(listCmd)
+}
+
+func statusLabel(status int) string {
+	if status == 1 {
+		return "running"
+	}
+	return "stopped"
+}
+
+func computeDriftSummary(client *portainer.Client, s *portainer.Stack, local *stack.Local) (string, error) {
+	remoteCompose, err := client.GetStackFile(s.ID)
+	if err != nil {
+		return "", err
+	}
+	localCompose, err := local.ReadCompose()
+	if err != nil {
+		return "", err
+	}
+	exampleKeys, err := local.EnvExampleKeys()
+	if err != nil {
+		return "", err
+	}
+
+	portainerKeys := make([]string, len(s.Env))
+	for i, e := range s.Env {
+		portainerKeys[i] = e.Name
+	}
+
+	composeDiff := drift.Compose(localCompose, remoteCompose)
+	missingKeys, unknownKeys := drift.EnvKeys(exampleKeys, portainerKeys)
+
+	r := drift.Result{
+		ComposeDiff: composeDiff,
+		MissingKeys: missingKeys,
+		UnknownKeys: unknownKeys,
+	}
+	return r.Summary(), nil
+}
+
+func repeat(s string, n int) string {
+	out := ""
+	for i := 0; i < n; i++ {
+		out += s
+	}
+	return out
+}
--- a/knecht/cmd/logs.go
+++ b/knecht/cmd/logs.go
@@ -0,0 +1,68 @@
+package cmd
+
+import (
+	"fmt"
+	"os/exec"
+	"runtime"
+
+	"github.com/spf13/cobra"
+)
+
+var logsCmd = &cobra.Command{
+	Use:   "logs",
+	Short: "Open the Dozzle log viewer in the browser",
+	RunE: func(cmd *cobra.Command, args []string) error {
+		cfg, _, _, err := setup()
+		if err != nil {
+			return err
+		}
+
+		// Derive logs URL from Portainer URL (same base domain)
+		// e.g. https://portainer.home.jens.pub → https://logs.home.jens.pub
+		logsURL := deriveLogsURL(cfg.Portainer.URL)
+		fmt.Printf("Opening %s\n", logsURL)
+		return openBrowser(logsURL)
+	},
+}
+
+func init() {
+	rootCmd.AddCommand(logsCmd)
+}
+
+func deriveLogsURL(portainerURL string) string {
+	// Replace "portainer." prefix with "logs."
+	return fmt.Sprintf("https://logs.%s", domainFromURL(portainerURL))
+}
+
+func domainFromURL(u string) string {
+	// Strip scheme and find domain after first dot
+	u = stripScheme(u)
+	for i, c := range u {
+		if c == '.' {
+			return u[i+1:]
+		}
+	}
+	return u
+}
+
+func stripScheme(u string) string {
+	for _, prefix := range []string{"https://", "http://"} {
+		if len(u) > len(prefix) && u[:len(prefix)] == prefix {
+			return u[len(prefix):]
+		}
+	}
+	return u
+}
+
+func openBrowser(url string) error {
+	var cmd *exec.Cmd
+	switch runtime.GOOS {
+	case "darwin":
+		cmd = exec.Command("open", url)
+	case "linux":
+		cmd = exec.Command("xdg-open", url)
+	default:
+		return fmt.Errorf("unsupported platform: %s", runtime.GOOS)
+	}
+	return cmd.Start()
+}
--- a/knecht/cmd/root.go
+++ b/knecht/cmd/root.go
@@ -0,0 +1,61 @@
+package cmd
+
+import (
+	"fmt"
+	"os"
+
+	"github.com/jensbecker/homelab/knecht/config"
+	"github.com/jensbecker/homelab/knecht/portainer"
+	"github.com/jensbecker/homelab/knecht/stack"
+	"github.com/jensbecker/homelab/knecht/tui"
+	"github.com/spf13/cobra"
+)
+
+var servicesPathFlag string
+
+var rootCmd = &cobra.Command{
+	Use:   "knecht",
+	Short: "Homelab stack manager",
+	Long:  "knecht manages Portainer stacks from your local services/ directory.",
+	// No subcommand → launch TUI
+	RunE: func(cmd *cobra.Command, args []string) error {
+		cfg, client, svcPath, err := setup()
+		if err != nil {
+			return err
+		}
+		return tui.Run(client, svcPath, cfg)
+	},
+}
+
+func Execute() {
+	if err := rootCmd.Execute(); err != nil {
+		os.Exit(1)
+	}
+}
+
+func init() {
+	rootCmd.PersistentFlags().StringVar(&servicesPathFlag, "services", "", "path to services directory (default: auto-detected from git root)")
+}
+
+// setup loads config, builds the Portainer client, and resolves the services path.
+func setup() (*config.Config, *portainer.Client, string, error) {
+	cfg, err := config.Load()
+	if err != nil {
+		return nil, nil, "", err
+	}
+
+	client, err := portainer.New(cfg.Portainer.URL, cfg.Portainer.Token, cfg.Portainer.Endpoint)
+	if err != nil {
+		return nil, nil, "", fmt.Errorf("connecting to Portainer: %w", err)
+	}
+
+	svcPath, err := stack.ServicesPath(servicesPathFlag)
+	if svcPath == "" && err == nil {
+		svcPath, err = stack.ServicesPath(cfg.ServicesPath)
+	}
+	if err != nil {
+		return nil, nil, "", err
+	}
+
+	return cfg, client, svcPath, nil
+}
--- a/knecht/cmd/update.go
+++ b/knecht/cmd/update.go
@@ -0,0 +1,85 @@
+package cmd
+
+import (
+	"fmt"
+
+	"github.com/jensbecker/homelab/knecht/portainer"
+	"github.com/jensbecker/homelab/knecht/stack"
+	"github.com/spf13/cobra"
+)
+
+var updateCmd = &cobra.Command{
+	Use:   "update <stack>",
+	Short: "Update an existing stack, preserving env vars",
+	Args:  cobra.ExactArgs(1),
+	RunE: func(cmd *cobra.Command, args []string) error {
+		_, client, svcPath, err := setup()
+		if err != nil {
+			return err
+		}
+
+		name := args[0]
+		local, err := stack.Get(svcPath, name)
+		if err != nil {
+			return err
+		}
+
+		remote, err := client.GetStackByName(name)
+		if err != nil {
+			return err
+		}
+		if remote == nil {
+			return fmt.Errorf("stack %q not found — use `knecht deploy %s` to create it", name, name)
+		}
+
+		compose, err := local.ReadCompose()
+		if err != nil {
+			return err
+		}
+
+		// Check for missing env keys and prompt for values
+		exampleKeys, err := local.EnvExampleKeys()
+		if err != nil {
+			return err
+		}
+		env, err := mergeEnvVars(remote.Env, exampleKeys)
+		if err != nil {
+			return err
+		}
+
+		s, err := client.UpdateStack(remote.ID, compose, env)
+		if err != nil {
+			return err
+		}
+		fmt.Printf("Updated stack %q (id %d)\n", s.Name, s.ID)
+		return nil
+	},
+}
+
+// mergeEnvVars takes existing Portainer env vars and prompts for any keys
+// present in .env.example but missing from Portainer.
+func mergeEnvVars(existing []portainer.EnvVar, exampleKeys []string) ([]portainer.EnvVar, error) {
+	envMap := make(map[string]string, len(existing))
+	for _, e := range existing {
+		envMap[e.Name] = e.Value
+	}
+
+	for _, key := range exampleKeys {
+		if _, ok := envMap[key]; !ok {
+			fmt.Printf("Missing env var %q — enter value (leave empty to skip): ", key)
+			var val string
+			fmt.Scanln(&val)
+			envMap[key] = val
+		}
+	}
+
+	result := make([]portainer.EnvVar, 0, len(envMap))
+	for k, v := range envMap {
+		result = append(result, portainer.EnvVar{Name: k, Value: v})
+	}
+	return result, nil
+}
+
+func init() {
+	rootCmd.AddCommand(updateCmd)
+}
--- a/knecht/config/config.go
+++ b/knecht/config/config.go
@@ -0,0 +1,56 @@
+package config
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+
+	"github.com/BurntSushi/toml"
+)
+
+type Portainer struct {
+	URL      string `toml:"url"`
+	Token    string `toml:"token"`
+	Endpoint string `toml:"endpoint"` // optional name override, defaults to auto-discover
+}
+
+type Config struct {
+	Portainer    Portainer `toml:"portainer"`
+	ServicesPath string    `toml:"services_path"` // optional, defaults to git root / services
+}
+
+func Load() (*Config, error) {
+	path, err := configPath()
+	if err != nil {
+		return nil, err
+	}
+
+	var cfg Config
+	if _, err := toml.DecodeFile(path, &cfg); err != nil {
+		if os.IsNotExist(err) {
+			return nil, fmt.Errorf("config file not found at %s — run `knecht init` to create one", path)
+		}
+		return nil, fmt.Errorf("parsing config: %w", err)
+	}
+
+	if cfg.Portainer.URL == "" {
+		return nil, fmt.Errorf("portainer.url is required in %s", path)
+	}
+	if cfg.Portainer.Token == "" {
+		return nil, fmt.Errorf("portainer.token is required in %s", path)
+	}
+
+	return &cfg, nil
+}
+
+func Path() (string, error) {
+	return configPath()
+}
+
+func configPath() (string, error) {
+	home, err := os.UserHomeDir()
+	if err != nil {
+		return "", err
+	}
+	return filepath.Join(home, ".config", "knecht", "config.toml"), nil
+}
--- a/knecht/drift/drift.go
+++ b/knecht/drift/drift.go
@@ -0,0 +1,102 @@
+package drift
+
+import (
+	"fmt"
+	"strings"
+)
+
+type Result struct {
+	ComposeDiff     []string // unified-style diff lines
+	MissingKeys     []string // in .env.example but not in Portainer
+	UnknownKeys     []string // in Portainer but not in .env.example (file exists)
+	PortainerOnlyKeys []string // Portainer has keys but no .env.example exists at all
+}
+
+func (r *Result) HasDrift() bool {
+	return len(r.ComposeDiff) > 0 || len(r.MissingKeys) > 0 || len(r.UnknownKeys) > 0 || len(r.PortainerOnlyKeys) > 0
+}
+
+func (r *Result) Summary() string {
+	parts := []string{}
+	if len(r.ComposeDiff) > 0 {
+		parts = append(parts, fmt.Sprintf("compose ~%d lines", len(r.ComposeDiff)))
+	}
+	if len(r.MissingKeys) > 0 {
+		parts = append(parts, fmt.Sprintf("%d env key(s) missing", len(r.MissingKeys)))
+	}
+	if len(r.UnknownKeys) > 0 {
+		parts = append(parts, fmt.Sprintf("%d env key(s) unknown", len(r.UnknownKeys)))
+	}
+	if len(r.PortainerOnlyKeys) > 0 {
+		parts = append(parts, fmt.Sprintf("no .env.example (%d key(s) in Portainer)", len(r.PortainerOnlyKeys)))
+	}
+	if len(parts) == 0 {
+		return "in sync"
+	}
+	return strings.Join(parts, ", ")
+}
+
+// Compose diffs local vs remote compose content line by line.
+func Compose(local, remote string) []string {
+	localLines := strings.Split(strings.TrimRight(local, "\n"), "\n")
+	remoteLines := strings.Split(strings.TrimRight(remote, "\n"), "\n")
+
+	if local == remote {
+		return nil
+	}
+
+	// Simple line-by-line diff: mark additions and removals.
+	remoteSet := toSet(remoteLines)
+	localSet := toSet(localLines)
+
+	var diff []string
+	for _, l := range remoteLines {
+		if !localSet[l] {
+			diff = append(diff, "- "+l)
+		}
+	}
+	for _, l := range localLines {
+		if !remoteSet[l] {
+			diff = append(diff, "+ "+l)
+		}
+	}
+	return diff
+}
+
+// EnvKeys compares keys from .env.example against keys set in Portainer.
+// If exampleKeys is nil (no .env.example file), both slices are returned nil —
+// use PortainerOnlyKeys on the Result instead to handle that case.
+func EnvKeys(exampleKeys []string, portainerKeys []string) (missing, unknown []string) {
+	if exampleKeys == nil {
+		return nil, nil
+	}
+
+	portainerSet := make(map[string]bool, len(portainerKeys))
+	for _, k := range portainerKeys {
+		portainerSet[k] = true
+	}
+	exampleSet := make(map[string]bool, len(exampleKeys))
+	for _, k := range exampleKeys {
+		exampleSet[k] = true
+	}
+
+	for _, k := range exampleKeys {
+		if !portainerSet[k] {
+			missing = append(missing, k)
+		}
+	}
+	for _, k := range portainerKeys {
+		if !exampleSet[k] {
+			unknown = append(unknown, k)
+		}
+	}
+	return
+}
+
+func toSet(lines []string) map[string]bool {
+	s := make(map[string]bool, len(lines))
+	for _, l := range lines {
+		s[l] = true
+	}
+	return s
+}
--- a/knecht/go.mod
+++ b/knecht/go.mod
@@ -0,0 +1,35 @@
+module github.com/jensbecker/homelab/knecht
+
+go 1.25.6
+
+require (
+	github.com/BurntSushi/toml v1.6.0 // indirect
+	github.com/atotto/clipboard v0.1.4 // indirect
+	github.com/aymanbagabas/go-osc52/v2 v2.0.1 // indirect
+	github.com/charmbracelet/bubbles v1.0.0 // indirect
+	github.com/charmbracelet/bubbletea v1.3.10 // indirect
+	github.com/charmbracelet/colorprofile v0.4.1 // indirect
+	github.com/charmbracelet/lipgloss v1.1.0 // indirect
+	github.com/charmbracelet/x/ansi v0.11.6 // indirect
+	github.com/charmbracelet/x/cellbuf v0.0.15 // indirect
+	github.com/charmbracelet/x/term v0.2.2 // indirect
+	github.com/clipperhouse/displaywidth v0.9.0 // indirect
+	github.com/clipperhouse/stringish v0.1.1 // indirect
+	github.com/clipperhouse/uax29/v2 v2.5.0 // 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.3.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.19 // 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/rivo/uniseg v0.4.7 // indirect
+	github.com/sahilm/fuzzy v0.1.1 // indirect
+	github.com/spf13/cobra v1.10.2 // indirect
+	github.com/spf13/pflag v1.0.9 // indirect
+	github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e // indirect
+	golang.org/x/sys v0.38.0 // indirect
+	golang.org/x/text v0.3.8 // indirect
+)
--- a/knecht/go.sum
+++ b/knecht/go.sum
@@ -0,0 +1,64 @@
+github.com/BurntSushi/toml v1.6.0 h1:dRaEfpa2VI55EwlIW72hMRHdWouJeRF7TPYhI+AUQjk=
+github.com/BurntSushi/toml v1.6.0/go.mod h1:ukJfTF/6rtPPRCnwkur4qwRxa8vTRFBF0uk2lLoLwho=
+github.com/atotto/clipboard v0.1.4 h1:EH0zSVneZPSuFR11BlR9YppQTVDbh5+16AmcJi4g1z4=
+github.com/atotto/clipboard v0.1.4/go.mod h1:ZY9tmq7sm5xIbd9bOK4onWV4S6X0u6GY7Vn0Yu86PYI=
+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/bubbles v1.0.0 h1:12J8/ak/uCZEMQ6KU7pcfwceyjLlWsDLAxB5fXonfvc=
+github.com/charmbracelet/bubbles v1.0.0/go.mod h1:9d/Zd5GdnauMI5ivUIVisuEm3ave1XwXtD1ckyV6r3E=
+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.4.1 h1:a1lO03qTrSIRaK8c3JRxJDZOvhvIeSco3ej+ngLk1kk=
+github.com/charmbracelet/colorprofile v0.4.1/go.mod h1:U1d9Dljmdf9DLegaJ0nGZNJvoXAhayhmidOdcBwAvKk=
+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.11.6 h1:GhV21SiDz/45W9AnV2R61xZMRri5NlLnl6CVF7ihZW8=
+github.com/charmbracelet/x/ansi v0.11.6/go.mod h1:2JNYLgQUsyqaiLovhU2Rv/pb8r6ydXKS3NIttu3VGZQ=
+github.com/charmbracelet/x/cellbuf v0.0.15 h1:ur3pZy0o6z/R7EylET877CBxaiE1Sp1GMxoFPAIztPI=
+github.com/charmbracelet/x/cellbuf v0.0.15/go.mod h1:J1YVbR7MUuEGIFPCaaZ96KDl5NoS0DAWkskup+mOY+Q=
+github.com/charmbracelet/x/term v0.2.2 h1:xVRT/S2ZcKdhhOuSP4t5cLi5o+JxklsoEObBSgfgZRk=
+github.com/charmbracelet/x/term v0.2.2/go.mod h1:kF8CY5RddLWrsgVwpw4kAa6TESp6EB5y3uxGLeCqzAI=
+github.com/clipperhouse/displaywidth v0.9.0 h1:Qb4KOhYwRiN3viMv1v/3cTBlz3AcAZX3+y9OLhMtAtA=
+github.com/clipperhouse/displaywidth v0.9.0/go.mod h1:aCAAqTlh4GIVkhQnJpbL0T/WfcrJXHcj8C0yjYcjOZA=
+github.com/clipperhouse/stringish v0.1.1 h1:+NSqMOr3GR6k1FdRhhnXrLfztGzuG+VuFDfatpWHKCs=
+github.com/clipperhouse/stringish v0.1.1/go.mod h1:v/WhFtE1q0ovMta2+m+UbpZ+2/HEXNWYXQgCt4hdOzA=
+github.com/clipperhouse/uax29/v2 v2.5.0 h1:x7T0T4eTHDONxFJsL94uKNKPHrclyFI0lm7+w94cO8U=
+github.com/clipperhouse/uax29/v2 v2.5.0/go.mod h1:Wn1g7MK6OoeDT0vL+Q0SQLDz/KpfsVRgg6W7ihQeh4g=
+github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g=
+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.3.0 h1:2/yBRLdWBZKrf7gB40FoiKfAWYQ0lqNcbuQwVHXptag=
+github.com/lucasb-eyer/go-colorful v1.3.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.19 h1:v++JhqYnZuu5jSKrk9RbgF5v4CGUjqRfBm05byFGLdw=
+github.com/mattn/go-runewidth v0.0.19/go.mod h1:XBkDxAl56ILZc9knddidhrOlY5R/pDhgLpndooCuJAs=
+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/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/sahilm/fuzzy v0.1.1 h1:ceu5RHF8DGgoi+/dR5PsECjCDH1BE3Fnmpo7aVXOdRA=
+github.com/sahilm/fuzzy v0.1.1/go.mod h1:VFvziUEIMCrT6A6tw2RFIXPXXmzXbOsSHF0DOI8ZK9Y=
+github.com/spf13/cobra v1.10.2 h1:DMTTonx5m65Ic0GOoRY2c16WCbHxOOw6xxezuLaBpcU=
+github.com/spf13/cobra v1.10.2/go.mod h1:7C1pvHqHw5A4vrJfjNwvOdzYu0Gml16OCs2GRiTUUS4=
+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/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=
+go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg=
+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.38.0 h1:3yZWxaJjBmCWXqhN1qh02AkOnCQ1poK6oF+a7xWL6Gc=
+golang.org/x/sys v0.38.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/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
--- a/knecht/main.go
+++ b/knecht/main.go
@@ -0,0 +1,7 @@
+package main
+
+import "github.com/jensbecker/homelab/knecht/cmd"
+
+func main() {
+	cmd.Execute()
+}
--- a/knecht/portainer/client.go
+++ b/knecht/portainer/client.go
@@ -0,0 +1,199 @@
+package portainer
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"strings"
+)
+
+type Client struct {
+	baseURL    string
+	token      string
+	httpClient *http.Client
+	endpointID int
+}
+
+type Endpoint struct {
+	ID   int    `json:"Id"`
+	Name string `json:"Name"`
+}
+
+type EnvVar struct {
+	Name  string `json:"name"`
+	Value string `json:"value"`
+}
+
+type Stack struct {
+	ID         int      `json:"Id"`
+	Name       string   `json:"Name"`
+	Status     int      `json:"Status"` // 1 = active, 2 = inactive
+	EndpointID int      `json:"EndpointId"`
+	Env        []EnvVar `json:"Env"`
+}
+
+type StackFile struct {
+	StackFileContent string `json:"StackFileContent"`
+}
+
+func New(baseURL, token, endpointName string) (*Client, error) {
+	c := &Client{
+		baseURL:    strings.TrimRight(baseURL, "/"),
+		token:      token,
+		httpClient: &http.Client{},
+	}
+
+	id, err := c.discoverEndpoint(endpointName)
+	if err != nil {
+		return nil, err
+	}
+	c.endpointID = id
+	return c, nil
+}
+
+func (c *Client) EndpointID() int {
+	return c.endpointID
+}
+
+func (c *Client) discoverEndpoint(name string) (int, error) {
+	var endpoints []Endpoint
+	if err := c.get("/api/endpoints", &endpoints); err != nil {
+		return 0, fmt.Errorf("listing endpoints: %w", err)
+	}
+	if len(endpoints) == 0 {
+		return 0, fmt.Errorf("no endpoints found in Portainer")
+	}
+	// If a name is specified, match by name; otherwise use the first active one.
+	for _, e := range endpoints {
+		if name == "" || e.Name == name {
+			return e.ID, nil
+		}
+	}
+	return 0, fmt.Errorf("endpoint %q not found", name)
+}
+
+func (c *Client) ListStacks() ([]Stack, error) {
+	var stacks []Stack
+	if err := c.get("/api/stacks", &stacks); err != nil {
+		return nil, err
+	}
+	return stacks, nil
+}
+
+func (c *Client) GetStack(id int) (*Stack, error) {
+	var s Stack
+	if err := c.get(fmt.Sprintf("/api/stacks/%d", id), &s); err != nil {
+		return nil, err
+	}
+	return &s, nil
+}
+
+func (c *Client) GetStackByName(name string) (*Stack, error) {
+	stacks, err := c.ListStacks()
+	if err != nil {
+		return nil, err
+	}
+	for _, s := range stacks {
+		if s.Name == name {
+			return &s, nil
+		}
+	}
+	return nil, nil // not found, not an error
+}
+
+func (c *Client) GetStackFile(id int) (string, error) {
+	var f StackFile
+	if err := c.get(fmt.Sprintf("/api/stacks/%d/file", id), &f); err != nil {
+		return "", err
+	}
+	return f.StackFileContent, nil
+}
+
+func (c *Client) CreateStack(name, composeContent string, env []EnvVar) (*Stack, error) {
+	body := map[string]any{
+		"name":             name,
+		"stackFileContent": composeContent,
+		"env":              env,
+	}
+	var s Stack
+	if err := c.post(fmt.Sprintf("/api/stacks/create/standalone/string?endpointId=%d", c.endpointID), body, &s); err != nil {
+		return nil, err
+	}
+	return &s, nil
+}
+
+func (c *Client) UpdateStack(id int, composeContent string, env []EnvVar) (*Stack, error) {
+	body := map[string]any{
+		"stackFileContent": composeContent,
+		"env":              env,
+		"prune":            true,
+		"pullImage":        false,
+	}
+	var s Stack
+	if err := c.put(fmt.Sprintf("/api/stacks/%d?endpointId=%d", id, c.endpointID), body, &s); err != nil {
+		return nil, err
+	}
+	return &s, nil
+}
+
+// request helpers
+
+func (c *Client) get(path string, out any) error {
+	resp, err := c.do("GET", path, nil)
+	if err != nil {
+		return err
+	}
+	defer resp.Body.Close()
+	return json.NewDecoder(resp.Body).Decode(out)
+}
+
+func (c *Client) post(path string, body, out any) error {
+	resp, err := c.do("POST", path, body)
+	if err != nil {
+		return err
+	}
+	defer resp.Body.Close()
+	return json.NewDecoder(resp.Body).Decode(out)
+}
+
+func (c *Client) put(path string, body, out any) error {
+	resp, err := c.do("PUT", path, body)
+	if err != nil {
+		return err
+	}
+	defer resp.Body.Close()
+	return json.NewDecoder(resp.Body).Decode(out)
+}
+
+func (c *Client) do(method, path string, body any) (*http.Response, error) {
+	var bodyReader io.Reader
+	if body != nil {
+		b, err := json.Marshal(body)
+		if err != nil {
+			return nil, err
+		}
+		bodyReader = bytes.NewReader(b)
+	}
+
+	req, err := http.NewRequest(method, c.baseURL+path, bodyReader)
+	if err != nil {
+		return nil, err
+	}
+	req.Header.Set("X-API-Key", c.token)
+	if body != nil {
+		req.Header.Set("Content-Type", "application/json")
+	}
+
+	resp, err := c.httpClient.Do(req)
+	if err != nil {
+		return nil, err
+	}
+	if resp.StatusCode >= 400 {
+		b, _ := io.ReadAll(resp.Body)
+		resp.Body.Close()
+		return nil, fmt.Errorf("portainer API %s %s: %s — %s", method, path, resp.Status, string(b))
+	}
+	return resp, nil
+}
--- a/knecht/stack/stack.go
+++ b/knecht/stack/stack.go
@@ -0,0 +1,144 @@
+package stack
+
+import (
+	"bufio"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+)
+
+type Local struct {
+	Name        string
+	ComposePath string
+	EnvExample  string // path to .env.example, may not exist
+}
+
+// Discover finds all stacks in the services directory.
+func Discover(servicesPath string) ([]Local, error) {
+	entries, err := os.ReadDir(servicesPath)
+	if err != nil {
+		return nil, fmt.Errorf("reading services dir %s: %w", servicesPath, err)
+	}
+
+	var stacks []Local
+	for _, e := range entries {
+		if !e.IsDir() {
+			continue
+		}
+		composePath := filepath.Join(servicesPath, e.Name(), "docker-compose.yml")
+		if _, err := os.Stat(composePath); err != nil {
+			continue // no compose file, skip
+		}
+		s := Local{
+			Name:        e.Name(),
+			ComposePath: composePath,
+			EnvExample:  filepath.Join(servicesPath, e.Name(), ".env.example"),
+		}
+		stacks = append(stacks, s)
+	}
+	return stacks, nil
+}
+
+// Get returns a single local stack by name.
+func Get(servicesPath, name string) (*Local, error) {
+	composePath := filepath.Join(servicesPath, name, "docker-compose.yml")
+	if _, err := os.Stat(composePath); err != nil {
+		return nil, fmt.Errorf("no docker-compose.yml found for stack %q in %s", name, servicesPath)
+	}
+	return &Local{
+		Name:        name,
+		ComposePath: composePath,
+		EnvExample:  filepath.Join(servicesPath, name, ".env.example"),
+	}, nil
+}
+
+// ReadCompose returns the raw compose file content.
+func (s *Local) ReadCompose() (string, error) {
+	b, err := os.ReadFile(s.ComposePath)
+	if err != nil {
+		return "", err
+	}
+	return string(b), nil
+}
+
+// EnvExampleKeys returns the variable names defined in .env.example.
+// Returns empty slice if the file doesn't exist.
+func (s *Local) EnvExampleKeys() ([]string, error) {
+	f, err := os.Open(s.EnvExample)
+	if os.IsNotExist(err) {
+		return nil, nil
+	}
+	if err != nil {
+		return nil, err
+	}
+	defer f.Close()
+
+	var keys []string
+	scanner := bufio.NewScanner(f)
+	for scanner.Scan() {
+		line := strings.TrimSpace(scanner.Text())
+		if line == "" || strings.HasPrefix(line, "#") {
+			continue
+		}
+		key, _, _ := strings.Cut(line, "=")
+		keys = append(keys, strings.TrimSpace(key))
+	}
+	return keys, scanner.Err()
+}
+
+// WriteEnvExample creates a .env.example file from a list of keys (values left empty).
+// Existing file is overwritten.
+func (s *Local) WriteEnvExample(keys []string) error {
+	var sb strings.Builder
+	sb.WriteString("# Generated by knecht from Portainer env vars\n")
+	for _, k := range keys {
+		sb.WriteString(k + "=\n")
+	}
+	return os.WriteFile(s.EnvExample, []byte(sb.String()), 0644)
+}
+
+// AppendEnvExample appends missing keys to an existing .env.example file.
+func (s *Local) AppendEnvExample(keys []string) error {
+	f, err := os.OpenFile(s.EnvExample, os.O_APPEND|os.O_WRONLY, 0644)
+	if err != nil {
+		return err
+	}
+	defer f.Close()
+	f.WriteString("\n# Added by knecht\n")
+	for _, k := range keys {
+		f.WriteString(k + "=\n")
+	}
+	return nil
+}
+
+// ServicesPath resolves the services directory: uses cfg value if set,
+// otherwise walks up from cwd to find the git root and appends /services.
+func ServicesPath(cfgPath string) (string, error) {
+	if cfgPath != "" {
+		return cfgPath, nil
+	}
+	return findServicesDir()
+}
+
+func findServicesDir() (string, error) {
+	dir, err := os.Getwd()
+	if err != nil {
+		return "", err
+	}
+	for {
+		if _, err := os.Stat(filepath.Join(dir, ".git")); err == nil {
+			p := filepath.Join(dir, "services")
+			if _, err := os.Stat(p); err == nil {
+				return p, nil
+			}
+			return "", fmt.Errorf("found git root at %s but no services/ directory", dir)
+		}
+		parent := filepath.Dir(dir)
+		if parent == dir {
+			break
+		}
+		dir = parent
+	}
+	return "", fmt.Errorf("could not find git root with a services/ directory")
+}
--- a/knecht/tui/tui.go
+++ b/knecht/tui/tui.go
@@ -0,0 +1,421 @@
+package tui
+
+import (
+	"fmt"
+	"strings"
+
+	"github.com/charmbracelet/bubbles/list"
+	"github.com/charmbracelet/bubbles/spinner"
+	tea "github.com/charmbracelet/bubbletea"
+	"github.com/charmbracelet/lipgloss"
+	"github.com/jensbecker/homelab/knecht/config"
+	"github.com/jensbecker/homelab/knecht/drift"
+	"github.com/jensbecker/homelab/knecht/portainer"
+	"github.com/jensbecker/homelab/knecht/stack"
+)
+
+var (
+	titleStyle    = lipgloss.NewStyle().Bold(true).Foreground(lipgloss.Color("12"))
+	successStyle  = lipgloss.NewStyle().Bold(true).Foreground(lipgloss.Color("10"))
+	mutedStyle    = lipgloss.NewStyle().Foreground(lipgloss.Color("8"))
+	driftStyle    = lipgloss.NewStyle().Foreground(lipgloss.Color("11"))
+	errorStyle    = lipgloss.NewStyle().Foreground(lipgloss.Color("9"))
+	addStyle      = lipgloss.NewStyle().Foreground(lipgloss.Color("10"))
+	removeStyle   = lipgloss.NewStyle().Foreground(lipgloss.Color("9"))
+)
+
+type viewMode int
+
+const (
+	modeSummary viewMode = iota
+	modeDiff
+)
+
+// ── messages ─────────────────────────────────────────────────────────────────
+
+type stacksLoadedMsg []stackItem
+type updateDoneMsg struct{ err error }
+type envExampleWrittenMsg struct{ err error }
+type errMsg error
+
+// ── list item ────────────────────────────────────────────────────────────────
+
+type stackItem struct {
+	remote      portainer.Stack
+	local       *stack.Local
+	driftResult *drift.Result
+}
+
+func (s stackItem) Title() string {
+	name := s.remote.Name
+	if s.driftResult != nil && s.driftResult.HasDrift() {
+		name += driftStyle.Render(" ~")
+	}
+	return name
+}
+
+func (s stackItem) Description() string {
+	status := "running"
+	if s.remote.Status != 1 {
+		status = mutedStyle.Render("stopped")
+	}
+	if s.driftResult == nil {
+		return status + " · no local compose"
+	}
+	return status + " · " + s.driftResult.Summary()
+}
+
+func (s stackItem) FilterValue() string { return s.remote.Name }
+
+// ── model ────────────────────────────────────────────────────────────────────
+
+type model struct {
+	list     list.Model
+	spinner  spinner.Model
+	client   *portainer.Client
+	svcPath  string
+	mode     viewMode
+	updating bool
+	status   string // transient success/error message
+	width    int
+	height   int
+}
+
+func initialModel(client *portainer.Client, svcPath string) model {
+	l := list.New(nil, list.NewDefaultDelegate(), 0, 0)
+	l.Title = "knecht"
+	l.Styles.Title = titleStyle
+	l.SetShowHelp(false) // we render our own key hints
+
+	s := spinner.New()
+	s.Spinner = spinner.Dot
+	s.Style = lipgloss.NewStyle().Foreground(lipgloss.Color("12"))
+
+	return model{
+		list:    l,
+		spinner: s,
+		client:  client,
+		svcPath: svcPath,
+	}
+}
+
+// ── commands ──────────────────────────────────────────────────────────────────
+
+func loadStacks(client *portainer.Client, svcPath string) tea.Cmd {
+	return func() tea.Msg {
+		remotes, err := client.ListStacks()
+		if err != nil {
+			return errMsg(err)
+		}
+
+		locals, _ := stack.Discover(svcPath)
+		localByName := make(map[string]stack.Local, len(locals))
+		for _, l := range locals {
+			localByName[l.Name] = l
+		}
+
+		items := make([]stackItem, 0, len(remotes))
+		for _, r := range remotes {
+			item := stackItem{remote: r}
+			if l, ok := localByName[r.Name]; ok {
+				lCopy := l
+				item.local = &lCopy
+				item.driftResult = computeDrift(client, &r, &lCopy)
+			}
+			items = append(items, item)
+		}
+		return stacksLoadedMsg(items)
+	}
+}
+
+func writeEnvExample(s stackItem) tea.Cmd {
+	return func() tea.Msg {
+		if s.local == nil || s.driftResult == nil {
+			return envExampleWrittenMsg{fmt.Errorf("no local stack info")}
+		}
+		// No .env.example at all — create from scratch
+		if len(s.driftResult.PortainerOnlyKeys) > 0 {
+			return envExampleWrittenMsg{s.local.WriteEnvExample(s.driftResult.PortainerOnlyKeys)}
+		}
+		// .env.example exists but has unknown keys — append them
+		if len(s.driftResult.UnknownKeys) > 0 {
+			return envExampleWrittenMsg{s.local.AppendEnvExample(s.driftResult.UnknownKeys)}
+		}
+		return envExampleWrittenMsg{fmt.Errorf("nothing to write")}
+	}
+}
+
+func updateStack(client *portainer.Client, s stackItem) tea.Cmd {
+	return func() tea.Msg {
+		compose, err := s.local.ReadCompose()
+		if err != nil {
+			return updateDoneMsg{err}
+		}
+		_, err = client.UpdateStack(s.remote.ID, compose, s.remote.Env)
+		return updateDoneMsg{err}
+	}
+}
+
+// ── bubbletea ────────────────────────────────────────────────────────────────
+
+func (m model) Init() tea.Cmd {
+	return tea.Batch(loadStacks(m.client, m.svcPath), m.spinner.Tick)
+}
+
+func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
+	var cmds []tea.Cmd
+
+	switch msg := msg.(type) {
+
+	case tea.WindowSizeMsg:
+		m.width = msg.Width
+		m.height = msg.Height
+		m.list.SetSize(msg.Width/2, msg.Height-4)
+
+	case stacksLoadedMsg:
+		m.updating = false
+		items := make([]list.Item, len(msg))
+		for i, s := range msg {
+			sCopy := s
+			items[i] = sCopy
+		}
+		m.list.SetItems(items)
+
+	case updateDoneMsg:
+		m.updating = false
+		if msg.err != nil {
+			m.status = errorStyle.Render("Update failed: " + msg.err.Error())
+		} else {
+			m.status = successStyle.Render("Updated successfully — refreshing...")
+			cmds = append(cmds, loadStacks(m.client, m.svcPath))
+		}
+
+	case envExampleWrittenMsg:
+		if msg.err != nil {
+			m.status = errorStyle.Render("Failed to write .env.example: " + msg.err.Error())
+		} else {
+			m.status = successStyle.Render(".env.example created — refreshing...")
+			cmds = append(cmds, loadStacks(m.client, m.svcPath))
+		}
+
+	case errMsg:
+		m.updating = false
+		m.status = errorStyle.Render("Error: " + msg.Error())
+
+	case spinner.TickMsg:
+		if m.updating {
+			var cmd tea.Cmd
+			m.spinner, cmd = m.spinner.Update(msg)
+			cmds = append(cmds, cmd)
+		}
+
+	case tea.KeyMsg:
+		// Don't pass keys to the list while filtering is active
+		if m.list.SettingFilter() {
+			break
+		}
+
+		switch msg.String() {
+		case "q", "ctrl+c":
+			return m, tea.Quit
+
+		case "r":
+			m.status = ""
+			m.mode = modeSummary
+			cmds = append(cmds, loadStacks(m.client, m.svcPath))
+			return m, tea.Batch(cmds...)
+
+		case "d":
+			if m.mode == modeDiff {
+				m.mode = modeSummary
+			} else {
+				m.mode = modeDiff
+			}
+			return m, nil
+
+		case "u":
+			item, ok := m.list.SelectedItem().(stackItem)
+			if !ok || item.local == nil || m.updating {
+				return m, nil
+			}
+			m.updating = true
+			m.status = ""
+			m.mode = modeSummary
+			cmds = append(cmds, updateStack(m.client, item), m.spinner.Tick)
+			return m, tea.Batch(cmds...)
+
+		case "e":
+			item, ok := m.list.SelectedItem().(stackItem)
+			if !ok || item.driftResult == nil {
+				return m, nil
+			}
+			hasEnvDrift := len(item.driftResult.PortainerOnlyKeys) > 0 || len(item.driftResult.UnknownKeys) > 0
+			if !hasEnvDrift {
+				return m, nil
+			}
+			cmds = append(cmds, writeEnvExample(item))
+			return m, tea.Batch(cmds...)
+
+		case "esc":
+			m.mode = modeSummary
+			m.status = ""
+			return m, nil
+		}
+	}
+
+	var listCmd tea.Cmd
+	m.list, listCmd = m.list.Update(msg)
+	cmds = append(cmds, listCmd)
+
+	return m, tea.Batch(cmds...)
+}
+
+// ── views ─────────────────────────────────────────────────────────────────────
+
+func (m model) View() string {
+	left := m.list.View()
+
+	var detail string
+	if m.updating {
+		detail = m.spinner.View() + " Updating..."
+	} else if item, ok := m.list.SelectedItem().(stackItem); ok {
+		switch m.mode {
+		case modeDiff:
+			detail = renderDiff(item)
+		default:
+			detail = renderSummary(item)
+		}
+	}
+
+	if m.status != "" {
+		detail += "\n\n" + m.status
+	}
+
+	right := lipgloss.NewStyle().
+		Width(m.width/2 - 2).
+		Height(m.height - 4).
+		Padding(1, 2).
+		Border(lipgloss.RoundedBorder()).
+		Render(detail)
+
+	return lipgloss.JoinHorizontal(lipgloss.Top, left, right)
+}
+
+func renderSummary(s stackItem) string {
+	out := titleStyle.Render(s.remote.Name) + "\n\n"
+
+	if s.remote.Status == 1 {
+		out += fmt.Sprintf("status:  %s\n", successStyle.Render("running"))
+	} else {
+		out += fmt.Sprintf("status:  %s\n", mutedStyle.Render("stopped"))
+	}
+
+	if s.driftResult == nil {
+		out += mutedStyle.Render("no local compose file\n")
+		return out
+	}
+
+	out += fmt.Sprintf("drift:   %s\n", s.driftResult.Summary())
+
+	if len(s.driftResult.MissingKeys) > 0 {
+		out += "\n" + driftStyle.Render("missing env keys:") + "\n"
+		for _, k := range s.driftResult.MissingKeys {
+			out += fmt.Sprintf("  ! %s\n", k)
+		}
+	}
+	if len(s.driftResult.UnknownKeys) > 0 {
+		out += "\n" + mutedStyle.Render("unknown env keys (in Portainer, not in .env.example):") + "\n"
+		for _, k := range s.driftResult.UnknownKeys {
+			out += fmt.Sprintf("  ? %s\n", k)
+		}
+		out += mutedStyle.Render("  [e] append to .env.example") + "\n"
+	}
+	if len(s.driftResult.PortainerOnlyKeys) > 0 {
+		out += "\n" + driftStyle.Render("no .env.example — Portainer has:") + "\n"
+		for _, k := range s.driftResult.PortainerOnlyKeys {
+			out += fmt.Sprintf("  • %s\n", k)
+		}
+		out += mutedStyle.Render("  [e] generate .env.example") + "\n"
+	}
+
+	out += "\n" + mutedStyle.Render("[u] update  [d] diff  [r] refresh  [esc] back  [q] quit")
+	return out
+}
+
+func renderDiff(s stackItem) string {
+	out := titleStyle.Render(s.remote.Name+" — diff") + "\n\n"
+
+	if s.driftResult == nil {
+		return out + mutedStyle.Render("no local compose file")
+	}
+
+	// Compose diff
+	out += mutedStyle.Render("compose:") + "\n"
+	if len(s.driftResult.ComposeDiff) == 0 {
+		out += "  " + successStyle.Render("in sync") + "\n"
+	} else {
+		for _, line := range s.driftResult.ComposeDiff {
+			if strings.HasPrefix(line, "+") {
+				out += "  " + addStyle.Render(line) + "\n"
+			} else {
+				out += "  " + removeStyle.Render(line) + "\n"
+			}
+		}
+	}
+
+	// Env key diff
+	out += "\n" + mutedStyle.Render("env keys:") + "\n"
+	if len(s.driftResult.MissingKeys) == 0 && len(s.driftResult.UnknownKeys) == 0 {
+		out += "  " + successStyle.Render("in sync") + "\n"
+	}
+	for _, k := range s.driftResult.MissingKeys {
+		out += "  " + driftStyle.Render("! missing: "+k) + "\n"
+	}
+	for _, k := range s.driftResult.UnknownKeys {
+		out += "  " + mutedStyle.Render("? unknown: "+k) + "\n"
+	}
+	if len(s.driftResult.PortainerOnlyKeys) > 0 {
+		out += "\n" + driftStyle.Render("no .env.example — Portainer has:") + "\n"
+		for _, k := range s.driftResult.PortainerOnlyKeys {
+			out += fmt.Sprintf("  • %s\n", k)
+		}
+	}
+
+	out += "\n" + mutedStyle.Render("[d] back  [u] update  [e] generate .env.example  [q] quit")
+	return out
+}
+
+// ── helpers ───────────────────────────────────────────────────────────────────
+
+func computeDrift(client *portainer.Client, s *portainer.Stack, local *stack.Local) *drift.Result {
+	remoteCompose, err := client.GetStackFile(s.ID)
+	if err != nil {
+		return nil
+	}
+	localCompose, _ := local.ReadCompose()
+	exampleKeys, _ := local.EnvExampleKeys()
+
+	portainerKeys := make([]string, len(s.Env))
+	for i, e := range s.Env {
+		portainerKeys[i] = e.Name
+	}
+
+	result := &drift.Result{
+		ComposeDiff: drift.Compose(localCompose, remoteCompose),
+	}
+
+	if exampleKeys == nil && len(portainerKeys) > 0 {
+		// No .env.example but Portainer has keys — surface as its own drift type
+		result.PortainerOnlyKeys = portainerKeys
+	} else {
+		result.MissingKeys, result.UnknownKeys = drift.EnvKeys(exampleKeys, portainerKeys)
+	}
+
+	return result
+}
+
+func Run(client *portainer.Client, svcPath string, _ *config.Config) error {
+	p := tea.NewProgram(initialModel(client, svcPath), tea.WithAltScreen())
+	_, err := p.Run()
+	return err
+}