feat: interactive setup wizard for first-run and netssh configure

- Auto-detects missing config (netbox.url empty) and launches wizard
- `netssh configure` re-runs the wizard anytime to change settings
- 3-page huh form: NetBox connection, SSH defaults, resolver & cache
- Saves to ~/.config/netssh.yaml (permissions 0600)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

cmd/netssh/main.go

@@ -16,12 +16,14 @@ import (
 	"git.zb-server.de/Sebi/ssh-netbox-wrapper/internal/config"
 	"git.zb-server.de/Sebi/ssh-netbox-wrapper/internal/netbox"
 	"git.zb-server.de/Sebi/ssh-netbox-wrapper/internal/resolver"
+	"git.zb-server.de/Sebi/ssh-netbox-wrapper/internal/setup"
 	internalssh "git.zb-server.de/Sebi/ssh-netbox-wrapper/internal/ssh"
 	"git.zb-server.de/Sebi/ssh-netbox-wrapper/internal/tui"
 )
 
 // managedSubcommands are dispatched to cobra; everything else is treated as SSH wrapper mode.
 var managedSubcommands = map[string]bool{
+	"configure":  true,
 	"search":     true,
 	"cache":      true,
 	"completion": true,
@@ -47,12 +49,28 @@ func main() {
 	runSSHWrapper(args)
 }
 
-// runSSHWrapper resolves the target hostname via NetBox and execs the native ssh binary.
-func runSSHWrapper(args []string) {
+// loadConfigOrSetup loads the config and runs the setup wizard if NetBox is not configured.
+func loadConfigOrSetup() *config.Config {
 	cfg, err := config.Load()
 	if err != nil {
 		fatalf("config: %v", err)
 	}
+	if cfg.NetBox.URL == "" {
+		fmt.Fprintln(os.Stderr, "No configuration found. Starting setup…")
+		if err := setup.RunWizard(cfg); err != nil {
+			fatalf("setup: %v", err)
+		}
+		cfg, err = config.Load()
+		if err != nil {
+			fatalf("config: %v", err)
+		}
+	}
+	return cfg
+}
+
+// runSSHWrapper resolves the target hostname via NetBox and execs the native ssh binary.
+func runSSHWrapper(args []string) {
+	cfg := loadConfigOrSetup()
 
 	parsed := internalssh.Parse(args)
 	if parsed == nil {
@@ -127,10 +145,7 @@ func connect(ip string, parsed *internalssh.ParsedArgs, originalArgs []string) {
 
 // runTUI starts the interactive host search.
 func runTUI() {
-	cfg, err := config.Load()
-	if err != nil {
-		fatalf("config: %v", err)
-	}
+	cfg := loadConfigOrSetup()
 
 	c := cache.New(cfg.Cache.Path, cfg.Cache.TTL)
 	_ = c.Load()
@@ -193,10 +208,24 @@ func rootCmd() *cobra.Command {
 	}
 
 	// cobra automatically adds a "completion" subcommand
-	root.AddCommand(searchCmd(), cacheCmd())
+	root.AddCommand(configureCmd(), searchCmd(), cacheCmd())
 	return root
 }
 
+func configureCmd() *cobra.Command {
+	return &cobra.Command{
+		Use:   "configure",
+		Short: "Interactively configure netssh",
+		RunE: func(cmd *cobra.Command, args []string) error {
+			cfg, _ := config.Load()
+			if cfg == nil {
+				cfg = &config.Config{}
+			}
+			return setup.RunWizard(cfg)
+		},
+	}
+}
+
 func searchCmd() *cobra.Command {
 	return &cobra.Command{
 		Use:   "search <query>",

go.mod

@@ -5,16 +5,20 @@ go 1.26.3
 require (
 	github.com/atotto/clipboard v0.1.4 // indirect
 	github.com/aymanbagabas/go-osc52/v2 v2.0.1 // indirect
+	github.com/catppuccin/go v0.3.0 // 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/huh v1.0.0 // 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/exp/strings v0.0.0-20240722160745-212f7b056ed0 // 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/dustin/go-humanize v1.0.1 // indirect
 	github.com/erikgeiser/coninput v0.0.0-20211004153227-1c3628e74d0f // indirect
 	github.com/fsnotify/fsnotify v1.9.0 // indirect
 	github.com/go-viper/mapstructure/v2 v2.4.0 // indirect
@@ -23,6 +27,7 @@ require (
 	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/mitchellh/hashstructure/v2 v2.0.2 // 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

go.sum

@@ -2,18 +2,24 @@ github.com/atotto/clipboard v0.1.4 h1:EH0zSVneZPSuFR11BlR9YppQTVDbh5+16AmcJi4g1z
 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/catppuccin/go v0.3.0 h1:d+0/YicIq+hSTo5oPuRi5kOpqkVA5tAsU6dNhvRu+aY=
+github.com/catppuccin/go v0.3.0/go.mod h1:8IHJuMGaUUjQM82qBrGNBv7LFq6JI3NnQCF6MOlZjpc=
 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/huh v1.0.0 h1:wOnedH8G4qzJbmhftTqrpppyqHakl/zbbNdXIWJyIxw=
+github.com/charmbracelet/huh v1.0.0/go.mod h1:5YVc+SlZ1IhQALxRPpkGwwEKftN/+OlJlnJYlDRFqN4=
 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/exp/strings v0.0.0-20240722160745-212f7b056ed0 h1:qko3AQ4gK1MTS/de7F5hPGx6/k1u0w4TeYmBFwzYVP4=
+github.com/charmbracelet/x/exp/strings v0.0.0-20240722160745-212f7b056ed0/go.mod h1:pBhA0ybfXv6hDjQUZ7hk1lVxBiUbupdw5R31yPUViVQ=
 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=
@@ -23,6 +29,8 @@ github.com/clipperhouse/stringish v0.1.1/go.mod h1:v/WhFtE1q0ovMta2+m+UbpZ+2/HEX
 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/dustin/go-humanize v1.0.1 h1:GzkhY7T5VNhEkwH0PVJgjz+fX1rhBrR7pRT3mDkpeCY=
+github.com/dustin/go-humanize v1.0.1/go.mod h1:Mu1zIs6XwVuF/gI1OepvI0qD18qycQx+mFykh5fBlto=
 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/fsnotify/fsnotify v1.9.0 h1:2Ml+OJNzbYCTzsxtv8vKSFD9PbJjmhYF14k/jKC7S9k=
@@ -39,6 +47,8 @@ github.com/mattn/go-localereader v0.0.1 h1:ygSAOl7ZXTx4RdPYinUpg6W99U8jWvWi9Ye2J
 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/mitchellh/hashstructure/v2 v2.0.2 h1:vGKWl0YJqUNxE8d+h8f6NJLcCJrgbhC4NcD46KavDd4=
+github.com/mitchellh/hashstructure/v2 v2.0.2/go.mod h1:MG3aRVU/N29oo/V/IhBX8GR/zz4kQkprJgF2EVszyDE=
 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=

internal/config/config.go

@@ -35,6 +35,15 @@ type SSHConfig struct {
 	DefaultUser string `mapstructure:"default_user"`
 }
 
+// Path returns the canonical config file path.
+func Path() string {
+	configDir, err := os.UserConfigDir()
+	if err != nil {
+		configDir = filepath.Join(os.Getenv("HOME"), ".config")
+	}
+	return filepath.Join(configDir, "netssh.yaml")
+}
+
 func Load() (*Config, error) {
 	v := viper.New()
 

internal/setup/wizard.go

@@ -0,0 +1,175 @@
+package setup
+
+import (
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strconv"
+	"strings"
+
+	"github.com/charmbracelet/huh"
+
+	"git.zb-server.de/Sebi/ssh-netbox-wrapper/internal/config"
+)
+
+// RunWizard runs the interactive setup form, pre-filled with any existing cfg values.
+// It saves the result to the config file on success.
+func RunWizard(cfg *config.Config) error {
+	url := cfg.NetBox.URL
+	token := cfg.NetBox.Token
+	defaultUser := cfg.SSH.DefaultUser
+	strategies := cfg.Resolver.Strategies
+	subnets := strings.Join(cfg.Resolver.ManagementSubnets, ", ")
+	interfaceName := cfg.Resolver.InterfaceName
+	cacheTTL := strconv.Itoa(cfg.Cache.TTL)
+
+	if len(strategies) == 0 {
+		strategies = []string{"primary_ip"}
+	}
+	if cacheTTL == "0" {
+		cacheTTL = "3600"
+	}
+
+	form := huh.NewForm(
+		huh.NewGroup(
+			huh.NewInput().
+				Title("NetBox URL").
+				Description("e.g. https://netbox.example.com").
+				Placeholder("https://").
+				Value(&url).
+				Validate(func(s string) error {
+					if strings.TrimSpace(s) == "" {
+						return errors.New("required")
+					}
+					return nil
+				}),
+			huh.NewInput().
+				Title("NetBox API token").
+				EchoMode(huh.EchoModePassword).
+				Value(&token).
+				Validate(func(s string) error {
+					if strings.TrimSpace(s) == "" {
+						return errors.New("required")
+					}
+					return nil
+				}),
+		).Title("NetBox connection"),
+
+		huh.NewGroup(
+			huh.NewInput().
+				Title("Default SSH user").
+				Description("Leave empty to use your system user ($USER).").
+				Value(&defaultUser),
+		).Title("SSH defaults"),
+
+		huh.NewGroup(
+			huh.NewMultiSelect[string]().
+				Title("Resolver strategies").
+				Description("Order matters: first match wins.").
+				Options(
+					huh.NewOption("primary_ip  — NetBox primary IPv4/IPv6", "primary_ip"),
+					huh.NewOption("management_subnet  — first IP inside a subnet", "management_subnet"),
+					huh.NewOption("interface_name  — IP on a named interface", "interface_name"),
+				).
+				Value(&strategies),
+			huh.NewInput().
+				Title("Management subnets").
+				Description("Comma-separated CIDRs, e.g. 10.0.0.0/8, 192.168.0.0/16\nOnly used when management_subnet strategy is active.").
+				Value(&subnets),
+			huh.NewInput().
+				Title("Interface name").
+				Description("Only used when interface_name strategy is active.").
+				Placeholder("eth0").
+				Value(&interfaceName),
+			huh.NewInput().
+				Title("Cache TTL (seconds)").
+				Value(&cacheTTL).
+				Validate(func(s string) error {
+					if _, err := strconv.Atoi(s); err != nil {
+						return errors.New("must be a number")
+					}
+					return nil
+				}),
+		).Title("Resolver & cache"),
+	)
+
+	if err := form.Run(); err != nil {
+		if errors.Is(err, huh.ErrUserAborted) {
+			fmt.Fprintln(os.Stderr, "Setup cancelled.")
+			os.Exit(0)
+		}
+		return err
+	}
+
+	ttl, _ := strconv.Atoi(cacheTTL)
+
+	var subnetList []string
+	for _, s := range strings.Split(subnets, ",") {
+		if s = strings.TrimSpace(s); s != "" {
+			subnetList = append(subnetList, s)
+		}
+	}
+
+	out := config.Config{
+		NetBox: config.NetBoxConfig{
+			URL:   strings.TrimRight(strings.TrimSpace(url), "/"),
+			Token: strings.TrimSpace(token),
+		},
+		SSH: config.SSHConfig{
+			DefaultUser: strings.TrimSpace(defaultUser),
+		},
+		Resolver: config.ResolverConfig{
+			Strategies:        strategies,
+			ManagementSubnets: subnetList,
+			InterfaceName:     strings.TrimSpace(interfaceName),
+		},
+		Cache: config.CacheConfig{
+			TTL: ttl,
+		},
+	}
+
+	return save(out)
+}
+
+func save(cfg config.Config) error {
+	path := config.Path()
+	if err := os.MkdirAll(filepath.Dir(path), 0o700); err != nil {
+		return fmt.Errorf("creating config dir: %w", err)
+	}
+
+	var b strings.Builder
+	b.WriteString("netbox:\n")
+	b.WriteString(fmt.Sprintf("  url: %q\n", cfg.NetBox.URL))
+	b.WriteString(fmt.Sprintf("  token: %q\n", cfg.NetBox.Token))
+
+	b.WriteString("\nresolver:\n")
+	b.WriteString("  strategies:\n")
+	for _, s := range cfg.Resolver.Strategies {
+		fmt.Fprintf(&b, "    - %s\n", s)
+	}
+	if len(cfg.Resolver.ManagementSubnets) > 0 {
+		b.WriteString("  management_subnets:\n")
+		for _, s := range cfg.Resolver.ManagementSubnets {
+			fmt.Fprintf(&b, "    - %s\n", s)
+		}
+	}
+	if cfg.Resolver.InterfaceName != "" {
+		fmt.Fprintf(&b, "  interface_name: %q\n", cfg.Resolver.InterfaceName)
+	}
+
+	b.WriteString("\ncache:\n")
+	fmt.Fprintf(&b, "  ttl: %d\n", cfg.Cache.TTL)
+
+	b.WriteString("\nssh:\n")
+	if cfg.SSH.DefaultUser != "" {
+		fmt.Fprintf(&b, "  default_user: %q\n", cfg.SSH.DefaultUser)
+	}
+
+	if err := os.WriteFile(path, []byte(b.String()), 0o600); err != nil {
+		return fmt.Errorf("writing config: %w", err)
+	}
+
+	fmt.Printf("\nConfig saved → %s\n", path)
+	return nil
+}