improve CLI help text for all datumctl commands

- Replace kubectl-centric Short/Long/Example text on all wrapped commands
- Add Long and Example to all auth, mcp, and docs subcommands
- Override activity command (external package) in root.go
- Scope kubectl integration commands (whoami, can-i, get-token, update-kubeconfig) as advanced/kubectl-only
- Hide irrelevant kubectl flags on create command
- Fix templates.LongDesc vs templates.Examples in generate-cli-docs
- Add cli-help-improvement-plan.md design doc

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: bmertens-datum

docs/cli-help-improvement-plan.md

@@ -9,7 +9,19 @@ import (
 func Command() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "auth",
-		Short: "Authenticate with Datum Cloud",
+		Short: "Manage Datum Cloud authentication credentials",
+		Long: `The auth group provides commands to log in to Datum Cloud, manage multiple
+user sessions, and retrieve tokens for scripting.
+
+Typical workflow:
+  1. Log in:          datumctl auth login
+  2. Verify sessions: datumctl auth list
+  3. Switch accounts: datumctl auth switch <email>
+  4. Log out:         datumctl auth logout <email>
+
+Advanced — kubectl integration:
+  If you use kubectl and want to point it at a Datum Cloud control plane,
+  see 'datumctl auth update-kubeconfig --help'.`,
 	}
 
 	cmd.AddCommand(

internal/cmd/auth/auth.go

@@ -22,12 +22,33 @@ const (
 // getTokenCmd retrieves tokens based on the --output flag.
 var getTokenCmd = &cobra.Command{
 	Use:   "get-token",
-	Short: "Retrieve access token for active user (raw or K8s format)",
-	Long: `Retrieves credentials for the currently active datumctl user.
+	Short: "Print the active user's access token (advanced / kubectl integration)",
+	Long: `Print the current access token for the active Datum Cloud user.
 
-Default behavior (--output=token) prints the raw access token to stdout.
-With --output=client.authentication.k8s.io/v1, prints a K8s ExecCredential JSON object
-suitable for use as a kubectl credential plugin.`, // Updated description
+Most datumctl users do not need this command — datumctl handles
+authentication automatically for all its own commands.
+
+This command exists for two advanced use cases:
+
+  1. kubectl credential plugin: invoked automatically by kubectl after you
+     run 'datumctl auth update-kubeconfig'. You do not need to call it
+     directly in that case.
+
+  2. Scripting or direct API calls: use --output=token to get a raw bearer
+     token to pass to curl or other HTTP clients.
+
+If the stored token is expired, datumctl automatically uses the stored
+refresh token to obtain a new one before printing.
+
+Output formats (--output / -o):
+  token                         Print the raw access token (default).
+  client.authentication.k8s.io/v1  Print a Kubernetes ExecCredential JSON
+                                object for kubectl credential plugin use.`,
+	Example: `  # Get a raw token for use in a script or direct API call
+  datumctl auth get-token
+
+  # Get a Kubernetes ExecCredential JSON object (used by kubectl automatically)
+  datumctl auth get-token --output=client.authentication.k8s.io/v1`,
 	Args: cobra.NoArgs,
 	RunE: runGetToken, // Use single function
 }

internal/cmd/auth/get_token.go

@@ -16,6 +16,20 @@ var listCmd = &cobra.Command{
 	Use:     "list",
 	Short:   "List locally authenticated users",
 	Aliases: []string{"ls"},
+	Long: `Display a table of all Datum Cloud users whose credentials are stored
+locally in the system keyring, along with their status.
+
+Columns:
+  Name    The display name from the user's Datum Cloud account.
+  Email   The email address used to log in. Pass this to 'datumctl auth switch'
+          or 'datumctl auth logout' to act on a specific account.
+  Status  "Active" marks the account whose credentials are used by default
+          for all subsequent datumctl commands.`,
+	Example: `  # Show all logged-in users
+  datumctl auth list
+
+  # Alias
+  datumctl auth ls`,
 	RunE: func(cmd *cobra.Command, args []string) error {
 		return runList()
 	},

internal/cmd/auth/list.go

@@ -40,7 +40,35 @@ var (
 
 var LoginCmd = &cobra.Command{
 	Use:   "login",
-	Short: "Authenticate with Datum Cloud via OAuth2 PKCE flow",
+	Short: "Log in to Datum Cloud",
+	Long: `Authenticate with Datum Cloud using a secure browser-based login flow.
+
+Running this command will:
+  1. Open your default web browser to the Datum Cloud authentication page.
+     If the browser cannot open automatically, a URL is printed for manual use.
+  2. Complete authentication in the browser (username/password or SSO).
+  3. Return to datumctl, which stores your credentials (including a refresh
+     token) securely in the system keyring.
+
+After login, credentials are associated with your email address and
+automatically refreshed when they expire. Use 'datumctl auth list' to see
+all stored sessions.
+
+By default, logs into auth.datum.net (the production Datum Cloud environment).
+Use --hostname to target a different environment (e.g., staging).
+Use --api-hostname to explicitly specify the API server hostname when it
+cannot be derived from the auth hostname (e.g., in self-hosted environments).`,
+	Example: `  # Log in to Datum Cloud (opens browser)
+  datumctl auth login
+
+  # Log in to a staging environment
+  datumctl auth login --hostname auth.staging.env.datum.net
+
+  # Log in to a self-hosted environment with an explicit client ID
+  datumctl auth login --hostname auth.example.com --client-id 123456789
+
+  # Log in to a self-hosted environment with explicit API hostname
+  datumctl auth login --hostname auth.example.com --api-hostname api.example.com --client-id 123456789`,
 	RunE: func(cmd *cobra.Command, args []string) error {
 		var actualClientID string
 		if clientIDFlag != "" {

internal/cmd/auth/login.go

@@ -14,21 +14,30 @@ var logoutAll bool // Flag variable for --all
 
 // logoutCmd removes local authentication credentials for a specified user or all users.
 var logoutCmd = &cobra.Command{
-	Use:   "logout [user]",
-	Short: "Remove local authentication credentials for a specified user or all users",
-	Long: `Remove local authentication credentials.
-
-Specify a user in the format 'email@hostname' to log out only that user.
-Use 'datumctl auth list' to see available users.
-Use the --all flag to log out all known users.`, // Updated Long description
+	Use:   "logout <email>",
+	Short: "Remove stored credentials for a user or all users",
+	Long: `Remove locally stored Datum Cloud credentials from the system keyring.
+
+Provide the email address of the user to log out (as shown by
+'datumctl auth list'). Use --all to remove credentials for every
+logged-in user at once.
+
+If you log out the currently active user, the active session is cleared.
+You will need to run 'datumctl auth login' again before running commands
+that require authentication.`,
+	Example: `  # Log out a specific user
+  datumctl auth logout user@example.com
+
+  # Log out all authenticated users
+  datumctl auth logout --all`,
 	Args: func(cmd *cobra.Command, args []string) error {
 		// Custom args validation
 		all, _ := cmd.Flags().GetBool("all")
 		if all && len(args) > 0 {
 			return errors.New("cannot specify a user argument when using the --all flag")
 		}
 		if !all && len(args) != 1 {
-			return errors.New("must specify exactly one user (email@hostname) or use the --all flag")
+			return errors.New("must specify exactly one user email or use the --all flag")
 		}
 		return nil
 	},

internal/cmd/auth/logout.go

@@ -12,11 +12,19 @@ import (
 
 var switchCmd = &cobra.Command{
 	Use:   "switch <user-email>",
-	Short: "Set the active authenticated user session",
-	Long: `Switches the active user context to the specified user email.
+	Short: "Switch the active Datum Cloud user session",
+	Long: `Change which locally stored user account is treated as active.
 
-The user email must correspond to an existing set of credentials previously
-established via 'datumctl auth login'. Use 'datumctl auth list' to see available users.`,
+The active user's credentials are used for all datumctl commands that
+require authentication.
+
+The email address must match an account shown by 'datumctl auth list'.
+To add a new account, run 'datumctl auth login' first.`,
+	Example: `  # See which accounts are available
+  datumctl auth list
+
+  # Switch to a different account
+  datumctl auth switch user@example.com`,
 	Args: cobra.ExactArgs(1), // Requires exactly one argument: the user email
 	RunE: func(cmd *cobra.Command, args []string) error {
 		targetUserKey := args[0]

internal/cmd/auth/switch.go

@@ -17,7 +17,37 @@ func updateKubeconfigCmd() *cobra.Command {
 
 	cmd := &cobra.Command{
 		Use:   "update-kubeconfig",
-		Short: "Update the kubeconfig file",
+		Short: "Configure kubectl to access a Datum Cloud control plane (kubectl users only)",
+		Long: `For kubectl users only. datumctl users do not need this command —
+manage your resources directly with 'datumctl get', 'datumctl apply', etc.
+
+This command adds or updates a cluster, user, and context entry in your
+kubeconfig file so that kubectl can authenticate to a Datum Cloud control
+plane using your active datumctl session.
+
+After running this command, kubectl will automatically call
+'datumctl auth get-token' to obtain a fresh credential on each request.
+
+You must specify exactly one of --organization or --project:
+
+  --organization <id>   Configure kubectl access to an organization's
+                        control plane.
+  --project <id>        Configure kubectl access to a specific project's
+                        control plane.
+
+The kubeconfig is updated at $HOME/.kube/config by default, or the path
+set by the KUBECONFIG environment variable. Use --kubeconfig to override.
+
+Use --hostname to override the API server hostname (useful for self-hosted
+environments where the hostname cannot be derived from stored credentials).`,
+		Example: `  # Configure kubectl for an organization's control plane
+  datumctl auth update-kubeconfig --organization my-org-id
+
+  # Configure kubectl for a specific project's control plane
+  datumctl auth update-kubeconfig --project my-project-id
+
+  # Write to a custom kubeconfig file
+  datumctl auth update-kubeconfig --organization my-org-id --kubeconfig ~/.kube/datum-config`,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			// Determine kubeconfig path
 			var kubeconfigPath string

internal/cmd/auth/update-kubeconfig.go

@@ -14,5 +14,23 @@ func NewCmdCreate(f util.Factory, ioStreams genericiooptions.IOStreams) *cobra.C
 	for _, subCmd := range cmd.Commands() {
 		cmd.RemoveCommand(subCmd)
 	}
+	cmd.Short = "Create a Datum Cloud resource from a file or stdin"
+	cmd.Long = `Create a new Datum Cloud resource by providing a manifest in YAML or JSON
+format, either from a file or piped through stdin.
+
+datumctl create accepts Datum Cloud resource manifests — not Kubernetes
+built-in resources. Use 'datumctl apply' for idempotent creation or updates.
+
+Resource manifests must specify the correct apiVersion and kind for the
+Datum Cloud resource type. Use 'datumctl explain <type>' to see the schema
+for a resource type and 'datumctl api-resources' to list available types.`
+	cmd.Example = `  # Create a project from a manifest file
+  datumctl create -f ./project.yaml --organization <org-id>
+
+  # Create a resource from stdin
+  cat dnszone.yaml | datumctl create -f - --project <project-id>
+
+  # Validate the resource without creating it
+  datumctl create -f ./project.yaml --organization <org-id> --dry-run=server`
 	return cmd
 }

internal/cmd/create/create.go

@@ -6,8 +6,16 @@ import "github.com/spf13/cobra"
 func Command(root *cobra.Command) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "docs",
-		Short: "Documentation and API exploration commands",
-		Long:  `Commands for exploring and browsing API documentation.`,
+		Short: "Explore API documentation and generate CLI reference docs",
+		Long: `The docs group provides tools for discovering and exploring the Datum Cloud
+API, as well as generating offline documentation for datumctl itself.
+
+Subcommands:
+  openapi               Launch a local Swagger UI to browse OpenAPI specs
+                        for any API group available in the current context.
+  generate-cli-docs     Generate markdown documentation files for all
+                        datumctl commands (used to build the published
+                        CLI reference at datum.net/docs).`,
 	}
 	cmd.AddCommand(OpenAPICmd())