Merge pull request #8838 from jsoref/gh-docs-multiple-accounts

Gh docs multiple accounts

docs/multiple-accounts.md

@@ -8,7 +8,7 @@ A particular shoutout to @gabe565 and his long term community support for https:
 
 With the release of `v2.40.0`, `gh` has begun supporting multiple accounts for some use cases on github.com and
 in GitHub Enterprise. We recognise that there are a number of missing quality of life features, and we've opted
-not to address the use case of automatic account switching based on some context (e.g. `pwd`, `git remote`, etc).
+not to address the use case of automatic account switching based on some context (e.g. `pwd`, `git remote`).
 However, we hope many of those using these custom solutions will now find it easier to obtain and update tokens (via the standard
 OAuth flow rather than as a PAT), and to store them securely in the system keyring managed by `gh`.
 
@@ -111,7 +111,7 @@ if there are any remaining logged into the host:
 
 As mentioned above, we know that this only addresses some of the requests around supporting multiple accounts. While
 these are not out of scope forever, for this release some of the big things we have intentionally not included are:
- * Automatic account switching based on some context (e.g. `pwd`, `git remote`, etc)
+ * Automatic account switching based on some context (e.g. `pwd`, `git remote`)
  * Automatic configuration of git config such as `user.name` and `user.email` when switching
  * User level configuration e.g. `williammartin` uses `vim` but `wilmartin_microsoft` uses `emacs`
 

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

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

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