Improve --help output for tsh, tctl, tbot, teleport-update and teleport (#64122)

* Write CLI --help text to stdout instead of stderr

* Display only one level of subcommands in help text

* Prevent a hidden command from increasing indentation level

* Add entry to changelog explaining updates to --help output

CHANGELOG.md

@@ -21,6 +21,14 @@ other services. The limit is aggregated across all apps on the
 `connection_limits` configured, those values apply to app access
 connections after upgrading to v19.
 
+#### CLI --help Output Improvements
+
+In the past, Teleport CLI programs printed all subcommands, subcommands'
+subcommands, and so on, when the `--help` option was specified. Additionally,
+the output was written to stderr, rather than stdout. `--help` output now
+goes to stdout, and contains info on only one level of subcommands. Affected
+programs include `teleport`, `tsh`, `tctl`, `tbot`, and `teleport-update`.
+
 ## 18.5.0 (12/04/25)
 
 ### Kubernetes support for Relay Service

lib/utils/cli.go

@@ -341,12 +341,18 @@ func InitCLIParser(appName, appHelp string) (app *kingpin.Application) {
 	app.HelpFlag.Hidden()
 	app.HelpFlag.NoEnvar()
 
+	// write --help output to stdout instead of stderr
+	app.UsageWriter(os.Stdout)
+
 	// set our own help template
 	app.UsageFuncs(template.FuncMap{
 		"CommandPrintfWidth": func(cmds []*kingpin.CmdModel) int {
 			cmdWidth := defaultCommandPrintfWidth
 			for _, cmd := range cmds {
-				cmdWidth = max(cmdWidth, len(cmd.FullCommand))
+				if cmd.Hidden {
+					continue
+				}
+				cmdWidth = max(cmdWidth, len(cmd.Name))
 			}
 			return cmdWidth
 		},
@@ -449,10 +455,10 @@ const defaultUsageTemplate = `{{define "FormatCommand" -}}
 {{end -}}
 
 {{define "FormatCommands" -}}
-{{- $cmdWidth := .FlattenedCommands | CommandPrintfWidth -}}
-{{range .FlattenedCommands -}}
+{{- $cmdWidth := .Commands | CommandPrintfWidth -}}
+{{range .Commands -}}
 {{if not .Hidden -}}
-{{"  "}}{{printf (printf "%%-%ds" $cmdWidth) .FullCommand}}{{if .Default}} (Default){{end}} {{ .Help }}
+{{"  "}}{{printf (printf "%%-%ds" $cmdWidth) .Name}}{{if .Default}} (Default){{end}} {{ .Help }}
 {{end -}}
 {{end -}}
 {{end -}}

lib/utils/cli_test.go

@@ -267,6 +267,8 @@ func TestInitCLIParser(t *testing.T) {
 		app.Terminate(func(int) {})
 
 		app.Command("hello", "Hello.")
+		app.Command("very-long-command", "Very long command.")
+		app.Command("hidden-very-long-command", "This command is hidden.").Hidden()
 
 		create := app.Command("create", "Create.")
 		create.Command("box", "Box.")
@@ -275,6 +277,7 @@ func TestInitCLIParser(t *testing.T) {
 		start := app.Command("start", "Start.")
 		start.Command("legacy", "Legacy.").Default()
 		start.Command("workload-identity", "Workload identity.")
+
 		return app
 	}
 

lib/utils/testdata/TestInitCLIParser/command_width_aligned_for_subcommand_help.golden

@@ -5,8 +5,8 @@ Create.
 Flags:
 
 Commands:
-  create box    Box.
-  create rocket Rocket.
+  box          Box.
+  rocket       Rocket.
 
 Aliases:
 

lib/utils/testdata/TestInitCLIParser/command_width_aligned_on_unknown_command_error.golden

@@ -5,12 +5,11 @@ some help message
 Flags:
 
 Commands:
-  help                    Show help.
-  hello                   Hello.
-  create box              Box.
-  create rocket           Rocket.
-  start legacy            (Default) Legacy.
-  start workload-identity Workload identity.
+  help              Show help.
+  hello             Hello.
+  very-long-command Very long command.
+  create            Create.
+  start             Start.
 
 Try 'test help [command]' to get help for a given command.
 

lib/utils/testdata/TestInitCLIParser/command_width_expands_to_longest_command.golden

@@ -5,12 +5,11 @@ some help message
 Flags:
 
 Commands:
-  help                    Show help.
-  hello                   Hello.
-  create box              Box.
-  create rocket           Rocket.
-  start legacy            (Default) Legacy.
-  start workload-identity Workload identity.
+  help              Show help.
+  hello             Hello.
+  very-long-command Very long command.
+  create            Create.
+  start             Start.
 
 Try 'test help [command]' to get help for a given command.
 

lib/utils/testdata/TestInitCLIParser/default_subcommand_does_not_affect_column_width.golden

@@ -5,8 +5,8 @@ Start.
 Flags:
 
 Commands:
-  start legacy            (Default) Legacy.
-  start workload-identity Workload identity.
+  legacy            (Default) Legacy.
+  workload-identity Workload identity.
 
 Aliases: