Merge pull request #3334 from buildkite/better-helptext

Better helptext

Author: moskyb

clicommand/agent_pause.go

@@ -39,6 +39,7 @@ type AgentPauseConfig struct {
 
 var AgentPauseCommand = cli.Command{
 	Name:        "pause",
+	Category:    categoryJobCommands,
 	Usage:       "Pause the agent",
 	Description: pauseDescription,
 	Flags: slices.Concat(globalFlags(), apiFlags(), []cli.Flag{

clicommand/agent_resume.go

@@ -32,6 +32,7 @@ type AgentResumeConfig struct {
 
 var AgentResumeCommand = cli.Command{
 	Name:        "resume",
+	Category:    categoryJobCommands,
 	Usage:       "Resume the agent",
 	Description: resumeDescription,
 	Flags:       slices.Concat(globalFlags(), apiFlags()),

clicommand/agent_stop.go

@@ -38,6 +38,7 @@ type AgentStopConfig struct {
 
 var AgentStopCommand = cli.Command{
 	Name:        "stop",
+	Category:    categoryJobCommands,
 	Usage:       "Stop the agent",
 	Description: stopDescription,
 	Flags: slices.Concat(globalFlags(), apiFlags(), []cli.Flag{

clicommand/annotate.go

@@ -70,7 +70,8 @@ type AnnotateConfig struct {
 
 var AnnotateCommand = cli.Command{
 	Name:        "annotate",
-	Usage:       "Annotate the build page within the Buildkite UI with text from within a Buildkite job",
+	Category:    categoryJobCommands,
+	Usage:       "Annotate the build page in the Buildkite UI with information from within a Buildkite job",
 	Description: annotateHelpDescription,
 	Flags: slices.Concat(globalFlags(), apiFlags(), []cli.Flag{
 		cli.StringFlag{

clicommand/bootstrap.go

@@ -106,7 +106,8 @@ type BootstrapConfig struct {
 
 var BootstrapCommand = cli.Command{
 	Name:        "bootstrap",
-	Usage:       "Run a Buildkite job locally",
+	Usage:       "Harness used internally by the agent to run jobs as subprocesses",
+	Category:    categoryInternal,
 	Description: bootstrapHelpDescription,
 	Flags: []cli.Flag{
 		cli.StringFlag{

clicommand/commands.go

@@ -2,24 +2,32 @@ package clicommand
 
 import "github.com/urfave/cli"
 
+const (
+	categoryJobCommands = "Commands that can be run within a Buildkite job"
+	categoryInternal    = "Internal commands, not intended to be run by users"
+)
+
 var BuildkiteAgentCommands = []cli.Command{
 	// These commands are special. The have a different lifecycle to the others
 	AgentStartCommand,
 	BootstrapCommand,
+	KubernetesBootstrapCommand,
 
 	// These are in alphabetical order
 	AcknowledgementsCommand,
 	AnnotateCommand,
 	{
-		Name:  "annotation",
-		Usage: "Make changes to an annotation on the currently running build",
+		Name:     "annotation",
+		Category: categoryJobCommands,
+		Usage:    "Make changes to annotations on the currently running build",
 		Subcommands: []cli.Command{
 			AnnotationRemoveCommand,
 		},
 	},
 	{
-		Name:  "artifact",
-		Usage: "Upload/download artifacts from Buildkite jobs",
+		Name:     "artifact",
+		Category: categoryJobCommands,
+		Usage:    "Upload/download artifacts from Buildkite jobs",
 		Subcommands: []cli.Command{
 			ArtifactUploadCommand,
 			ArtifactDownloadCommand,
@@ -28,15 +36,17 @@ var BuildkiteAgentCommands = []cli.Command{
 		},
 	},
 	{
-		Name:  "build",
-		Usage: "Interact with a Buildkite build",
+		Name:     "build",
+		Category: categoryJobCommands,
+		Usage:    "Interact with a Buildkite build",
 		Subcommands: []cli.Command{
 			BuildCancelCommand,
 		},
 	},
 	{
-		Name:  "env",
-		Usage: "Process environment subcommands",
+		Name:     "env",
+		Category: categoryJobCommands,
+		Usage:    "Interact with the environment of the currently running build",
 		Subcommands: []cli.Command{
 			EnvDumpCommand,
 			EnvGetCommand,
@@ -45,10 +55,10 @@ var BuildkiteAgentCommands = []cli.Command{
 		},
 	},
 	GitCredentialsHelperCommand,
-	KubernetesBootstrapCommand,
 	{
-		Name:  "lock",
-		Usage: "Process lock subcommands",
+		Name:     "lock",
+		Category: categoryJobCommands,
+		Usage:    "Lock or unlock resources for the currently running build",
 		Subcommands: []cli.Command{
 			LockAcquireCommand,
 			LockDoCommand,
@@ -58,15 +68,17 @@ var BuildkiteAgentCommands = []cli.Command{
 		},
 	},
 	{
-		Name:  "redactor",
-		Usage: "Redact sensitive information from logs",
+		Name:     "redactor",
+		Category: categoryJobCommands,
+		Usage:    "Redact sensitive information from logs",
 		Subcommands: []cli.Command{
 			RedactorAddCommand,
 		},
 	},
 	{
-		Name:  "meta-data",
-		Usage: "Get/set data from Buildkite jobs",
+		Name:     "meta-data",
+		Category: categoryJobCommands,
+		Usage:    "Get/set metadata from Buildkite jobs",
 		Subcommands: []cli.Command{
 			MetaDataSetCommand,
 			MetaDataGetCommand,
@@ -75,31 +87,35 @@ var BuildkiteAgentCommands = []cli.Command{
 		},
 	},
 	{
-		Name:  "oidc",
-		Usage: "Interact with Buildkite OpenID Connect (OIDC)",
+		Name:     "oidc",
+		Category: categoryJobCommands,
+		Usage:    "Interact with Buildkite OpenID Connect (OIDC)",
 		Subcommands: []cli.Command{
 			OIDCRequestTokenCommand,
 		},
 	},
 	AgentPauseCommand,
 	{
-		Name:  "pipeline",
-		Usage: "Make changes to the pipeline of the currently running build",
+		Name:     "pipeline",
+		Category: categoryJobCommands,
+		Usage:    "Make changes to the pipeline of the currently running build",
 		Subcommands: []cli.Command{
 			PipelineUploadCommand,
 		},
 	},
 	AgentResumeCommand,
 	{
-		Name:  "secret",
-		Usage: "Interact with Pipelines Secrets",
+		Name:     "secret",
+		Category: categoryJobCommands,
+		Usage:    "Interact with Pipelines Secrets",
 		Subcommands: []cli.Command{
 			SecretGetCommand,
 		},
 	},
 	{
-		Name:  "step",
-		Usage: "Get or update an attribute of a build step, or cancel unfinished jobs for a step",
+		Name:     "step",
+		Category: categoryJobCommands,
+		Usage:    "Get or update an attribute of a build step, or cancel unfinished jobs for a step",
 		Subcommands: []cli.Command{
 			StepGetCommand,
 			StepUpdateCommand,
@@ -109,7 +125,7 @@ var BuildkiteAgentCommands = []cli.Command{
 	AgentStopCommand,
 	{
 		Name:  "tool",
-		Usage: "Utility commands, intended for users and operators of the agent to run directly on their machines, and not as part of a Buildkite job",
+		Usage: "Utilities for working with the Buildkite Agent",
 		Subcommands: []cli.Command{
 			ToolKeygenCommand,
 			ToolSignCommand,

clicommand/git_credentials_helper.go

@@ -20,8 +20,6 @@ const gitCredentialsHelperHelpDescription = `Usage:
 
 Description:
 
-[EXPERIMENTAL]
-
 Ask buildkite for credentials to use to authenticate with Github when cloning via HTTPS.
 The credentials are returned in the git-credential format.
 
@@ -45,7 +43,8 @@ type GitCredentialsHelperConfig struct {
 
 var GitCredentialsHelperCommand = cli.Command{
 	Name:        "git-credentials-helper",
-	Usage:       "Ask buildkite for credentials to use to authenticate with Github when cloning",
+	Usage:       "Internal process used by hosted compute jobs to authenticate with Github",
+	Category:    categoryInternal,
 	Description: gitCredentialsHelperHelpDescription,
 	Flags: append(globalFlags(),
 		cli.StringFlag{

clicommand/kubernetes_bootstrap.go

@@ -39,7 +39,8 @@ type KubernetesBootstrapConfig struct {
 
 var KubernetesBootstrapCommand = cli.Command{
 	Name:        "kubernetes-bootstrap",
-	Usage:       "Rebootstraps the command after connecting to the Kubernetes socket",
+	Usage:       "Harness used internally by the agent to run jobs on Kubernetes",
+	Category:    categoryInternal,
 	Description: bootstrapHelpDescription,
 	Flags: []cli.Flag{
 		KubernetesContainerIDFlag,

main.go

@@ -16,13 +16,12 @@ import (
 )
 
 const appHelpTemplate = `Usage:
-
   {{.Name}} <command> [options...]
 
-Available commands are:
-
-  {{range .Commands}}{{.Name}}{{with .ShortName}}, {{.}}{{end}}{{ "\t" }}{{.Usage}}
-  {{end}}
+Available commands are: {{range .VisibleCategories}}{{if .Name}}
+{{.Name}}:{{range .VisibleCommands}}
+  {{join .Names ", "}}{{"\t"}}{{.Usage}}{{end}}{{"\n"}}{{else}}{{range .VisibleCommands}}
+  {{join .Names ", "}}{{"\t"}}{{.Usage}}{{end}}{{"\n"}}{{end}}{{end}}
 Use "{{.Name}} <command> --help" for more information about a command.
 `
 
@@ -65,15 +64,10 @@ func main() {
 	app.Commands = clicommand.BuildkiteAgentCommands
 	app.ErrWriter = os.Stderr
 
-	// When no sub command is used
-	app.Action = func(c *cli.Context) {
-		_ = cli.ShowAppHelp(c)
-		os.Exit(1)
-	}
-
 	// When a sub command can't be found
 	app.CommandNotFound = func(c *cli.Context, command string) {
-		_ = cli.ShowAppHelp(c)
+		fmt.Fprintf(app.ErrWriter, "buildkite-agent: unknown subcommand %q\n", command)
+		fmt.Fprintf(app.ErrWriter, "Run '%s --help' for usage.\n", c.App.Name)
 		os.Exit(1)
 	}