refactor(cli): add Execute, unexport error types, modernize idioms

Add cli.Execute() that owns all error dispatch (sentinels, flag errors,
default). Silence Cobra's built-in error/usage printing so Execute has
full control. Unexport FlagError and remove HandleError/NewFlagError —
flag wrapping is now internal to Init via SetFlagErrorFunc.

Modernize across packages: interface{} → any, os.IsNotExist →
errors.Is(fs.ErrNotExist), sort.Slice → slices.SortFunc. Update
migration guide and README to document cli.Execute.

Author: ravisuhag

MIGRATION.md

@@ -95,15 +95,23 @@ HTTP middleware is explicit — use `middleware.DefaultHTTP(logger)` for the sta
 
 ## CLI bootstrap
 
-New `cli.Init()` enhances your root command with standard features:
+`cli.Init()` enhances your root command with standard features and `cli.Execute()` runs it with proper error handling:
 
 ```go
 // Before
 rootCmd := &cobra.Command{Use: "frontier", Short: "identity management"}
 mgr := commander.New(rootCmd, commander.WithTopics(topics))
 mgr.Init()
 rootCmd.AddCommand(serverCmd, configCmd)
-rootCmd.Execute()
+
+cmd, err := rootCmd.ExecuteC()
+if err != nil {
+    if commander.IsCommandErr(err) {
+        fmt.Println(cmd.UsageString())
+    }
+    fmt.Println(err)
+    os.Exit(1)
+}
 
 // After
 import "github.com/raystack/salt/cli"
@@ -117,7 +125,7 @@ cli.Init(rootCmd,
     cli.Topics(topics...),
 )
 
-rootCmd.Execute()
+cli.Execute(rootCmd)
 ```
 
 Config command helper replaces boilerplate:
@@ -159,7 +167,7 @@ func newListCmd() *cobra.Command {
 
 ## Error handling
 
-`commander.IsCommandErr` (string matching) is replaced by typed errors and a helper:
+`commander.IsCommandErr` (string matching) and manual error handling are replaced by `cli.Execute`:
 
 ```go
 // Before
@@ -172,24 +180,38 @@ if err := rootCmd.Execute(); err != nil {
 }
 
 // After
-if err := rootCmd.Execute(); err != nil {
-    cli.HandleError(err) // handles ErrSilent, ErrCancel, FlagError, and default
-}
+cli.Execute(rootCmd) // handles all errors with proper exit codes
 ```
 
-In commands, return typed errors:
+`cli.Execute` uses `ExecuteC` internally and handles all error types:
+
+| Error | Behavior |
+|-------|----------|
+| `cli.ErrSilent` | Exit 1, no output (command already printed the error) |
+| `cli.ErrCancel` | Exit 0, no output (user cancelled) |
+| Flag errors | Prints error + failing command's usage, exit 1 |
+| Other errors | Prints "Error: \<message\>", exit 1 |
+
+In commands, return sentinel errors to control exit behavior:
 
 ```go
-// Command already printed the error — exit silently
+// Command already printed a rich error — exit 1, no extra output
+out.Error("connection failed: timeout")
 return cli.ErrSilent
 
-// User cancelled (ctrl-c) — exit 0
+// User cancelled (ctrl-c, declined prompt) — exit 0
 return cli.ErrCancel
-
-// Bad input — print error + usage
-return cli.NewFlagError(fmt.Errorf("--port must be positive"))
 ```
 
+The following exports are removed — their functionality is now internal to `cli.Execute`:
+
+| Removed | Replacement |
+|---------|-------------|
+| `cli.HandleError(err)` | `cli.Execute(rootCmd)` handles errors automatically |
+| `cli.NewFlagError(err)` | `cli.Init` wraps flag errors automatically via `SetFlagErrorFunc` |
+| `cli.FlagError` (type) | Unexported; flag errors are handled internally by `Execute` |
+| `commander.IsCommandErr(err)` | Removed; `Execute` detects and handles flag/command errors |
+
 ## Printer
 
 Package-level functions replaced by `Output` type:

README.md

@@ -6,7 +6,7 @@
 
 The standard way to build raystack services and CLIs.
 
-Salt provides `app.Run()` for services and `cli.Init()` for command-line tools, along with the building blocks they use: configuration, middleware, terminal output, and more.
+Salt provides `app.Run()` for services and `cli.Init()` / `cli.Execute()` for command-line tools, along with the building blocks they use: configuration, middleware, terminal output, and more.
 
 ## Quick start
 
@@ -57,11 +57,11 @@ func main() {
         cli.Version("0.1.0", "raystack/frontier"),
     )
 
-    rootCmd.Execute()
+    cli.Execute(rootCmd)
 }
 ```
 
-Help, shell completion, and reference docs added automatically. Commands access shared output via `cli.Output(cmd)`.
+`Init` adds help, shell completion, reference docs, and silences Cobra's default error output. `Execute` runs the command and handles all errors with proper exit codes. Commands access shared output via `cli.Output(cmd)`.
 
 ## Installation
 
@@ -78,7 +78,7 @@ Requires Go 1.24+.
 | Package | Description |
 |---------|-------------|
 | [`app`](app/) | Service lifecycle — config, logger, telemetry, server, graceful shutdown |
-| [`cli`](cli/) | CLI lifecycle — root command, help, completion, version check |
+| [`cli`](cli/) | CLI lifecycle — init, execute, error handling, help, completion, version check |
 
 ### Server & Middleware
 

app/option.go

@@ -17,7 +17,7 @@ type Option func(*App) error
 // WithConfig loads configuration into the target struct.
 // The target must be a pointer to a struct. Config is loaded eagerly
 // so that subsequent options can reference fields from it.
-func WithConfig(target interface{}, loaderOpts ...config.Option) Option {
+func WithConfig(target any, loaderOpts ...config.Option) Option {
 	return func(_ *App) error {
 		loader := config.NewLoader(loaderOpts...)
 		return loader.Load(target)

cli/cli.go

@@ -10,11 +10,12 @@
 //	    cli.Topics(authTopic, envTopic),
 //	)
 //
-//	rootCmd.Execute()
+//	cli.Execute(rootCmd)
 package cli
 
 import (
 	"context"
+	"errors"
 	"fmt"
 	"os"
 
@@ -46,6 +47,11 @@ func Init(rootCmd *cobra.Command, opts ...Option) {
 	// Set error prefix for consistent error messages.
 	rootCmd.SetErrPrefix(rootCmd.Name() + ":")
 
+	// Silence cobra's default error and usage printing.
+	// Errors are handled by Execute; usage is shown only for flag errors.
+	rootCmd.SilenceErrors = true
+	rootCmd.SilenceUsage = true
+
 	// Inject shared output and prompter into command context.
 	existing := rootCmd.PersistentPreRun
 	rootCmd.PersistentPreRun = func(cmd *cobra.Command, args []string) {
@@ -70,12 +76,46 @@ func Init(rootCmd *cobra.Command, opts ...Option) {
 	mgr := commander.New(rootCmd, managerOpts...)
 	mgr.Init()
 
+	// Wrap flag parsing errors so Execute can show contextual usage.
+	// Must be set after mgr.Init() which also configures a flag error func.
+	rootCmd.SetFlagErrorFunc(func(cmd *cobra.Command, err error) error {
+		return &flagError{err: err}
+	})
+
 	// Add version command if configured.
 	if cfg.version != "" {
 		rootCmd.AddCommand(versionCmd(rootCmd.Name(), cfg.version, cfg.repo))
 	}
 }
 
+// Execute runs the root command and handles errors with appropriate
+// exit codes and output. It uses ExecuteC to obtain the failing command
+// so flag errors can show contextual usage.
+//
+// This function never returns on error — it calls os.Exit.
+func Execute(rootCmd *cobra.Command) {
+	cmd, err := rootCmd.ExecuteC()
+	if err == nil {
+		return
+	}
+
+	var flagErr *flagError
+	switch {
+	case errors.Is(err, ErrCancel):
+		os.Exit(0)
+	case errors.Is(err, ErrSilent):
+		os.Exit(1)
+	case errors.As(err, &flagErr):
+		fmt.Fprintln(os.Stderr, err)
+		fmt.Fprintln(os.Stderr)
+		fmt.Fprintln(os.Stderr, cmd.UsageString())
+		os.Exit(1)
+	default:
+		fmt.Fprintf(os.Stderr, "Error: %s\n", err)
+		os.Exit(1)
+	}
+}
+
 func versionCmd(name, ver, repo string) *cobra.Command {
 	return &cobra.Command{
 		Use:   "version",

cli/cli_test.go

@@ -73,6 +73,33 @@ func TestInit(t *testing.T) {
 		err := root.Execute()
 		require.NoError(t, err)
 	})
+
+	t.Run("silences cobra error and usage output", func(t *testing.T) {
+		root := newTestRoot()
+		cli.Init(root)
+
+		assert.True(t, root.SilenceErrors, "SilenceErrors should be true")
+		assert.True(t, root.SilenceUsage, "SilenceUsage should be true")
+	})
+
+	t.Run("wraps flag errors for Execute", func(t *testing.T) {
+		root := newTestRoot()
+		root.Flags().Int("port", 8080, "server port")
+		root.RunE = func(cmd *cobra.Command, args []string) error { return nil }
+		cli.Init(root)
+
+		// Unknown flag returns an error (wrapped internally as flagError).
+		root.SetArgs([]string{"--unknown"})
+		err := root.Execute()
+		require.Error(t, err)
+		assert.Contains(t, err.Error(), "unknown flag")
+
+		// Invalid flag value also returns an error.
+		root.SetArgs([]string{"--port", "abc"})
+		err = root.Execute()
+		require.Error(t, err)
+		assert.Contains(t, err.Error(), "invalid argument")
+	})
 }
 
 func TestOutput(t *testing.T) {

cli/commander/codex.go

@@ -1,7 +1,9 @@
 package commander
 
 import (
+	"errors"
 	"fmt"
+	"io/fs"
 	"os"
 	"path/filepath"
 
@@ -67,7 +69,7 @@ func (m *Manager) generateMarkdownTree(rootOutputPath string, cmd *cobra.Command
 
 // ensureDir ensures that the given directory exists, creating it if necessary.
 func ensureDir(path string) error {
-	if _, err := os.Stat(path); os.IsNotExist(err) {
+	if _, err := os.Stat(path); errors.Is(err, fs.ErrNotExist) {
 		if err := os.MkdirAll(path, os.ModePerm); err != nil {
 			return err
 		}

cli/commander/completion.go

@@ -43,7 +43,7 @@ func (m *Manager) addCompletionCommand() {
 
 // generateCompletionSummary creates the long description for the `completion` command.
 func (m *Manager) generateCompletionSummary(exec string) string {
-	var execs []interface{}
+	var execs []any
 	for i := 0; i < 12; i++ {
 		execs = append(execs, exec)
 	}

cli/commander/layout.go

@@ -2,7 +2,6 @@ package commander
 
 import (
 	"bytes"
-	"errors"
 	"fmt"
 	"regexp"
 	"strings"
@@ -12,7 +11,6 @@ import (
 	"golang.org/x/text/language"
 
 	"github.com/spf13/cobra"
-	"github.com/spf13/pflag"
 )
 
 // Section Titles for Help Output
@@ -39,7 +37,6 @@ func (m *Manager) setCustomHelp() {
 		displayHelp(cmd, args)
 	})
 	m.RootCmd.SetUsageFunc(generateUsage)
-	m.RootCmd.SetFlagErrorFunc(handleFlagError)
 }
 
 // generateUsage customizes the usage function for a command.
@@ -64,14 +61,6 @@ func generateUsage(cmd *cobra.Command) error {
 	return nil
 }
 
-// handleFlagError processes flag-related errors, including the special case of help flags.
-func handleFlagError(cmd *cobra.Command, err error) error {
-	if errors.Is(err, pflag.ErrHelp) {
-		return err
-	}
-	return err
-}
-
 // displayHelp generates a custom help message for a Cobra command.
 func displayHelp(cmd *cobra.Command, args []string) {
 	if isRootCommand(cmd.Parent()) && len(args) >= 2 && args[1] != "--help" && args[1] != "-h" {

cli/config_cmd.go

@@ -17,7 +17,7 @@ import (
 // Usage:
 //
 //	rootCmd.AddCommand(cli.ConfigCommand("frontier", &Config{}))
-func ConfigCommand(appName string, defaultCfg interface{}) *cobra.Command {
+func ConfigCommand(appName string, defaultCfg any) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:     "config <command>",
 		Short:   "Manage client configuration",
@@ -30,7 +30,7 @@ func ConfigCommand(appName string, defaultCfg interface{}) *cobra.Command {
 	return cmd
 }
 
-func configInitCmd(appName string, defaultCfg interface{}) *cobra.Command {
+func configInitCmd(appName string, defaultCfg any) *cobra.Command {
 	return &cobra.Command{
 		Use:     "init",
 		Short:   "Initialize a new configuration file",

cli/error.go

@@ -1,50 +1,20 @@
 package cli
 
-import (
-	"errors"
-	"fmt"
-	"os"
-)
+import "errors"
 
 // ErrSilent indicates the command already printed its error.
-// The error handler should exit 1 without printing anything.
+// Execute will exit 1 without printing anything.
 var ErrSilent = errors.New("silent error")
 
 // ErrCancel indicates the user cancelled the operation (e.g. ctrl-c).
-// The error handler should exit 0.
+// Execute will exit 0 without printing anything.
 var ErrCancel = errors.New("cancelled")
 
-// FlagError wraps an error caused by bad flags or arguments.
-// The error handler should print the error and show usage.
-type FlagError struct {
-	Err error
+// flagError wraps an error caused by bad flags or arguments.
+// Execute prints the error and shows the failing command's usage.
+type flagError struct {
+	err error
 }
 
-func (e *FlagError) Error() string { return e.Err.Error() }
-func (e *FlagError) Unwrap() error { return e.Err }
-
-// NewFlagError creates a FlagError.
-func NewFlagError(err error) *FlagError {
-	return &FlagError{Err: err}
-}
-
-// HandleError handles a command error by type.
-// FlagError prints the error (usage is shown by cobra).
-// SilentError exits without printing.
-// CancelError exits with code 0.
-// Other errors print "Error: <message>".
-func HandleError(err error) {
-	if err == nil {
-		return
-	}
-
-	switch {
-	case errors.Is(err, ErrCancel):
-		os.Exit(0)
-	case errors.Is(err, ErrSilent):
-		os.Exit(1)
-	default:
-		fmt.Fprintf(os.Stderr, "Error: %s\n", err)
-		os.Exit(1)
-	}
-}
+func (e *flagError) Error() string { return e.err.Error() }
+func (e *flagError) Unwrap() error { return e.err }