Fix tmux: add -- separator for shell commands, kill stale sessions

README.md

@@ -203,8 +203,10 @@ ln -s /mnt/c/Users/<your-windows-username>/.kube/config ~/.kube/config
 
 ```bash
 kctl-tui                    # start the TUI (full navigation mode)
+kctl-tui --help             # show all commands and flags
 kctl-tui --version          # print version
 kctl-tui --verbose          # enable debug logging to stderr
+kctl-tui doctor             # check if all tools, config and connections are OK
 kctl-tui config check       # validate ~/.kctl-tui/config.yaml
 kctl-tui panel --context=... --ns=... --team=...   # internal (called by tmux)
 ```

SPEC.md

@@ -89,11 +89,12 @@ not cover: **redeploy** and **secrets diff**.
 Example startup command (generic placeholders):
 
 ```
+tmux kill-session -t kctl \; \
 tmux new-session -d -s kctl \
-  "kctl-tui panel --context=$CTX_A --ns=$NS --team=$TEAM" \; \
+  -- "kctl-tui panel --context=$CTX_A --ns=$NS --team=$TEAM" \; \
   set-option -t kctl remain-on-exit on \; \
-  split-window -v -t kctl:0.0 "k9s --context $CTX_A -n $NS" \; \
-  split-window -v -t kctl:0.1 "k9s --context $CTX_B -n $NS" \; \
+  split-window -v -t kctl:0.0 -- "k9s --context $CTX_A -n $NS" \; \
+  split-window -v -t kctl:0.1 -- "k9s --context $CTX_B -n $NS" \; \
   select-layout -t kctl even-vertical \; \
   select-pane -t kctl:0.0 \; \
   attach -t kctl

cmd/kctl-tui/full.go

@@ -2,6 +2,7 @@ package main
 
 import (
 	"fmt"
+	"os"
 	"os/exec"
 	"sort"
 
@@ -265,7 +266,10 @@ func (m *fullModel) loadNamespacesFor(teamValue string) tea.Cmd {
 // configured envs, resolved via the context template, so both are
 // visible side by side.
 func (m *fullModel) startTmuxSession() tea.Cmd {
-	selfPath := "kctl-tui"
+	selfPath, err := os.Executable()
+	if err != nil {
+		selfPath = "kctl-tui" // fallback to PATH lookup
+	}
 	panelCmd := fmt.Sprintf("%s panel --context=%s --ns=%s --team=%s",
 		selfPath, m.selectedContext, m.selectedNamespace, m.selectedTeam)
 
@@ -274,17 +278,18 @@ func (m *fullModel) startTmuxSession() tea.Cmd {
 	k9sCmdA := fmt.Sprintf("k9s --context %s -n %s", ctxA, m.selectedNamespace)
 
 	args := []string{
+		"kill-session", "-t", "kctl", ";", // ignore error if no session exists
 		"new-session", "-d", "-s", "kctl",
-		panelCmd, ";",
+		"--", panelCmd, ";",
 		"set-option", "-t", "kctl", "remain-on-exit", "on", ";",
-		"split-window", "-v", "-t", "kctl:0.0", k9sCmdA, ";",
+		"split-window", "-v", "-t", "kctl:0.0", "--", k9sCmdA, ";",
 	}
 	if len(m.cfg.Envs) > 1 {
 		envB := m.cfg.Envs[1]
 		ctxB := m.cfg.ResolveContext(envB, m.selectedContext)
 		k9sCmdB := fmt.Sprintf("k9s --context %s -n %s", ctxB, m.selectedNamespace)
 		args = append(args,
-			"split-window", "-v", "-t", "kctl:0.1", k9sCmdB, ";",
+			"split-window", "-v", "-t", "kctl:0.1", "--", k9sCmdB, ";",
 		)
 	}
 	args = append(args,

cmd/kctl-tui/main.go

@@ -18,6 +18,7 @@ func main() {
 
 	// Extract global flags before delegating to sub-commands.
 	verbose := false
+	showHelp := false
 	filtered := make([]string, 0, len(args))
 	for _, a := range args {
 		switch a {
@@ -26,6 +27,8 @@ func main() {
 		case "--version", "-v":
 			fmt.Printf("kctl-tui %s\n", version)
 			return
+		case "--help", "-h":
+			showHelp = true
 		default:
 			filtered = append(filtered, a)
 		}
@@ -34,6 +37,13 @@ func main() {
 		kubeexec.SetVerbose(true, os.Stderr)
 	}
 
+	if showHelp || len(filtered) == 0 {
+		printUsage()
+		if showHelp && len(filtered) == 0 {
+			return
+		}
+	}
+
 	if len(filtered) > 0 {
 		switch filtered[0] {
 		case "panel":
@@ -48,6 +58,12 @@ func main() {
 				os.Exit(1)
 			}
 			return
+		case "doctor":
+			if err := runDoctor(); err != nil {
+				fmt.Fprintln(os.Stderr, "kctl-tui doctor error:", err)
+				os.Exit(1)
+			}
+			return
 		}
 	}
 
@@ -59,6 +75,28 @@ func main() {
 	}
 }
 
+func printUsage() {
+	fmt.Print(`kctl-tui — Kubernetes entry-point TUI
+
+Usage:
+  kctl-tui [flags]             start the TUI (full navigation mode)
+  kctl-tui doctor              check tools, config and connections
+  kctl-tui config check        validate ~/.kctl-tui/config.yaml
+  kctl-tui panel [options]     control pane (called internally by tmux)
+
+Flags:
+  --verbose    log all kubectl/aws commands to stderr
+  --version    print version
+  --help       show this help
+
+Examples:
+  kctl-tui                          # start the TUI
+  kctl-tui doctor                   # verify everything is installed
+  kctl-tui --verbose 2>debug.log    # log commands to a file
+  kctl-tui config check             # validate config
+`)
+}
+
 func runConfig(args []string) error {
 	if len(args) == 0 || args[0] != "check" {
 		return fmt.Errorf("usage: kctl-tui config check")
@@ -110,3 +148,112 @@ func runConfig(args []string) error {
 	}
 	return nil
 }
+
+func runDoctor() error {
+	pass := "ok"
+	fail := "FAIL"
+	warn := "WARN"
+	status := pass
+	errs := 0
+
+	check := func(label string, err error) {
+		if err != nil {
+			fmt.Printf("  [%s] %s: %v\n", fail, label, err)
+			status = fail
+			errs++
+		} else {
+			fmt.Printf("  [%s] %s\n", pass, label)
+		}
+	}
+
+	warnCheck := func(label string, err error) {
+		if err != nil {
+			fmt.Printf("  [%s] %s: %v\n", warn, label, err)
+		} else {
+			fmt.Printf("  [%s] %s\n", pass, label)
+		}
+	}
+
+	// --- Tools ---
+	fmt.Println("\nTools:")
+	check("kubectl", kubeexec.CheckTool("kubectl"))
+	check("tmux/psmux", kubeexec.CheckTool("tmux"))
+	check("k9s", kubeexec.CheckTool("k9s"))
+	warnCheck("aws CLI (optional)", kubeexec.CheckTool("aws"))
+
+	// --- Config ---
+	fmt.Println("\nConfig:")
+	cfgPath, err := config.DefaultPath()
+	if err != nil {
+		fmt.Printf("  [%s] config path: %v\n", fail, err)
+		errs++
+		status = fail
+	} else {
+		cfg, err := config.Load(cfgPath)
+		if err != nil {
+			fmt.Printf("  [%s] load config: %v\n", fail, err)
+			errs++
+			status = fail
+		} else {
+			check("config file exists", nil)
+			if len(cfg.Contexts) == 0 {
+				fmt.Printf("  [%s] contexts configured\n", fail)
+				errs++
+				status = fail
+			} else {
+				fmt.Printf("  [%s] contexts configured (%d)\n", pass, len(cfg.Contexts))
+			}
+			if len(cfg.Envs) == 0 {
+				fmt.Printf("  [%s] envs configured\n", fail)
+				errs++
+				status = fail
+			} else {
+				fmt.Printf("  [%s] envs configured (%d)\n", pass, len(cfg.Envs))
+			}
+			if cfg.ContextTemplate != "" {
+				ctx := cfg.ResolveContext(cfg.Envs[0], cfg.Contexts[0])
+				fmt.Printf("  [%s] context_template resolves to: %s\n", pass, ctx)
+			} else {
+				fmt.Printf("  [%s] context_template is empty\n", fail)
+				errs++
+				status = fail
+			}
+			if cfg.SecretNameTemplate != "" && len(cfg.Envs) > 0 {
+				secret := cfg.ResolveSecretName("example-ns", cfg.Envs[0])
+				fmt.Printf("  [%s] secret_name_template resolves to: %s\n", pass, secret)
+			}
+		}
+	}
+
+	// --- Connections ---
+	fmt.Println("\nConnections:")
+	if kubeexec.CheckTool("kubectl") == nil {
+		err := kubeexec.CheckAWSAuth()
+		if err == nil {
+			fmt.Printf("  [%s] kubectl cluster reachable\n", pass)
+		} else {
+			// Not fatal — cluster might be unreachable from this machine
+			fmt.Printf("  [%s] kubectl cluster: %v\n", warn, err)
+		}
+	}
+	if kubeexec.CheckTool("aws") == nil {
+		err := kubeexec.CheckAWSAuth()
+		if err == nil {
+			fmt.Printf("  [%s] AWS credentials valid\n", pass)
+		} else {
+			fmt.Printf("  [%s] AWS credentials: %v\n", warn, err)
+		}
+	} else {
+		fmt.Printf("  [%s] AWS credentials (aws CLI not installed)\n", warn)
+	}
+
+	// --- Summary ---
+	fmt.Println()
+	if status == pass {
+		fmt.Println("All checks passed. kctl-tui is ready to use.")
+	} else {
+		fmt.Printf("%d error(s) found. Fix the issues above and re-run: kctl-tui doctor\n", errs)
+		os.Exit(1)
+	}
+	return nil
+}