crane: add catalog argument use annotation (#1473)

* crane: add catalog argument use annotation

* crane: catalog examples and syntex update

* Update cmd/crane/cmd/catalog.go

Co-authored-by: Jason Hall <jason@chainguard.dev>

* crane: update docs for catalog

* crane: fix doc generation with args

Co-authored-by: Jason Hall <jason@chainguard.dev>

cmd/crane/cmd/catalog.go

@@ -16,17 +16,28 @@ package cmd
 
 import (
 	"fmt"
+	"os"
+	"strings"
 
 	"github.com/google/go-containerregistry/pkg/crane"
 	"github.com/spf13/cobra"
 )
 
 // NewCmdCatalog creates a new cobra.Command for the repos subcommand.
-func NewCmdCatalog(options *[]crane.Option) *cobra.Command {
+func NewCmdCatalog(options *[]crane.Option, argv ...string) *cobra.Command {
+	if len(argv) == 0 {
+		argv = []string{os.Args[0]}
+	}
+
+	baseCmd := strings.Join(argv, " ")
+	eg := fmt.Sprintf(`  # list the repos for reg.example.com
+  $ %s catalog reg.example.com`, baseCmd)
+
 	return &cobra.Command{
-		Use:   "catalog",
-		Short: "List the repos in a registry",
-		Args:  cobra.ExactArgs(1),
+		Use:     "catalog [REGISTRY]",
+		Short:   "List the repos in a registry",
+		Example: eg,
+		Args:    cobra.ExactArgs(1),
 		RunE: func(_ *cobra.Command, args []string) error {
 			reg := args[0]
 			repos, err := crane.Catalog(reg, *options...)

cmd/crane/cmd/root.go

@@ -96,7 +96,7 @@ func New(use, short string, options []crane.Option) *cobra.Command {
 		NewCmdAppend(&options),
 		NewCmdAuth(options, "crane", "auth"),
 		NewCmdBlob(&options),
-		NewCmdCatalog(&options),
+		NewCmdCatalog(&options, "crane"),
 		NewCmdConfig(&options),
 		NewCmdCopy(&options),
 		NewCmdDelete(&options),