chore(cmd): surface key verbs in top-level command descriptions

pkg/cmd/application/application.go

@@ -18,7 +18,7 @@ func NewApplicationCmd(f *cmdutil.Factory) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:     "application",
 		Aliases: []string{"app"},
-		Short:   "Manage your Algolia applications",
+		Short:   "Create, select, and manage your Algolia applications",
 	}
 
 	cmd.AddCommand(create.NewCreateCmd(f))

pkg/cmd/describe/describe.go

@@ -37,7 +37,7 @@ func NewDescribeCmd(f *cmdutil.Factory) *cobra.Command {
 		Use:     "describe [command] [subcommand]...",
 		Aliases: []string{"schema"},
 		Args:    cobra.ArbitraryArgs,
-		Short:   "Describe commands and flags as JSON.",
+		Short:   "Print the full command and flag tree as JSON, for scripting and discovery",
 		// Describe only walks the command tree; it needs no credentials and
 		// must work on a machine with nothing configured.
 		Annotations: map[string]string{
@@ -46,6 +46,9 @@ func NewDescribeCmd(f *cmdutil.Factory) *cobra.Command {
 		Long: heredoc.Doc(`
 			Describe the CLI's command tree in a machine-readable format.
 			With no arguments, this command describes the root command.
+
+			Use it to discover every command, subcommand, and flag without
+			crawling the --help pages one by one.
 		`),
 		Example: heredoc.Doc(`
 			# Describe the root command
@@ -56,6 +59,9 @@ func NewDescribeCmd(f *cmdutil.Factory) *cobra.Command {
 
 			# Describe the objects browse command
 			$ algolia describe objects browse
+
+			# List every top-level command
+			$ algolia describe | jq '.command.subCommands[].name'
 		`),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			opts.CommandPath = args

pkg/cmd/indices/index.go

@@ -18,7 +18,7 @@ func NewIndicesCmd(f *cmdutil.Factory) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:     "indices",
 		Aliases: []string{"index"},
-		Short:   "Manage your Algolia indices",
+		Short:   "List, copy, move, clear, and delete indices",
 	}
 
 	cmd.AddCommand(list.NewListCmd(f))

pkg/cmd/objects/objects.go

@@ -15,7 +15,7 @@ import (
 func NewObjectsCmd(f *cmdutil.Factory) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:     "objects",
-		Short:   "Add, update, and delete records",
+		Short:   "Import, browse, add, update, and delete records",
 		Aliases: []string{"records"},
 	}
 

pkg/cmd/root/root.go

@@ -65,6 +65,7 @@ func NewRootCmd(f *cmdutil.Factory) *cobra.Command {
 		SilenceUsage:  true,
 		SilenceErrors: true,
 		Example: heredoc.Doc(`
+			$ algolia auth login
 			$ algolia search MOVIES --query "toy story"
 			$ algolia objects browse MOVIES
 			$ algolia apikeys create --acl search

pkg/cmd/settings/settings.go

@@ -13,7 +13,7 @@ import (
 func NewSettingsCmd(f *cmdutil.Factory) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "settings",
-		Short: "Manage your Algolia index settings.",
+		Short: "Manage your Algolia index settings",
 	}
 
 	cmd.AddCommand(get.NewGetCmd(f))