Update CLI wording (bufbuild#901)

private/buf/cmd/buf/buf.go

@@ -115,6 +115,8 @@ func NewRootCommand(name string) *appcmd.Command {
 	globalFlags := bufcli.NewGlobalFlags()
 	return &appcmd.Command{
 		Use:                 name,
+		Short:               "The Buf CLI",
+		Long:                "A tool for working with Protocol Buffers and managing resources on the Buf Schema Registry (BSR).",
 		Version:             bufcli.Version,
 		BindPersistentFlags: appcmd.BindMultiple(builder.BindRoot, globalFlags.BindRoot),
 		SubCommands: []*appcmd.Command{
@@ -128,7 +130,7 @@ func NewRootCommand(name string) *appcmd.Command {
 			push.NewCommand("push", builder),
 			{
 				Use:   "mod",
-				Short: "Configure and update buf modules.",
+				Short: "Manage Buf modules.",
 				SubCommands: []*appcmd.Command{
 					appcmd.NewDeletedCommand("init", modInitDeprecationMessage),
 					modprune.NewCommand("prune", builder),
@@ -139,7 +141,7 @@ func NewRootCommand(name string) *appcmd.Command {
 			},
 			{
 				Use:   "config",
-				Short: "Interact with the configuration of Buf.",
+				Short: "Manage Buf module configuration.",
 				SubCommands: []*appcmd.Command{
 					configinit.NewCommand("init", builder),
 					configlslintrules.NewCommand("ls-lint-rules", builder),
@@ -149,23 +151,23 @@ func NewRootCommand(name string) *appcmd.Command {
 			},
 			{
 				Use:   "registry",
-				Short: "Interact with the Buf Schema Registry.",
+				Short: "Manage assets on the Buf Schema Registry.",
 				SubCommands: []*appcmd.Command{
 					registrylogin.NewCommand("login", builder),
 					registrylogout.NewCommand("logout", builder),
 				},
 			},
 			{
 				Use:   "beta",
-				Short: "Beta commands. Unstable and will likely change.",
+				Short: "Beta commands. Unstable and likely to change.",
 				SubCommands: []*appcmd.Command{
 					{
 						Use:   "registry",
-						Short: "Interact with the Buf Schema Registry.",
+						Short: "Manage assets on the Buf Schema Registry.",
 						SubCommands: []*appcmd.Command{
 							{
 								Use:   "organization",
-								Short: "Organization commands.",
+								Short: "Manage organizations.",
 								SubCommands: []*appcmd.Command{
 									organizationcreate.NewCommand("create", builder),
 									organizationget.NewCommand("get", builder),
@@ -174,7 +176,7 @@ func NewRootCommand(name string) *appcmd.Command {
 							},
 							{
 								Use:   "repository",
-								Short: "Repository commands.",
+								Short: "Manage repositories.",
 								SubCommands: []*appcmd.Command{
 									repositorycreate.NewCommand("create", builder),
 									repositoryget.NewCommand("get", builder),
@@ -186,31 +188,31 @@ func NewRootCommand(name string) *appcmd.Command {
 							},
 							{
 								Use:   "track",
-								Short: "Repository track commands.",
+								Short: "Manage a repository's tracks.",
 								SubCommands: []*appcmd.Command{
 									tracklist.NewCommand("list", builder),
 									trackdelete.NewCommand("delete", builder),
 								},
 							},
 							{
 								Use:   "tag",
-								Short: "Repository tag commands.",
+								Short: "Manage a repository's tags.",
 								SubCommands: []*appcmd.Command{
 									tagcreate.NewCommand("create", builder),
 									taglist.NewCommand("list", builder),
 								},
 							},
 							{
 								Use:   "commit",
-								Short: "Repository commit commands.",
+								Short: "Manage a repository's commits.",
 								SubCommands: []*appcmd.Command{
 									commitget.NewCommand("get", builder),
 									commitlist.NewCommand("list", builder),
 								},
 							},
 							{
 								Use:   "plugin",
-								Short: "Plugin commands.",
+								Short: "Manage Protobuf plugins.",
 								SubCommands: []*appcmd.Command{
 									plugincreate.NewCommand("create", builder),
 									pluginlist.NewCommand("list", builder),
@@ -219,7 +221,7 @@ func NewRootCommand(name string) *appcmd.Command {
 									pluginundeprecate.NewCommand("undeprecate", builder),
 									{
 										Use:   "version",
-										Short: "Plugin version commands.",
+										Short: "Manage Protobuf plugin versions.",
 										SubCommands: []*appcmd.Command{
 											pluginversionlist.NewCommand("list", builder),
 										},
@@ -228,7 +230,7 @@ func NewRootCommand(name string) *appcmd.Command {
 							},
 							{
 								Use:   "template",
-								Short: "Template commands.",
+								Short: "Manage Protobuf templates on the Buf Schema Registry.",
 								SubCommands: []*appcmd.Command{
 									templatecreate.NewCommand("create", builder),
 									templatelist.NewCommand("list", builder),
@@ -237,7 +239,7 @@ func NewRootCommand(name string) *appcmd.Command {
 									templateundeprecate.NewCommand("undeprecate", builder),
 									{
 										Use:   "version",
-										Short: "Template version commands.",
+										Short: "Manage Protobuf template versions.",
 										SubCommands: []*appcmd.Command{
 											templateversioncreate.NewCommand("create", builder),
 											templateversionlist.NewCommand("list", builder),
@@ -249,7 +251,7 @@ func NewRootCommand(name string) *appcmd.Command {
 					},
 					{
 						Use:        "config",
-						Short:      "Interact with the configuration of Buf.",
+						Short:      "Manage Buf module configuration.",
 						Deprecated: betaConfigDeprecationMessage,
 						Hidden:     true,
 						SubCommands: []*appcmd.Command{
@@ -258,7 +260,7 @@ func NewRootCommand(name string) *appcmd.Command {
 					},
 					{
 						Use:        "image",
-						Short:      "Work with Images and FileDescriptorSets.",
+						Short:      "Manage Images and FileDescriptorSets.",
 						Deprecated: imageDeprecationMessage,
 						Hidden:     true,
 						SubCommands: []*appcmd.Command{
@@ -267,7 +269,7 @@ func NewRootCommand(name string) *appcmd.Command {
 					},
 					{
 						Use:        "mod",
-						Short:      "Configure and update buf modules.",
+						Short:      "Manage Buf modules.",
 						Deprecated: betaModDeprecationMessage,
 						Hidden:     true,
 						SubCommands: []*appcmd.Command{
@@ -282,16 +284,16 @@ func NewRootCommand(name string) *appcmd.Command {
 			},
 			{
 				Use:    "alpha",
-				Short:  "Alpha commands. These are so early in development that they should not be used except in development.",
+				Short:  "Alpha commands. Unstable and recommended only for experimentation.",
 				Hidden: true,
 				SubCommands: []*appcmd.Command{
 					{
 						Use:   "registry",
-						Short: "Interact with the Buf Schema Registry.",
+						Short: "Manage assets on the Buf Schema Registry.",
 						SubCommands: []*appcmd.Command{
 							{
 								Use:   "token",
-								Short: "Token commands.",
+								Short: "Manage user tokens.",
 								SubCommands: []*appcmd.Command{
 									tokencreate.NewCommand("create", builder),
 									tokenget.NewCommand("get", builder),
@@ -308,7 +310,7 @@ func NewRootCommand(name string) *appcmd.Command {
 			appcmd.NewDeletedCommand("push", pushDeprecationMessage),
 			{
 				Use:        "image",
-				Short:      "Work with Images and FileDescriptorSets.",
+				Short:      "Manage Images and FileDescriptorSets.",
 				Deprecated: imageDeprecationMessage,
 				Hidden:     true,
 				SubCommands: []*appcmd.Command{
@@ -317,7 +319,7 @@ func NewRootCommand(name string) *appcmd.Command {
 			},
 			{
 				Use:        "check",
-				Short:      "Run linting or breaking change detection.",
+				Short:      "Run linting or breaking change detection against Buf modules.",
 				Deprecated: checkDeprecationMessage,
 				Hidden:     true,
 				SubCommands: []*appcmd.Command{
@@ -329,13 +331,13 @@ func NewRootCommand(name string) *appcmd.Command {
 			},
 			{
 				Use:        "experimental",
-				Short:      "Experimental commands. Unstable and will likely change.",
+				Short:      "Experimental commands. Unstable and likely to change.",
 				Deprecated: experimentalDeprecationMessage,
 				Hidden:     true,
 				SubCommands: []*appcmd.Command{
 					{
 						Use:        "image",
-						Short:      "Work with Images and FileDescriptorSets.",
+						Short:      "Manage Images and FileDescriptorSets.",
 						Deprecated: imageDeprecationMessage,
 						Hidden:     true,
 						SubCommands: []*appcmd.Command{

private/buf/cmd/buf/command/alpha/registry/token/tokencreate/tokencreate.go

@@ -73,7 +73,7 @@ func (f *flags) Bind(flagSet *pflag.FlagSet) {
 		&f.TimeToLive,
 		timeToLiveFlagName,
 		24*30*time.Hour,
-		`How long the token should live for. Set to 0 for no expiry.`,
+		`How long the token should live. Set to 0 for no expiry.`,
 	)
 }
 
@@ -85,7 +85,7 @@ func run(
 	bufcli.WarnAlphaCommand(ctx, container)
 	remote := container.Arg(0)
 	if remote == "" {
-		return appcmd.NewInvalidArgumentError("a module remote must be specified")
+		return appcmd.NewInvalidArgumentError("you must specify a remote module")
 	}
 	var expireTime *timestamppb.Timestamp
 	var err error

private/buf/cmd/buf/command/alpha/registry/token/tokendelete/tokendelete.go

@@ -83,7 +83,7 @@ func run(
 	bufcli.WarnAlphaCommand(ctx, container)
 	remote := container.Arg(0)
 	if remote == "" {
-		return appcmd.NewInvalidArgumentError("a module remote must be specified")
+		return appcmd.NewInvalidArgumentError("you must specify a remote module")
 	}
 	registryProvider, err := bufcli.NewRegistryProvider(ctx, container)
 	if err != nil {

private/buf/cmd/buf/command/alpha/registry/token/tokenget/tokenget.go

@@ -85,7 +85,7 @@ func run(
 	bufcli.WarnAlphaCommand(ctx, container)
 	remote := container.Arg(0)
 	if remote == "" {
-		return appcmd.NewInvalidArgumentError("a module remote must be specified")
+		return appcmd.NewInvalidArgumentError("you must specify a remote module")
 	}
 	format, err := bufprint.ParseFormat(flags.Format)
 	if err != nil {

private/buf/cmd/buf/command/alpha/registry/token/tokenlist/tokenlist.go

@@ -73,7 +73,7 @@ func (f *flags) Bind(flagSet *pflag.FlagSet) {
 	flagSet.StringVar(&f.PageToken,
 		pageTokenFlagName,
 		"",
-		`The page token. If more results are available, a "next_page" key will be present in the --format=json output.`,
+		`The page token. If more results are available, a "next_page" key is present in the --format=json output.`,
 	)
 	flagSet.BoolVar(&f.Reverse,
 		reverseFlagName,
@@ -96,7 +96,7 @@ func run(
 	bufcli.WarnAlphaCommand(ctx, container)
 	remote := container.Arg(0)
 	if remote == "" {
-		return appcmd.NewInvalidArgumentError("a module remote must be specified")
+		return appcmd.NewInvalidArgumentError("you must specify a remote module")
 	}
 	format, err := bufprint.ParseFormat(flags.Format)
 	if err != nil {

private/buf/cmd/buf/command/beta/registry/branch/branchcreate/branchcreate.go

@@ -42,7 +42,7 @@ func NewCommand(
 	flags := newFlags()
 	return &appcmd.Command{
 		Use:   name + " <buf.build/owner/repository:branch>",
-		Short: "Create a branch for the specified repository.",
+		Short: "Creates a branch for the specified repository.",
 		Args:  cobra.ExactArgs(1),
 		Run: builder.NewRunFunc(
 			func(ctx context.Context, container appflag.Container) error {

private/buf/cmd/buf/command/beta/registry/commit/commitget/commitget.go

@@ -38,7 +38,7 @@ func NewCommand(
 	flags := newFlags()
 	return &appcmd.Command{
 		Use:   name + " <buf.build/owner/repo:ref>",
-		Short: "Get commit details",
+		Short: "Get details about a commit.",
 		Args:  cobra.ExactArgs(1),
 		Run: builder.NewRunFunc(
 			func(ctx context.Context, container appflag.Container) error {

private/buf/cmd/buf/command/beta/registry/commit/commitlist/commitlist.go

@@ -43,7 +43,7 @@ func NewCommand(
 	flags := newFlags()
 	return &appcmd.Command{
 		Use:   name + " <buf.build/owner/repo[:ref]>",
-		Short: "List commit details",
+		Short: "List commits.",
 		Args:  cobra.ExactArgs(1),
 		Run: builder.NewRunFunc(
 			func(ctx context.Context, container appflag.Container) error {
@@ -75,7 +75,7 @@ func (f *flags) Bind(flagSet *pflag.FlagSet) {
 	flagSet.StringVar(&f.PageToken,
 		pageTokenFlagName,
 		"",
-		`The page token. If more results are available, a "next_page" key will be present in the --format=json output.`,
+		`The page token. If more results are available, a "next_page" key is present in the --format=json output.`,
 	)
 	flagSet.BoolVar(&f.Reverse,
 		reverseFlagName,

private/buf/cmd/buf/command/beta/registry/organization/organizationcreate/organizationcreate.go

@@ -38,7 +38,7 @@ func NewCommand(
 	flags := newFlags()
 	return &appcmd.Command{
 		Use:   name + " <buf.build/organization>",
-		Short: "Create a new organization.",
+		Short: "Create a new organization on the BSR.",
 		Args:  cobra.ExactArgs(1),
 		Run: builder.NewRunFunc(
 			func(ctx context.Context, container appflag.Container) error {

private/buf/cmd/buf/command/beta/registry/organization/organizationdelete/organizationdelete.go

@@ -37,7 +37,7 @@ func NewCommand(
 	flags := newFlags()
 	return &appcmd.Command{
 		Use:   name + " <buf.build/organization>",
-		Short: "Delete an organization by name.",
+		Short: "Delete an organization by name on the BSR.",
 		Args:  cobra.ExactArgs(1),
 		Run: builder.NewRunFunc(
 			func(ctx context.Context, container appflag.Container) error {

private/buf/cmd/buf/command/beta/registry/organization/organizationget/organizationget.go

@@ -38,7 +38,7 @@ func NewCommand(
 	flags := newFlags()
 	return &appcmd.Command{
 		Use:   name + " <buf.build/organization>",
-		Short: "Get an organization by name.",
+		Short: "Get an organization on the BSR by name.",
 		Args:  cobra.ExactArgs(1),
 		Run: builder.NewRunFunc(
 			func(ctx context.Context, container appflag.Container) error {

private/buf/cmd/buf/command/beta/registry/plugin/plugincreate/plugincreate.go

@@ -50,7 +50,7 @@ func NewCommand(
 	flags := newFlags()
 	return &appcmd.Command{
 		Use:   name + " <buf.build/owner/" + bufplugin.PluginsPathName + "/plugin>",
-		Short: "Create a new plugin.",
+		Short: "Create a new Protobuf plugin.",
 		Args:  cobra.ExactArgs(1),
 		Run: builder.NewRunFunc(
 			func(ctx context.Context, container appflag.Container) error {

private/buf/cmd/buf/command/beta/registry/plugin/plugindelete/plugindelete.go

@@ -38,7 +38,7 @@ func NewCommand(
 	flags := newFlags()
 	return &appcmd.Command{
 		Use:   name + " <buf.build/owner/" + internal.PluginsPathName + "/plugin>",
-		Short: "Delete a plugin by name.",
+		Short: "Delete a Protobuf plugin by name.",
 		Args:  cobra.ExactArgs(1),
 		Run: builder.NewRunFunc(
 			func(ctx context.Context, container appflag.Container) error {
@@ -75,7 +75,7 @@ func run(
 	bufcli.WarnBetaCommand(ctx, container)
 	pluginPath := container.Arg(0)
 	if pluginPath == "" {
-		return appcmd.NewInvalidArgumentError("a plugin path must be specified")
+		return appcmd.NewInvalidArgumentError("you must specify a plugin path")
 	}
 	registryProvider, err := bufcli.NewRegistryProvider(ctx, container)
 	if err != nil {

private/buf/cmd/buf/command/beta/registry/plugin/plugindeprecate/plugindeprecate.go

@@ -63,7 +63,7 @@ func (f *flags) Bind(flagSet *pflag.FlagSet) {
 		&f.Message,
 		messageFlagName,
 		"",
-		`The deprecation message to display with deprecation warnings.`,
+		`The message to display with deprecation warnings.`,
 	)
 }
 
@@ -75,7 +75,7 @@ func run(
 	bufcli.WarnBetaCommand(ctx, container)
 	pluginPath := container.Arg(0)
 	if pluginPath == "" {
-		return appcmd.NewInvalidArgumentError("a plugin path must be specified")
+		return appcmd.NewInvalidArgumentError("you must specify a plugin path")
 	}
 	registryProvider, err := bufcli.NewRegistryProvider(ctx, container)
 	if err != nil {

private/buf/cmd/buf/command/beta/registry/plugin/pluginlist/pluginlist.go

@@ -73,7 +73,7 @@ func (f *flags) Bind(flagSet *pflag.FlagSet) {
 	flagSet.StringVar(&f.PageToken,
 		pageTokenFlagName,
 		"",
-		`The page token. If more results are available, a "next_page" key will be present in the --format=json output.`,
+		`The page token. If more results are available, a "next_page" key is present in the --format=json output.`,
 	)
 	flagSet.BoolVar(&f.Reverse,
 		reverseFlagName,
@@ -96,7 +96,7 @@ func run(
 	bufcli.WarnBetaCommand(ctx, container)
 	remote := container.Arg(0)
 	if remote == "" {
-		return appcmd.NewInvalidArgumentError("a remote must be specified")
+		return appcmd.NewInvalidArgumentError("you must specify a remote")
 	}
 	format, err := bufprint.ParseFormat(flags.Format)
 	if err != nil {

private/buf/cmd/buf/command/beta/registry/plugin/pluginundeprecate/pluginundeprecate.go

@@ -45,7 +45,7 @@ func run(
 	bufcli.WarnBetaCommand(ctx, container)
 	pluginPath := container.Arg(0)
 	if pluginPath == "" {
-		return appcmd.NewInvalidArgumentError("a plugin path must be specified")
+		return appcmd.NewInvalidArgumentError("you must specify a plugin path")
 	}
 	registryProvider, err := bufcli.NewRegistryProvider(ctx, container)
 	if err != nil {