Restructure CLI Help Output with Improved Categorization (#265)

* Restructure CLI help output with improved categorization

- Fix duplicate start command registration bug
- Reorganize commands into semantic categories:
  - Workspace Commands: core workspace operations (create, start, stop, ls, etc.)
  - Workspace Access: tools for accessing workspaces (shell, open, copy, port-forward)
  - Organization Management: org-related commands with helpful subcommand hints
  - Configuration: settings, secrets, and account management
  - Quick Start: onboarding commands like ollama
- Update command annotations from old categories (context, ssh, housekeeping) to new ones
- Add inline tips and hints to guide users (e.g., 'Use brev org --help for subcommands')
- Improve help text discoverability by showing common org subcommands in main help

* Hide dev-only commands from help output

- Move 'fu' command to hidden annotation (inappropriate name, dev-only)
- Move 'env-vars' to hidden annotation (redundant with configure-env-vars)
- These commands remain functional but won't appear in help text

* Hide non-functional secret command from help output

- Move 'secret' command to hidden annotation (non-functional)
- Command remains available but won't appear in help text

* Hide non-functional ollama command from help output

- Move 'ollama' command to hidden annotation (non-functional)
- Removes 'Quick Start' section from help (no longer needed)
- Command remains available but won't appear in help text

* Improve help text clarity and consistency

- Fix typo: 'pulic' -> 'public' in ssh-key description
- Standardize capitalization: all descriptions start with capital letter
- Capitalize proper nouns: Brev, SSH, CLI
- Improve command descriptions for clarity
- Remove misplaced org tip from workspace commands section
- Remove detailed subcommand list from org help
- Add inline tip to org command description

* Fix org subcommands not showing in help output

- Set org command to use default Cobra template instead of custom filtered template
- Update annotations for org subcommands to use consistent 'orgsubcommand' annotation
- This ensures all org subcommands (create, invite, ls, set) are visible when running 'brev org -h'

* Hide status command from help output

* Document invite and set as aliases in help text

- Update Short descriptions to indicate they are aliases for 'brev org invite' and 'brev org set'
- This makes it clearer to users that these are convenience shortcuts

* Capitalize flag descriptions for consistency

- Capitalize first letter of --user flag description
- Maintains consistency with command descriptions

* Capitalize Brev in help flag description

- Define help flag manually to override Cobra's default lowercase description
- Ensures consistency with 'Help for Brev' instead of 'help for brev'

* Hide internal commands and update workspace to instance in help text

* Add provider-dependent support warning for start, stop, and reset commands

* Update redeem command for new help structure and remove 'coupon' from descriptions

* Update pkg/cmd/refresh/refresh.go

Co-authored-by: Pratik Patel <patel.s.pratik@gmail.com>

---------

Co-authored-by: Pratik Patel <patel.s.pratik@gmail.com>

Author: cloin

pkg/cmd/background/background.go

@@ -30,7 +30,7 @@ type BackgroundStore interface {
 
 func NewCmdBackground(t *terminal.Terminal, s BackgroundStore) *cobra.Command {
 	cmd := &cobra.Command{
-		Annotations:           map[string]string{"workspace": ""},
+		Annotations:           map[string]string{"hidden": ""},
 		Use:                   "background [flags] [command]",
 		Aliases:               []string{"bg"},
 		DisableFlagsInUseLine: true,

pkg/cmd/cmd.go

@@ -69,9 +69,14 @@ var (
 
 func NewDefaultBrevCommand() *cobra.Command {
 	cmd := NewBrevCommand()
-	cmd.PersistentFlags().StringVar(&userFlag, "user", "", "non root user to use for per user configuration of commands run as root")
+
+	// Define help flag before Cobra does with proper capitalization
+	cmd.PersistentFlags().BoolP("help", "h", false, "Help for Brev")
+
+	cmd.PersistentFlags().StringVar(&userFlag, "user", "", "Non root user to use for per user configuration of commands run as root")
 	cmd.PersistentFlags().BoolVar(&printVersion, "version", false, "Print version output")
 	cmd.PersistentFlags().BoolVar(&noCheckLatest, "no-check-latest", false, "Do not check for the latest version when printing version")
+
 	return cmd
 }
 
@@ -213,19 +218,20 @@ func NewBrevCommand() *cobra.Command { //nolint:funlen,gocognit,gocyclo // defin
 			}
 		},
 	}
-	cobra.AddTemplateFunc("hasContextCommands", hasContextCommands)
-	cobra.AddTemplateFunc("contextCommands", contextCommands)
-	cobra.AddTemplateFunc("hasSSHCommands", hasSSHCommands)
-	cobra.AddTemplateFunc("sshCommands", sshCommands)
 	cobra.AddTemplateFunc("hasWorkspaceCommands", hasWorkspaceCommands)
 	cobra.AddTemplateFunc("workspaceCommands", workspaceCommands)
-	cobra.AddTemplateFunc("hasHousekeepingCommands", hasHousekeepingCommands)
-	cobra.AddTemplateFunc("hasDebugCommands", hasDebugCommands)
-	cobra.AddTemplateFunc("debugCommands", debugCommands)
-	cobra.AddTemplateFunc("printCautiousMetaCmdMessage", printCautiousMetaCmdMessage)
-	cobra.AddTemplateFunc("housekeepingCommands", housekeepingCommands)
+	cobra.AddTemplateFunc("hasProviderDependentCommands", hasProviderDependentCommands)
+	cobra.AddTemplateFunc("providerDependentCommands", providerDependentCommands)
+	cobra.AddTemplateFunc("hasAccessCommands", hasAccessCommands)
+	cobra.AddTemplateFunc("accessCommands", accessCommands)
+	cobra.AddTemplateFunc("hasOrganizationCommands", hasOrganizationCommands)
+	cobra.AddTemplateFunc("organizationCommands", organizationCommands)
+	cobra.AddTemplateFunc("hasConfigurationCommands", hasConfigurationCommands)
+	cobra.AddTemplateFunc("configurationCommands", configurationCommands)
 	cobra.AddTemplateFunc("hasQuickstartCommands", hasQuickstartCommands)
 	cobra.AddTemplateFunc("quickstartCommands", quickstartCommands)
+	cobra.AddTemplateFunc("hasDebugCommands", hasDebugCommands)
+	cobra.AddTemplateFunc("debugCommands", debugCommands)
 
 	cmds.SetUsageTemplate(usageTemplate)
 
@@ -274,7 +280,6 @@ func createCmdTree(cmd *cobra.Command, t *terminal.Terminal, loginCmdStore *stor
 	cmd.AddCommand(secret.NewCmdSecret(loginCmdStore, t))
 	cmd.AddCommand(sshkeys.NewCmdSSHKeys(t, loginCmdStore))
 	cmd.AddCommand(start.NewCmdStart(t, loginCmdStore, noLoginCmdStore))
-	cmd.AddCommand(start.NewCmdStart(t, loginCmdStore, noLoginCmdStore))
 	cmd.AddCommand(create.NewCmdCreate(t, loginCmdStore))
 	cmd.AddCommand(stop.NewCmdStop(t, loginCmdStore, noLoginCmdStore))
 	cmd.AddCommand(delete.NewCmdDelete(t, loginCmdStore, noLoginCmdStore))
@@ -291,122 +296,136 @@ func createCmdTree(cmd *cobra.Command, t *terminal.Terminal, loginCmdStore *stor
 	cmd.AddCommand(updatemodel.NewCmdupdatemodel(t, loginCmdStore))
 }
 
-func hasQuickstartCommands(cmd *cobra.Command) bool {
-	return len(quickstartCommands(cmd)) > 0
+func hasWorkspaceCommands(cmd *cobra.Command) bool {
+	return len(workspaceCommands(cmd)) > 0
 }
 
-func hasHousekeepingCommands(cmd *cobra.Command) bool {
-	return len(housekeepingCommands(cmd)) > 0
+func hasAccessCommands(cmd *cobra.Command) bool {
+	return len(accessCommands(cmd)) > 0
 }
 
-func hasDebugCommands(cmd *cobra.Command) bool {
-	return len(debugCommands(cmd)) > 0
+func hasOrganizationCommands(cmd *cobra.Command) bool {
+	return len(organizationCommands(cmd)) > 0
 }
 
-func printCautiousMetaCmdMessage() string {
-	yellow := color.New(color.FgYellow, color.Bold).SprintFunc()
-	return yellow("(we're actively working on getting rid of these commands)")
+func hasConfigurationCommands(cmd *cobra.Command) bool {
+	return len(configurationCommands(cmd)) > 0
 }
 
-func hasSSHCommands(cmd *cobra.Command) bool {
-	return len(sshCommands(cmd)) > 0
+func hasQuickstartCommands(cmd *cobra.Command) bool {
+	return len(quickstartCommands(cmd)) > 0
 }
 
-func hasWorkspaceCommands(cmd *cobra.Command) bool {
-	return len(workspaceCommands(cmd)) > 0
+func hasDebugCommands(cmd *cobra.Command) bool {
+	return len(debugCommands(cmd)) > 0
 }
 
-func hasContextCommands(cmd *cobra.Command) bool {
-	return len(contextCommands(cmd)) > 0
+func hasProviderDependentCommands(cmd *cobra.Command) bool {
+	return len(providerDependentCommands(cmd)) > 0
 }
 
-func quickstartCommands(cmd *cobra.Command) []*cobra.Command {
+func workspaceCommands(cmd *cobra.Command) []*cobra.Command {
 	cmds := []*cobra.Command{}
 	for _, sub := range cmd.Commands() {
-		if isQuickstartCommand(sub) {
+		if isWorkspaceCommand(sub) {
 			cmds = append(cmds, sub)
 		}
 	}
 	return cmds
 }
 
-func housekeepingCommands(cmd *cobra.Command) []*cobra.Command {
+func accessCommands(cmd *cobra.Command) []*cobra.Command {
 	cmds := []*cobra.Command{}
 	for _, sub := range cmd.Commands() {
-		if isHousekeepingCommand(sub) {
+		if isAccessCommand(sub) {
 			cmds = append(cmds, sub)
 		}
 	}
 	return cmds
 }
 
-func debugCommands(cmd *cobra.Command) []*cobra.Command {
+func organizationCommands(cmd *cobra.Command) []*cobra.Command {
 	cmds := []*cobra.Command{}
 	for _, sub := range cmd.Commands() {
-		if isDebugCommand(sub) {
+		if isOrganizationCommand(sub) {
 			cmds = append(cmds, sub)
 		}
 	}
 	return cmds
 }
 
-func sshCommands(cmd *cobra.Command) []*cobra.Command {
+func configurationCommands(cmd *cobra.Command) []*cobra.Command {
 	cmds := []*cobra.Command{}
 	for _, sub := range cmd.Commands() {
-		if isSSHCommand(sub) {
+		if isConfigurationCommand(sub) {
 			cmds = append(cmds, sub)
 		}
 	}
 	return cmds
 }
 
-func workspaceCommands(cmd *cobra.Command) []*cobra.Command {
+func quickstartCommands(cmd *cobra.Command) []*cobra.Command {
 	cmds := []*cobra.Command{}
 	for _, sub := range cmd.Commands() {
-		if isWorkspaceCommand(sub) {
+		if isQuickstartCommand(sub) {
+			cmds = append(cmds, sub)
+		}
+	}
+	return cmds
+}
+
+func debugCommands(cmd *cobra.Command) []*cobra.Command {
+	cmds := []*cobra.Command{}
+	for _, sub := range cmd.Commands() {
+		if isDebugCommand(sub) {
 			cmds = append(cmds, sub)
 		}
 	}
 	return cmds
 }
 
-func contextCommands(cmd *cobra.Command) []*cobra.Command {
+func providerDependentCommands(cmd *cobra.Command) []*cobra.Command {
 	cmds := []*cobra.Command{}
 	for _, sub := range cmd.Commands() {
-		if isContextCommand(sub) {
+		if isProviderDependentCommand(sub) {
 			cmds = append(cmds, sub)
 		}
 	}
 	return cmds
 }
 
-func isQuickstartCommand(cmd *cobra.Command) bool {
-	_, ok := cmd.Annotations["quickstart"]
+func isWorkspaceCommand(cmd *cobra.Command) bool {
+	_, ok := cmd.Annotations["workspace"]
 	return ok
 }
 
-func isHousekeepingCommand(cmd *cobra.Command) bool {
-	_, ok := cmd.Annotations["housekeeping"]
+func isAccessCommand(cmd *cobra.Command) bool {
+	_, ok := cmd.Annotations["access"]
 	return ok
 }
 
-func isDebugCommand(cmd *cobra.Command) bool {
-	_, ok := cmd.Annotations["debug"]
+func isOrganizationCommand(cmd *cobra.Command) bool {
+	_, ok := cmd.Annotations["organization"]
 	return ok
 }
 
-func isSSHCommand(cmd *cobra.Command) bool {
-	_, ok := cmd.Annotations["ssh"]
+func isConfigurationCommand(cmd *cobra.Command) bool {
+	_, ok := cmd.Annotations["configuration"]
 	return ok
 }
 
-func isWorkspaceCommand(cmd *cobra.Command) bool {
-	_, ok := cmd.Annotations["workspace"]
+func isQuickstartCommand(cmd *cobra.Command) bool {
+	_, ok := cmd.Annotations["quickstart"]
+	return ok
+}
+
+func isDebugCommand(cmd *cobra.Command) bool {
+	_, ok := cmd.Annotations["debug"]
 	return ok
 }
 
-func isContextCommand(cmd *cobra.Command) bool {
-	_, ok := cmd.Annotations["context"]
+func isProviderDependentCommand(cmd *cobra.Command) bool {
+	_, ok := cmd.Annotations["provider-dependent"]
 	return ok
 }
 
@@ -420,38 +439,44 @@ Aliases:
 Examples:
 {{.Example}}{{end}}{{if .HasAvailableSubCommands}}
 
-{{- if hasWorkspaceCommands . }}
+{{- if or (hasWorkspaceCommands .) (hasProviderDependentCommands .) }}
 
 Instance Commands:
 {{- range workspaceCommands . }}
   {{rpad .Name .NamePadding }} {{.Short}}
-{{- end}}{{- end}}
+{{- end}}
+{{- if hasProviderDependentCommands . }}
 
-{{- if hasSSHCommands . }}
+  The following commands have provider-dependent support:
+{{- range providerDependentCommands . }}
+  {{rpad .Name .NamePadding }} {{.Short}}
+{{- end}}{{- end}}{{- end}}
 
-{{- if hasContextCommands . }}
+{{- if hasAccessCommands . }}
 
-Context Commands:
-{{- range contextCommands . }}
+Instance Access:
+{{- range accessCommands . }}
   {{rpad .Name .NamePadding }} {{.Short}}
 {{- end}}{{- end}}
 
-SSH Commands:
-{{- range sshCommands . }}
+{{- if hasOrganizationCommands . }}
+
+Organization Management:
+{{- range organizationCommands . }}
   {{rpad .Name .NamePadding }} {{.Short}}
 {{- end}}{{- end}}
 
-{{- if hasQuickstartCommands . }}
+{{- if hasConfigurationCommands . }}
 
-Quickstart Commands:
-{{- range quickstartCommands . }}
+Configuration:
+{{- range configurationCommands . }}
   {{rpad .Name .NamePadding }} {{.Short}}
 {{- end}}{{- end}}
 
-{{- if hasHousekeepingCommands . }}
+{{- if hasQuickstartCommands . }}
 
-Housekeeping Commands:
-{{- range housekeepingCommands . }}
+Quick Start:
+{{- range quickstartCommands . }}
   {{rpad .Name .NamePadding }} {{.Short}}
 {{- end}}{{- end}}
 

pkg/cmd/configureenvvars/configureenvvars.go

@@ -26,10 +26,10 @@ type ConfigureEnvVarsStore interface {
 
 func NewCmdConfigureEnvVars(_ *terminal.Terminal, cevStore ConfigureEnvVarsStore) *cobra.Command {
 	cmd := &cobra.Command{
-		Annotations:           map[string]string{"housekeeping": ""},
+		Annotations:           map[string]string{"hidden": ""},
 		Use:                   "configure-env-vars",
 		DisableFlagsInUseLine: true,
-		Short:                 "configure env vars in supported shells",
+		Short:                 "Configure environment variables in supported shells",
 		Long:                  "configure env vars in supported shells",
 		Example:               "",
 		RunE: func(cmd *cobra.Command, args []string) error {

pkg/cmd/copy/copy.go

@@ -40,11 +40,11 @@ type CopyStore interface {
 func NewCmdCopy(t *terminal.Terminal, store CopyStore, noLoginStartStore CopyStore) *cobra.Command {
 	var host bool
 	cmd := &cobra.Command{
-		Annotations:           map[string]string{"ssh": ""},
+		Annotations:           map[string]string{"access": ""},
 		Use:                   "copy",
 		Aliases:               []string{"cp", "scp"},
 		DisableFlagsInUseLine: true,
-		Short:                 "copy files and directories between local and remote instance",
+		Short:                 "Copy files and directories between local and remote instance",
 		Long:                  copyLong,
 		Example:               copyExample,
 		Args:                  cmderrors.TransformToValidationError(cobra.ExactArgs(2)),

pkg/cmd/create/create.go

@@ -41,7 +41,7 @@ func NewCmdCreate(t *terminal.Terminal, createStore CreateStore) *cobra.Command
 		Annotations:           map[string]string{"workspace": ""},
 		Use:                   "create",
 		DisableFlagsInUseLine: true,
-		Short:                 "Create a new instance ",
+		Short:                 "Create a new instance",
 		Long:                  createLong,
 		Example:               createExample,
 		RunE: func(cmd *cobra.Command, args []string) error {

pkg/cmd/delete/delete.go

@@ -32,7 +32,7 @@ func NewCmdDelete(t *terminal.Terminal, loginDeleteStore DeleteStore, noLoginDel
 		Annotations:           map[string]string{"workspace": ""},
 		Use:                   "delete",
 		DisableFlagsInUseLine: true,
-		Short:                 "Delete a Brev instance",
+		Short:                 "Delete an instance",
 		Long:                  stripmd.Strip(deleteLong),
 		Example:               deleteExample,
 		ValidArgsFunction:     completions.GetAllWorkspaceNameCompletionHandler(noLoginDeleteStore, t),

pkg/cmd/envvars/envvars.go

@@ -10,7 +10,7 @@ type EnvVarsStore interface{}
 
 func NewCmdEnvVars(_ *terminal.Terminal, evStore EnvVarsStore) *cobra.Command {
 	cmd := &cobra.Command{
-		Annotations:           map[string]string{"housekeeping": ""},
+		Annotations:           map[string]string{"hidden": ""},
 		Use:                   "env-vars",
 		DisableFlagsInUseLine: true,
 		Short:                 "configure env vars in supported shells",

pkg/cmd/fu/fu.go

@@ -30,7 +30,7 @@ type FuStore interface {
 
 func NewCmdFu(t *terminal.Terminal, loginFuStore FuStore, noLoginFuStore FuStore) *cobra.Command {
 	cmd := &cobra.Command{
-		Annotations:           map[string]string{"workspace": ""},
+		Annotations:           map[string]string{"hidden": ""},
 		Use:                   "fu",
 		DisableFlagsInUseLine: true,
 		Short:                 "Fetch all workspaces for a user and delete them",

pkg/cmd/healthcheck/healthcheck.go

@@ -15,7 +15,7 @@ type HealthcheckStore interface {
 
 func NewCmdHealthcheck(t *terminal.Terminal, store HealthcheckStore) *cobra.Command {
 	cmd := &cobra.Command{
-		Annotations: map[string]string{"housekeeping": ""},
+		Annotations: map[string]string{"configuration": ""},
 		Use:         "healthcheck",
 		Short:       "Check backend to see if it's healthy",
 		Long:        "Check backend to see if it's healthy",

pkg/cmd/hello/hello.go

@@ -22,7 +22,7 @@ type HelloStore interface {
 
 func NewCmdHello(t *terminal.Terminal, store HelloStore) *cobra.Command {
 	cmd := &cobra.Command{
-		Annotations:           map[string]string{"housekeeping": ""},
+		Annotations:           map[string]string{"configuration": ""},
 		Use:                   "hello",
 		DisableFlagsInUseLine: true,
 		Long:                  "Get a quick onboarding of the Brev CLI",