From 6ff355049c96d169cc8ffbd9aaec32c19dce41ca Mon Sep 17 00:00:00 2001
From: Josh Soref <2119212+jsoref@users.noreply.github.com>
Date: Mon, 18 Mar 2024 12:09:27 -0400
Subject: [PATCH] Improve discovery of `gh auth status`

---
 pkg/cmd/auth/refresh/refresh.go | 6 +++++-
 pkg/cmd/auth/status/status.go   | 2 +-
 pkg/cmd/auth/switch/switch.go   | 6 ++++--
 3 files changed, 10 insertions(+), 4 deletions(-)

diff --git a/pkg/cmd/auth/refresh/refresh.go b/pkg/cmd/auth/refresh/refresh.go
index a918493e8..b77c45bac 100644
--- a/pkg/cmd/auth/refresh/refresh.go
+++ b/pkg/cmd/auth/refresh/refresh.go
@@ -55,7 +55,7 @@ func NewCmdRefresh(f *cmdutil.Factory, runF func(*RefreshOptions) error) *cobra.
 		Use:   "refresh",
 		Args:  cobra.ExactArgs(0),
 		Short: "Refresh stored authentication credentials",
-		Long: heredoc.Docf(`Expand or fix the permission scopes for stored credentials.
+		Long: heredoc.Docf(`Expand or fix the permission scopes for stored credentials for active account.
 
 			The %[1]s--scopes%[1]s flag accepts a comma separated list of scopes you want
 			your gh credentials to have. If no scopes are provided, the command
@@ -67,6 +67,10 @@ func NewCmdRefresh(f *cmdutil.Factory, runF func(*RefreshOptions) error) *cobra.
 
 			The %[1]s--reset-scopes%[1]s flag resets the scopes for your gh credentials to
 			the default set of scopes for your auth flow.
+
+			If you have multiple accounts in %[1]sgh auth status%[1]s and want to refresh the credentials for an
+			inactive account, you will have to use %[1]sgh auth switch%[1]s to that account first before using
+			this command, and then switch back when you are done.
 		`, "`"),
 		Example: heredoc.Doc(`
 			$ gh auth refresh --scopes write:org,read:public_key
diff --git a/pkg/cmd/auth/status/status.go b/pkg/cmd/auth/status/status.go
index fa027e193..c28c3f48e 100644
--- a/pkg/cmd/auth/status/status.go
+++ b/pkg/cmd/auth/status/status.go
@@ -140,7 +140,7 @@ func NewCmdStatus(f *cmdutil.Factory, runF func(*StatusOptions) error) *cobra.Co
 	cmd := &cobra.Command{
 		Use:   "status",
 		Args:  cobra.ExactArgs(0),
-		Short: "View authentication status",
+		Short: "View all accounts and authentication status",
 		Long: heredoc.Doc(`Verifies and displays information about your authentication state.
 
 			This command will test your authentication state for each GitHub host that gh knows about and
diff --git a/pkg/cmd/auth/switch/switch.go b/pkg/cmd/auth/switch/switch.go
index 129fe9fd4..bc94ff8c4 100644
--- a/pkg/cmd/auth/switch/switch.go
+++ b/pkg/cmd/auth/switch/switch.go
@@ -32,12 +32,14 @@ func NewCmdSwitch(f *cmdutil.Factory, runF func(*SwitchOptions) error) *cobra.Co
 		Use:   "switch",
 		Args:  cobra.ExactArgs(0),
 		Short: "Switch active GitHub account",
-		Long: heredoc.Doc(`
+		Long: heredoc.Docf(`
 			Switch the active account for a GitHub host.
 
 			This command changes the authentication configuration that will
 			be used when running commands targeting the specified GitHub host.
-		`),
+
+			For a list of authenticated accounts you can run %[1]sgh auth status%[1]s.
+		`, "`"),
 		Example: heredoc.Doc(`
 			# Select what host and account to switch to via a prompt
 			$ gh auth switch