Unhide login subcommand and improve several command help messages

Co-authored-by: Ryan Richard <richardry@vmware.com>
Co-authored-by: Benjamin A. Petersen <ben@benjaminapetersen.me>

cmd/pinniped/cmd/alpha.go

@@ -1,22 +0,0 @@
-// Copyright 2020-2022 the Pinniped contributors. All Rights Reserved.
-// SPDX-License-Identifier: Apache-2.0
-
-package cmd
-
-import (
-	"github.com/spf13/cobra"
-)
-
-//nolint:gochecknoglobals
-var alphaCmd = &cobra.Command{
-	Use:          "alpha",
-	Short:        "alpha",
-	Long:         "alpha subcommands (syntax or flags are still subject to change)",
-	SilenceUsage: true, // do not print usage message when commands fail
-	Hidden:       true,
-}
-
-//nolint:gochecknoinits
-func init() {
-	rootCmd.AddCommand(alphaCmd)
-}

cmd/pinniped/cmd/generate_markdown_help.go

@@ -1,4 +1,4 @@
-// Copyright 2020-2022 the Pinniped contributors. All Rights Reserved.
+// Copyright 2020-2023 the Pinniped contributors. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 
 package cmd
@@ -24,7 +24,7 @@ func generateMarkdownHelpCommand() *cobra.Command {
 		Args:         cobra.NoArgs,
 		Use:          "generate-markdown-help",
 		Short:        "Generate markdown help for the current set of non-hidden CLI commands",
-		SilenceUsage: true,
+		SilenceUsage: true, // do not print usage message when commands fail
 		Hidden:       true,
 		RunE:         runGenerateMarkdownHelp,
 	}

cmd/pinniped/cmd/get.go

@@ -1,4 +1,4 @@
-// Copyright 2020-2022 the Pinniped contributors. All Rights Reserved.
+// Copyright 2020-2023 the Pinniped contributors. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 
 package cmd
@@ -8,7 +8,11 @@ import (
 )
 
 //nolint:gochecknoglobals
-var getCmd = &cobra.Command{Use: "get", Short: "get"}
+var getCmd = &cobra.Command{
+	Use:          "get",
+	Short:        "Gets one of [kubeconfig]",
+	SilenceUsage: true, // Do not print usage message when commands fail.
+}
 
 //nolint:gochecknoinits
 func init() {

cmd/pinniped/cmd/kubeconfig.go

@@ -1,4 +1,4 @@
-// Copyright 2020-2022 the Pinniped contributors. All Rights Reserved.
+// Copyright 2020-2023 the Pinniped contributors. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 
 package cmd
@@ -103,7 +103,7 @@ func kubeconfigCommand(deps kubeconfigDeps) *cobra.Command {
 			Args:         cobra.NoArgs,
 			Use:          "kubeconfig",
 			Short:        "Generate a Pinniped-based kubeconfig for a cluster",
-			SilenceUsage: true,
+			SilenceUsage: true, // do not print usage message when commands fail
 		}
 		flags     getKubeconfigParams
 		namespace string // unused now

cmd/pinniped/cmd/login.go

@@ -1,4 +1,4 @@
-// Copyright 2020-2022 the Pinniped contributors. All Rights Reserved.
+// Copyright 2020-2023 the Pinniped contributors. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 
 package cmd
@@ -7,15 +7,27 @@ import (
 	"github.com/spf13/cobra"
 	clientauthv1beta1 "k8s.io/client-go/pkg/apis/clientauthentication/v1beta1"
 	"k8s.io/client-go/tools/auth/exec"
+
+	"go.pinniped.dev/internal/here"
 )
 
 //nolint:gochecknoglobals
 var loginCmd = &cobra.Command{
-	Use:          "login",
+	Use:   "login",
-	Short:        "login",
+	Short: "Authenticates with one of [oidc, static]",
-	Long:         "Login to a Pinniped server",
+	Long: here.Doc(
+		`Authenticates with one of [oidc, static]
+
+			Use "pinniped get kubeconfig" to generate a kubeconfig file which will include
+			one of these login subcommands in its configuration. The oidc and static
+			subcommands are not meant to be invoked directly by a user.
+
+			The oidc and static subcommands are Kubernetes client-go credential plugins
+			which are meant to be configured inside a kubeconfig file. (See the Kubernetes
+			authentication documentation for more information about client-go credential
+			plugins.)`,
+	),
 	SilenceUsage: true, // Do not print usage message when commands fail.
-	Hidden:       true, // These commands are not really meant to be used directly by users, so it's confusing to have them discoverable.
 }
 
 //nolint:gochecknoinits

cmd/pinniped/cmd/login_oidc.go

@@ -1,4 +1,4 @@
-// Copyright 2020-2022 the Pinniped contributors. All Rights Reserved.
+// Copyright 2020-2023 the Pinniped contributors. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 
 package cmd
@@ -23,6 +23,7 @@ import (
 	oidcapi "go.pinniped.dev/generated/latest/apis/supervisor/oidc"
 	"go.pinniped.dev/internal/execcredcache"
 	"go.pinniped.dev/internal/groupsuffix"
+	"go.pinniped.dev/internal/here"
 	"go.pinniped.dev/internal/net/phttp"
 	"go.pinniped.dev/internal/plog"
 	"go.pinniped.dev/pkg/conciergeclient"
@@ -88,10 +89,21 @@ type oidcLoginFlags struct {
 func oidcLoginCommand(deps oidcLoginCommandDeps) *cobra.Command {
 	var (
 		cmd = &cobra.Command{
-			Args:         cobra.NoArgs,
+			Args:  cobra.NoArgs,
-			Use:          "oidc --issuer ISSUER",
+			Use:   "oidc --issuer ISSUER",
-			Short:        "Login using an OpenID Connect provider",
+			Short: "Login using an OpenID Connect provider",
-			SilenceUsage: true,
+			Long: here.Doc(
+				`Login using an OpenID Connect provider
+
+					Use "pinniped get kubeconfig" to generate a kubeconfig file which includes this
+					login command in its configuration. This login command is not meant to be
+					invoked directly by a user.
+
+					This login command is a Kubernetes client-go credential plugin which is meant to
+					be configured inside a kubeconfig file. (See the Kubernetes authentication
+					documentation for more information about client-go credential plugins.)`,
+			),
+			SilenceUsage: true, // do not print usage message when commands fail
 		}
 		flags              oidcLoginFlags
 		conciergeNamespace string // unused now

cmd/pinniped/cmd/login_oidc_test.go

@@ -1,4 +1,4 @@
-// Copyright 2020-2022 the Pinniped contributors. All Rights Reserved.
+// Copyright 2020-2023 the Pinniped contributors. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 
 package cmd
@@ -62,6 +62,14 @@ func TestLoginOIDCCommand(t *testing.T) {
 			wantStdout: here.Doc(`
 				Login using an OpenID Connect provider
 
+				Use "pinniped get kubeconfig" to generate a kubeconfig file which includes this
+				login command in its configuration. This login command is not meant to be
+				invoked directly by a user.
+
+				This login command is a Kubernetes client-go credential plugin which is meant to
+				be configured inside a kubeconfig file. (See the Kubernetes authentication
+				documentation for more information about client-go credential plugins.)
+
 				Usage:
 				  oidc --issuer ISSUER [flags]
 
@@ -483,8 +491,8 @@ func TestLoginOIDCCommand(t *testing.T) {
 			wantOptionsCount: 4,
 			wantStdout:       `{"kind":"ExecCredential","apiVersion":"client.authentication.k8s.io/v1beta1","spec":{"interactive":false},"status":{"expirationTimestamp":"3020-10-12T13:14:15Z","token":"test-id-token"}}` + "\n",
 			wantLogs: []string{
-				nowStr + `  pinniped-login  cmd/login_oidc.go:231  Performing OIDC login  {"issuer": "test-issuer", "client id": "test-client-id"}`,
+				nowStr + `  pinniped-login  cmd/login_oidc.go:243  Performing OIDC login  {"issuer": "test-issuer", "client id": "test-client-id"}`,
-				nowStr + `  pinniped-login  cmd/login_oidc.go:251  No concierge configured, skipping token credential exchange`,
+				nowStr + `  pinniped-login  cmd/login_oidc.go:263  No concierge configured, skipping token credential exchange`,
 			},
 		},
 		{
@@ -513,10 +521,10 @@ func TestLoginOIDCCommand(t *testing.T) {
 			wantOptionsCount: 11,
 			wantStdout:       `{"kind":"ExecCredential","apiVersion":"client.authentication.k8s.io/v1beta1","spec":{"interactive":false},"status":{"token":"exchanged-token"}}` + "\n",
 			wantLogs: []string{
-				nowStr + `  pinniped-login  cmd/login_oidc.go:231  Performing OIDC login  {"issuer": "test-issuer", "client id": "test-client-id"}`,
+				nowStr + `  pinniped-login  cmd/login_oidc.go:243  Performing OIDC login  {"issuer": "test-issuer", "client id": "test-client-id"}`,
-				nowStr + `  pinniped-login  cmd/login_oidc.go:241  Exchanging token for cluster credential  {"endpoint": "https://127.0.0.1:1234/", "authenticator type": "webhook", "authenticator name": "test-authenticator"}`,
+				nowStr + `  pinniped-login  cmd/login_oidc.go:253  Exchanging token for cluster credential  {"endpoint": "https://127.0.0.1:1234/", "authenticator type": "webhook", "authenticator name": "test-authenticator"}`,
-				nowStr + `  pinniped-login  cmd/login_oidc.go:249  Successfully exchanged token for cluster credential.`,
+				nowStr + `  pinniped-login  cmd/login_oidc.go:261  Successfully exchanged token for cluster credential.`,
-				nowStr + `  pinniped-login  cmd/login_oidc.go:256  caching cluster credential for future use.`,
+				nowStr + `  pinniped-login  cmd/login_oidc.go:268  caching cluster credential for future use.`,
 			},
 		},
 	}

cmd/pinniped/cmd/login_static.go

@@ -1,4 +1,4 @@
-// Copyright 2020-2022 the Pinniped contributors. All Rights Reserved.
+// Copyright 2020-2023 the Pinniped contributors. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 
 package cmd
@@ -16,6 +16,7 @@ import (
 
 	"go.pinniped.dev/internal/execcredcache"
 	"go.pinniped.dev/internal/groupsuffix"
+	"go.pinniped.dev/internal/here"
 	"go.pinniped.dev/internal/plog"
 	"go.pinniped.dev/pkg/conciergeclient"
 	"go.pinniped.dev/pkg/oidcclient/oidctypes"
@@ -55,10 +56,21 @@ type staticLoginParams struct {
 func staticLoginCommand(deps staticLoginDeps) *cobra.Command {
 	var (
 		cmd = &cobra.Command{
-			Args:         cobra.NoArgs,
+			Args:  cobra.NoArgs,
-			Use:          "static [--token TOKEN] [--token-env TOKEN_NAME]",
+			Use:   "static [--token TOKEN] [--token-env TOKEN_NAME]",
-			Short:        "Login using a static token",
+			Short: "Login using a static token",
-			SilenceUsage: true,
+			Long: here.Doc(
+				`Login using a static token
+
+					Use "pinniped get kubeconfig" to generate a kubeconfig file which includes this
+					login command in its configuration. This login command is not meant to be
+					invoked directly by a user.
+
+					This login command is a Kubernetes client-go credential plugin which is meant to
+					be configured inside a kubeconfig file. (See the Kubernetes authentication
+					documentation for more information about client-go credential plugins.)`,
+			),
+			SilenceUsage: true, // do not print usage message when commands fail
 		}
 		flags              staticLoginParams
 		conciergeNamespace string // unused now

cmd/pinniped/cmd/login_static_test.go

@@ -1,4 +1,4 @@
-// Copyright 2020-2022 the Pinniped contributors. All Rights Reserved.
+// Copyright 2020-2023 the Pinniped contributors. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 
 package cmd
@@ -56,6 +56,14 @@ func TestLoginStaticCommand(t *testing.T) {
 			wantStdout: here.Doc(`
 				Login using a static token
 
+				Use "pinniped get kubeconfig" to generate a kubeconfig file which includes this
+				login command in its configuration. This login command is not meant to be
+				invoked directly by a user.
+
+				This login command is a Kubernetes client-go credential plugin which is meant to
+				be configured inside a kubeconfig file. (See the Kubernetes authentication
+				documentation for more information about client-go credential plugins.)
+
 				Usage:
 				  static [--token TOKEN] [--token-env TOKEN_NAME] [flags]
 
@@ -140,7 +148,7 @@ func TestLoginStaticCommand(t *testing.T) {
 				Error: could not complete Concierge credential exchange: some concierge error
 			`),
 			wantLogs: []string{
-				nowStr + `  pinniped-login  cmd/login_static.go:147  exchanging static token for cluster credential  {"endpoint": "https://127.0.0.1/", "authenticator type": "webhook", "authenticator name": "test-authenticator"}`,
+				nowStr + `  pinniped-login  cmd/login_static.go:159  exchanging static token for cluster credential  {"endpoint": "https://127.0.0.1/", "authenticator type": "webhook", "authenticator name": "test-authenticator"}`,
 			},
 		},
 		{

cmd/pinniped/cmd/root.go

@@ -1,4 +1,4 @@
-// Copyright 2020-2022 the Pinniped contributors. All Rights Reserved.
+// Copyright 2020-2023 the Pinniped contributors. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 
 package cmd
@@ -8,14 +8,18 @@ import (
 
 	"github.com/spf13/cobra"
 
+	"go.pinniped.dev/internal/here"
 	"go.pinniped.dev/internal/plog"
 )
 
 //nolint:gochecknoglobals
 var rootCmd = &cobra.Command{
-	Use:          "pinniped",
+	Use: "pinniped",
-	Short:        "pinniped",
+	Long: here.Doc(
-	Long:         "pinniped is the client-side binary for use with Pinniped-enabled Kubernetes clusters.",
+		`The Pinniped CLI is the client-side binary for use with Pinniped-enabled Kubernetes clusters
+
+		 Find more information at: https://pinniped.dev`,
+	),
 	SilenceUsage: true, // do not print usage message when commands fail
 }
 

cmd/pinniped/cmd/whoami.go

@@ -1,4 +1,4 @@
-// Copyright 2021-2022 the Pinniped contributors. All Rights Reserved.
+// Copyright 2021-2023 the Pinniped contributors. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 
 package cmd
@@ -48,7 +48,7 @@ func newWhoamiCommand(getClientset getConciergeClientsetFunc) *cobra.Command {
 		Args:         cobra.NoArgs, // do not accept positional arguments for this command
 		Use:          "whoami",
 		Short:        "Print information about the current user",
-		SilenceUsage: true,
+		SilenceUsage: true, // do not print usage message when commands fail
 	}
 	flags := &whoamiFlags{}