Improve help and positional arg enforcement in most commands

Chosen approach explained in spf13/cobra#571 (comment)

Didn't touch the generic REST commands such as `get`, `delete` etc
as I'm confused by them both using `urls.Expand()` to support
`get URL` & `get KIND ID` forms, as well as having some Cobra sub-commands.

cmd/ocm/account/orgs/cmd.go

@@ -42,6 +42,7 @@ var Cmd = &cobra.Command{
 	Use:   "orgs",
 	Short: "List organizations.",
 	Long:  "Display a list of organizations.",
+	Args:  cobra.NoArgs,
 	RunE:  run,
 }
 

cmd/ocm/account/quota/cmd.go

@@ -37,6 +37,7 @@ var Cmd = &cobra.Command{
 	Use:   "quota",
 	Short: "Retrieve cluster quota information.",
 	Long:  "Retrieve cluster quota information of a specific organization.",
+	Args:  cobra.NoArgs,
 	RunE:  run,
 }
 

cmd/ocm/account/roles/cmd.go

@@ -32,10 +32,16 @@ var args struct {
 }
 
 var Cmd = &cobra.Command{
-	Use:   "roles [role-name]",
+	Use:   "roles [flags] [ROLE_NAME]",
 	Short: "Retrieve information of the different roles",
-	Long:  "Get description of a role or list of all roles ",
-	RunE:  run,
+	Long:  "Get description of a role or list of all roles",
+	Args: func(cmd *cobra.Command, args []string) error {
+		if len(args) > 1 {
+			return fmt.Errorf("Accepts at most 1 role name")
+		}
+		return nil
+	},
+	RunE: run,
 }
 
 func init() {

cmd/ocm/account/status/cmd.go

@@ -35,6 +35,7 @@ var Cmd = &cobra.Command{
 	Use:   "status",
 	Short: "Status of current user.",
 	Long:  "Display status of current user.",
+	Args:  cobra.NoArgs,
 	RunE:  run,
 }
 

cmd/ocm/account/users/cmd.go

@@ -39,6 +39,7 @@ var Cmd = &cobra.Command{
 	Use:   "users",
 	Short: "Retrieve users and their roles",
 	Long:  "Retrieve information of all users/roles in the same organization",
+	Args:  cobra.NoArgs,
 	RunE:  run,
 }
 

cmd/ocm/cluster/create/create.go

@@ -43,7 +43,7 @@ var args struct {
 
 // Cmd Constant:
 var Cmd = &cobra.Command{
-	Use:        "create [flags] <cluster name>",
+	Use:        "create [flags] CLUSTER_NAME",
 	Short:      "Create managed clusters",
 	Long:       "Create managed OpenShift Dedicated v4 clusters via OCM",
 	Deprecated: "please use `ocm create cluster` command",

cmd/ocm/cluster/describe/describe.go

@@ -36,7 +36,7 @@ var args struct {
 }
 
 var Cmd = &cobra.Command{
-	Use:        "describe NAME|ID|EXTERNAL_ID [--output] [--short]",
+	Use:        "describe [flags] {NAME|ID|EXTERNAL_ID}",
 	Short:      "Describe a cluster",
 	Long:       "Get info about a cluster identified by name, identifier or external identifier",
 	Deprecated: "please use `ocm describe cluster` command",

cmd/ocm/cluster/list/list.go

@@ -44,9 +44,9 @@ var args struct {
 
 // Cmd Constant:
 var Cmd = &cobra.Command{
-	Use:        "list [flags] [partial cluster ID or name]",
+	Use:        "list [flags] [PARTIAL_CLUSTER_ID_OR_NAME]",
 	Short:      "List clusters",
-	Long:       "List clusters by ID and Name",
+	Long:       "List clusters, optionally filtering by substring of ID or Name",
 	Deprecated: "please use `ocm list clusters` command",
 	Args:       cobra.RangeArgs(0, 1),
 	RunE:       run,

cmd/ocm/cluster/login/login.go

@@ -35,14 +35,14 @@ var args struct {
 }
 
 var Cmd = &cobra.Command{
-	Use:   "login [CLUSTERID|CLUSTER_NAME|CLUSTER_NAME_SEARCH]",
+	Use:   "login [flags] {CLUSTER_ID|CLUSTER_NAME|CLUSTER_NAME_SEARCH}",
 	Short: "login to a cluster",
 	Long: "login to a cluster by ID or Name or cluster name search string according to the api: " +
 		"https://api.openshift.com/#/clusters/get_api_clusters_mgmt_v1_clusters",
 	Example: " ocm cluster login <id>\n ocm cluster login %test%",
 	RunE:    run,
 	Args: func(cmd *cobra.Command, args []string) error {
-		if len(args) < 1 {
+		if len(args) != 1 {
 			return fmt.Errorf("cluster name expected")
 		}
 

cmd/ocm/cluster/status/status.go

@@ -24,7 +24,7 @@ import (
 )
 
 var Cmd = &cobra.Command{
-	Use:   "status CLUSTERID",
+	Use:   "status [flags] CLUSTER_ID",
 	Short: "Status of a cluster",
 	Long:  "Get the status of a cluster identified by its cluster ID",
 	RunE:  run,
@@ -33,7 +33,7 @@ var Cmd = &cobra.Command{
 func run(cmd *cobra.Command, argv []string) error {
 
 	if len(argv) != 1 {
-		return fmt.Errorf("Expected exactly one cluster")
+		return fmt.Errorf("Expected exactly one cluster id")
 	}
 
 	// Create the client for the OCM API:

cmd/ocm/cluster/versions/versions.go

@@ -31,15 +31,11 @@ var Cmd = &cobra.Command{
 	Short:      "List available versions",
 	Long:       "List the versions available for provisioning a cluster",
 	Deprecated: "please use `ocm list versions` command",
+	Args:       cobra.NoArgs,
 	RunE:       run,
 }
 
 func run(cmd *cobra.Command, argv []string) error {
-
-	if len(argv) != 0 {
-		return fmt.Errorf("Expected no arguments")
-	}
-
 	// Create the client for the OCM API:
 	connection, err := ocm.NewConnection().Build()
 	if err != nil {

cmd/ocm/completion/cmd.go

@@ -35,6 +35,7 @@ To configure your bash shell to load completions for each session add to your ba
 # ~/.bashrc or ~/.profile
 . <(ocm completion)
 `,
+	Args: cobra.NoArgs,
 	RunE: run,
 }
 

cmd/ocm/config/cmd.go

@@ -56,7 +56,11 @@ or ~/.ocm.json if that variable is unset. Currently using: %s
 
 The following variables are supported:
 
-%s`, loc, configVarDocs())
+%s
+
+Note that "ocm config get access_token" gives whatever the file contains - may be missing or expired;
+you probably want "ocm token" command instead which will obtain a fresh token if needed.
+`, loc, configVarDocs())
 	return
 }
 

cmd/ocm/config/get/get.go

@@ -30,10 +30,10 @@ var args struct {
 }
 
 var Cmd = &cobra.Command{
-	Use:   "get VARIABLE",
+	Use:   "get [flags] VARIABLE",
 	Short: "Prints the value of a config variable",
 	Long:  "Prints the value of a config variable. See 'ocm config --help' for supported config variables.",
-	Args:  cobra.MinimumNArgs(1),
+	Args:  cobra.ExactArgs(1),
 	RunE:  run,
 }
 
@@ -76,7 +76,7 @@ func run(cmd *cobra.Command, argv []string) error {
 	case "url":
 		fmt.Fprintf(os.Stdout, "%s\n", cfg.URL)
 	default:
-		fmt.Fprintf(os.Stderr, "Uknown setting\n")
+		return fmt.Errorf("Unknown setting")
 	}
 
 	return nil

cmd/ocm/config/set/set.go

@@ -30,10 +30,10 @@ var args struct {
 }
 
 var Cmd = &cobra.Command{
-	Use:   "set VARIABLE VALUE",
+	Use:   "set [flags] VARIABLE VALUE",
 	Short: "Sets the variable's value",
 	Long:  "Sets the value of a config variable. See 'ocm config --help' for supported config variables.",
-	Args:  cobra.MinimumNArgs(2),
+	Args:  cobra.ExactArgs(2),
 	RunE:  run,
 }
 

cmd/ocm/create/cluster/cmd.go

@@ -59,11 +59,12 @@ var args struct {
 
 // Cmd Constant:
 var Cmd = &cobra.Command{
-	Use:   "cluster",
+	Use:   "cluster [flags] NAME",
 	Short: "Create managed clusters",
-	Long:  "Create managed OpenShift Dedicated v4 clusters via OCM",
-	Args:  cobra.ExactArgs(1),
-	RunE:  run,
+	Long: "Create managed OpenShift Dedicated v4 clusters via OCM.\n" +
+		"\n" +
+		"The specified name is used as a DNS component, as well as initial display_name.",
+	RunE: run,
 }
 
 func init() {

cmd/ocm/create/cmd.go

@@ -23,7 +23,7 @@ import (
 )
 
 var Cmd = &cobra.Command{
-	Use:     "create RESOURCE [flags]",
+	Use:     "create [flags] RESOURCE",
 	Aliases: []string{"add"},
 	Short:   "Create a resource from stdin",
 	Long:    "Create a resource from stdin",

cmd/ocm/create/idp/cmd.go

@@ -62,13 +62,14 @@ var args struct {
 var validIdps = []string{"github", "google", "ldap", "openid"}
 
 var Cmd = &cobra.Command{
-	Use:   "idp",
+	Use:   "idp --cluster={NAME|ID|EXTERNAL_ID}",
 	Short: "Add IDP for cluster",
 	Long:  "Add an Identity providers to determine how users log into the cluster.",
 	Example: `  # Add a GitHub identity provider to a cluster named "mycluster"
   ocm create idp --type=github --cluster=mycluster
   # Add an identity provider following interactive prompts
   ocm create idp --cluster=mycluster`,
+	Args: cobra.NoArgs,
 	RunE: run,
 }
 

cmd/ocm/create/ingress/cmd.go

@@ -30,7 +30,7 @@ var args struct {
 }
 
 var Cmd = &cobra.Command{
-	Use:     "ingress",
+	Use:     "ingress --cluster={NAME|ID|EXTERNAL_ID}",
 	Aliases: []string{"route", "routes", "ingresses"},
 	Short:   "Add Ingress to cluster",
 	Long:    "Add an Ingress endpoint to determine API access to the cluster.",
@@ -40,6 +40,7 @@ var Cmd = &cobra.Command{
   ocm create ingress --cluster=mycluster
   # Add an ingress with route selector label match
   ocm create ingress -c mycluster --label-match="foo=bar,bar=baz"`,
+	Args: cobra.NoArgs,
 	RunE: run,
 }
 

cmd/ocm/create/machinepool/cmd.go

@@ -31,7 +31,7 @@ var args struct {
 }
 
 var Cmd = &cobra.Command{
-	Use:     "machinepool",
+	Use:     "machinepool --cluster={NAME|ID|EXTERNAL_ID} --replicas=N [flags] MACHINE_POOL_ID",
 	Aliases: []string{"machinepools", "machine-pool", "machine-pools"},
 	Short:   "Add machine pool to cluster",
 	Long:    "Add a machine pool to the cluster.",

cmd/ocm/create/user/cmd.go

@@ -30,11 +30,11 @@ var args struct {
 }
 
 var Cmd = &cobra.Command{
-	Use:     "user",
+	Use:     "user --cluster={NAME|ID|EXTERNAL_ID} --group=GROUP_ID [flags] USERS",
 	Aliases: []string{"users"},
 	Short:   "Configure user access for cluster",
-	Long:    "Configure user access for cluster",
-	Example: `# Add users to the dedicated-admins group
+	Long:    "Add users (comma-separated) to a priviledged group on a cluster.",
+	Example: `  # Add users to the dedicated-admins group
   ocm create user user1,user2 --cluster=mycluster --group=dedicated-admins`,
 	RunE: run,
 }
@@ -56,7 +56,7 @@ func init() {
 		&args.group,
 		"group",
 		"",
-		"Group name to add the users to.",
+		"Group name to add the users to (required).",
 	)
 	//nolint:gosec
 	Cmd.MarkFlagRequired("group")

cmd/ocm/delete/cmd.go

@@ -39,7 +39,7 @@ var args struct {
 }
 
 var Cmd = &cobra.Command{
-	Use:       "delete PATH",
+	Use:       "delete [flags] PATH",
 	Short:     "Send a DELETE request",
 	Long:      "Send a DELETE request to the given path.",
 	RunE:      run,

cmd/ocm/delete/idp/cmd.go

@@ -28,7 +28,7 @@ var args struct {
 }
 
 var Cmd = &cobra.Command{
-	Use:     "idp [IDP NAME]",
+	Use:     "idp --cluster={NAME|ID|EXTERNAL_ID} [flags] IDP_NAME",
 	Aliases: []string{"idps"},
 	Short:   "Delete cluster IDPs",
 	Long:    "Delete a specific identity provider for a cluster.",

cmd/ocm/delete/ingress/cmd.go

@@ -30,7 +30,7 @@ var args struct {
 }
 
 var Cmd = &cobra.Command{
-	Use:     "ingress",
+	Use:     "ingress --cluster={NAME|ID|EXTERNAL_ID} [flags] INGRESS_ID",
 	Aliases: []string{"ingresses", "route", "routes"},
 	Short:   "Delete cluster ingress",
 	Long:    "Delete the additional non-default application router for a cluster.",

cmd/ocm/delete/machinepool/cmd.go

@@ -27,7 +27,7 @@ var args struct {
 }
 
 var Cmd = &cobra.Command{
-	Use:     "machinepool",
+	Use:     "machinepool --cluster={NAME|ID|EXTERNAL_ID} [flags] MACHINE_POOL_ID",
 	Aliases: []string{"machine-pool", "machinepools", "machine-pools"},
 	Short:   "Delete cluster machine pool",
 	Long:    "Delete the additional machine pool of a cluster.",

cmd/ocm/delete/user/cmd.go

@@ -28,10 +28,10 @@ var args struct {
 }
 
 var Cmd = &cobra.Command{
-	Use:     "user",
+	Use:     "user --cluster={NAME|ID|EXTERNAL_ID} --group=GROUP_ID [flags] USER1",
 	Aliases: []string{"users"},
 	Short:   "Remove user access from cluster",
-	Long:    "Remove user access from cluster",
+	Long:    "Remove a user from a priviledged group on a cluster.",
 	Example: `# Delete users from the dedicated-admins group
   ocm delete user user1 --cluster=mycluster --group=dedicated-admins`,
 	RunE: run,

cmd/ocm/describe/cluster/cmd.go

@@ -36,7 +36,7 @@ var args struct {
 }
 
 var Cmd = &cobra.Command{
-	Use:   "cluster NAME|ID|EXTERNAL_ID",
+	Use:   "cluster [flags] {NAME|ID|EXTERNAL_ID}",
 	Short: "Show details of a cluster",
 	Long:  "Show details of a cluster identified by name, identifier or external identifier",
 	RunE:  run,

cmd/ocm/describe/cmd.go

@@ -19,7 +19,7 @@ import (
 )
 
 var Cmd = &cobra.Command{
-	Use:   "describe RESOURCE [flags]",
+	Use:   "describe [flags] RESOURCE",
 	Short: "Show details of a specific resource",
 	Long:  "Show details of a specific resource",
 }

cmd/ocm/edit/cluster/cmd.go

@@ -38,11 +38,12 @@ var args struct {
 }
 
 var Cmd = &cobra.Command{
-	Use:   "cluster",
+	Use:   "cluster --cluster={NAME|ID|EXTERNAL_ID}",
 	Short: "Edit cluster",
 	Long:  "Edit cluster.",
 	Example: `  # Edit a cluster named "mycluster" to make it private
   ocm edit cluster mycluster --private`,
+	Args: cobra.NoArgs,
 	RunE: run,
 }
 
@@ -54,7 +55,7 @@ func init() {
 		"cluster",
 		"c",
 		"",
-		"Name or ID of the cluster.",
+		"Name or ID or external_id of the cluster.",
 	)
 	//nolint:gosec
 	Cmd.MarkFlagRequired("cluster")

cmd/ocm/edit/ingress/cmd.go

@@ -33,7 +33,7 @@ var args struct {
 }
 
 var Cmd = &cobra.Command{
-	Use:     "ingress",
+	Use:     "ingress --cluster={NAME|ID|EXTERNAL_ID} [flags] INGRESS_ID",
 	Aliases: []string{"route", "routes", "ingresses"},
 	Short:   "Edit a cluster Ingress",
 	Long:    "Edit an Ingress endpoint to determine access to the cluster.",

cmd/ocm/edit/machinepool/cmd.go

@@ -28,7 +28,7 @@ var args struct {
 }
 
 var Cmd = &cobra.Command{
-	Use:     "machinepool",
+	Use:     "machinepool --cluster={NAME|ID|EXTERNAL_ID} [flags] MACHINE_POOL_ID",
 	Aliases: []string{"machine-pool"},
 	Short:   "Edit a cluster machine pool",
 	Long:    "Edit a machine pool size.",

cmd/ocm/get/cmd.go

@@ -35,7 +35,7 @@ var args struct {
 }
 
 var Cmd = &cobra.Command{
-	Use:       "get RESOURCE {ID}",
+	Use:       "get RESOURCE [ID]",
 	Short:     "Send a GET request",
 	Long:      "Send a GET request to the given path.",
 	RunE:      run,