feat(cli): support cobra GroupID and set error prefix

Commander layout now reads both cobra's native GroupID and the
legacy Annotations["group"] for command grouping. Projects can
use either approach while keeping salt's custom help formatting.

cli.Init sets SetErrPrefix(name + ":") for consistent error messages
across all raystack CLIs (e.g. "Error: frontier: unknown command").

Author: ravisuhag

cli/cli.go

@@ -43,6 +43,9 @@ func Init(rootCmd *cobra.Command, opts ...Option) {
 		opt(cfg)
 	}
 
+	// Set error prefix for consistent error messages.
+	rootCmd.SetErrPrefix(rootCmd.Name() + ":")
+
 	// Inject shared output and prompter into command context.
 	existing := rootCmd.PersistentPreRun
 	rootCmd.PersistentPreRun = func(cmd *cobra.Command, args []string) {

cli/commander/codex.go

@@ -13,12 +13,10 @@ import (
 // This command generates a Markdown documentation tree for all commands in the hierarchy.
 func (m *Manager) addMarkdownCommand(outputPath string) {
 	markdownCmd := &cobra.Command{
-		Use:    "markdown",
-		Short:  "Generate Markdown documentation for all commands",
-		Hidden: true,
-		Annotations: map[string]string{
-			"group": "help",
-		},
+		Use:     "markdown",
+		Short:   "Generate Markdown documentation for all commands",
+		Hidden:  true,
+		GroupID: "help",
 		RunE: func(cmd *cobra.Command, args []string) error {
 			return m.generateMarkdownTree(outputPath, m.RootCmd)
 		},

cli/commander/layout.go

@@ -18,7 +18,6 @@ import (
 // Section Titles for Help Output
 const (
 	usage     = "Usage"
-	corecmd   = "Core commands"
 	othercmd  = "Other commands"
 	helpcmd   = "Help topics"
 	flags     = "Flags"
@@ -86,7 +85,7 @@ func displayHelp(cmd *cobra.Command, args []string) {
 
 // buildHelpEntries constructs a structured help message for a command.
 func buildHelpEntries(cmd *cobra.Command) []helpEntry {
-	var coreCommands, helpCommands, otherCommands []string
+	var helpCommands, ungroupedCommands []string
 	groupCommands := map[string][]string{}
 
 	for _, c := range cmd.Commands() {
@@ -95,24 +94,15 @@ func buildHelpEntries(cmd *cobra.Command) []helpEntry {
 		}
 
 		entry := fmt.Sprintf("%s%s", rpad(c.Name(), c.NamePadding()+3), c.Short)
-		if group, ok := c.Annotations["group"]; ok {
-			switch group {
-			case "core":
-				coreCommands = append(coreCommands, entry)
-			case "help":
-				helpCommands = append(helpCommands, entry)
-			default:
-				groupCommands[group] = append(groupCommands[group], entry)
-			}
-		} else {
-			otherCommands = append(otherCommands, entry)
-		}
-	}
 
-	// Treat all commands as core if no groups are specified
-	if len(coreCommands) == 0 && len(groupCommands) == 0 {
-		coreCommands = otherCommands
-		otherCommands = []string{}
+		switch c.GroupID {
+		case "help":
+			helpCommands = append(helpCommands, entry)
+		case "":
+			ungroupedCommands = append(ungroupedCommands, entry)
+		default:
+			groupCommands[c.GroupID] = append(groupCommands[c.GroupID], entry)
+		}
 	}
 
 	helpEntries := []helpEntry{}
@@ -121,14 +111,16 @@ func buildHelpEntries(cmd *cobra.Command) []helpEntry {
 	}
 
 	helpEntries = append(helpEntries, helpEntry{usage, cmd.UseLine()})
-	if len(coreCommands) > 0 {
-		helpEntries = append(helpEntries, helpEntry{corecmd, strings.Join(coreCommands, "\n")})
-	}
-	for group, cmds := range groupCommands {
-		helpEntries = append(helpEntries, helpEntry{fmt.Sprintf("%s commands", toTitle(group)), strings.Join(cmds, "\n")})
-	}
-	if len(otherCommands) > 0 {
-		helpEntries = append(helpEntries, helpEntry{othercmd, strings.Join(otherCommands, "\n")})
+	if len(ungroupedCommands) > 0 && len(groupCommands) == 0 {
+		// No groups defined — show all commands under "Commands"
+		helpEntries = append(helpEntries, helpEntry{"Commands", strings.Join(ungroupedCommands, "\n")})
+	} else {
+		for group, cmds := range groupCommands {
+			helpEntries = append(helpEntries, helpEntry{fmt.Sprintf("%s commands", toTitle(group)), strings.Join(cmds, "\n")})
+		}
+		if len(ungroupedCommands) > 0 {
+			helpEntries = append(helpEntries, helpEntry{othercmd, strings.Join(ungroupedCommands, "\n")})
+		}
 	}
 	if len(helpCommands) > 0 {
 		helpEntries = append(helpEntries, helpEntry{helpcmd, strings.Join(helpCommands, "\n")})

cli/commander/manager.go

@@ -66,6 +66,13 @@ func New(rootCmd *cobra.Command, options ...func(*Manager)) *Manager {
 // It enables or disables features like custom help, reference documentation,
 // shell completion, help topics, and client hooks based on the Manager's settings.
 func (m *Manager) Init() {
+	// Register the help group used by salt's internal commands
+	// (reference, completion, topics). Developers register their
+	// own groups via rootCmd.AddGroup() before calling Init.
+	m.RootCmd.AddGroup(
+		&cobra.Group{ID: "help", Title: "Help topics:"},
+	)
+
 	if m.Help {
 		m.setCustomHelp()
 	}

cli/commander/reference.go

@@ -15,13 +15,11 @@ import (
 func (m *Manager) addReferenceCommand() {
 	var isPlain bool
 	refCmd := &cobra.Command{
-		Use:   "reference",
-		Short: "Comprehensive reference of all commands",
-		Long:  m.generateReferenceMarkdown(),
-		Run:   m.runReferenceCommand(&isPlain),
-		Annotations: map[string]string{
-			"group": "help",
-		},
+		Use:     "reference",
+		Short:   "Comprehensive reference of all commands",
+		Long:    m.generateReferenceMarkdown(),
+		Run:     m.runReferenceCommand(&isPlain),
+		GroupID: "help",
 	}
 	refCmd.SetHelpFunc(m.runReferenceCommand(&isPlain))
 	refCmd.Flags().BoolVarP(&isPlain, "plain", "p", true, "output in plain markdown (without ANSI color)")

cli/commander/topics.go

@@ -24,9 +24,7 @@ func (m *Manager) addHelpTopicCommand(topic HelpTopic) {
 		Long:    topic.Long,
 		Example: topic.Example,
 		Hidden:  false,
-		Annotations: map[string]string{
-			"group": "help",
-		},
+		GroupID: "help",
 	}
 
 	helpCmd.SetHelpFunc(helpTopicHelpFunc)

cli/config_cmd.go

@@ -35,9 +35,6 @@ func configInitCmd(appName string, defaultCfg interface{}) *cobra.Command {
 		Use:     "init",
 		Short:   "Initialize a new configuration file",
 		Example: fmt.Sprintf("  $ %s config init", appName),
-		Annotations: map[string]string{
-			"group": "core",
-		},
 		RunE: func(cmd *cobra.Command, _ []string) error {
 			loader := config.NewLoader(config.WithAppConfig(appName))
 			if err := loader.Init(defaultCfg); err != nil {
@@ -54,9 +51,6 @@ func configListCmd(appName string) *cobra.Command {
 		Use:     "list",
 		Short:   "List current configuration",
 		Example: fmt.Sprintf("  $ %s config list", appName),
-		Annotations: map[string]string{
-			"group": "core",
-		},
 		RunE: func(cmd *cobra.Command, _ []string) error {
 			loader := config.NewLoader(config.WithAppConfig(appName))
 			data, err := loader.View()