Improve discoverability of active accounts in gh auth status

[jsoref]

Describe the feature or problem you’d like to solve

Apparently gh auth switch exists, but there doesn't appear to be any easy way to determine which accounts are available

Proposed solution

add gh auth list -- see also gcloud auth list

This would allow for a more natural flow for users -- no need for them to guess how gh auth switch will behave or whether they need to use gh auth login.

Additional context

[williammartin]

gh auth status lists the accounts that are available for you to switch to, and indicate which account is currently active. Is there something missing in there?

[williammartin]

We should probably update the help text of auth status to be a bit clearer about its behaviour in the multi-account world, it's definitely not obvious.

[jsoref]

So...

gh auth

Authenticate gh and git with GitHub

USAGE
  gh auth <command> [flags]

AVAILABLE COMMANDS
  login:       Log in to a GitHub account
  logout:      Log out of a GitHub account
  refresh:     Refresh stored authentication credentials
  setup-git:   Setup git with GitHub CLI
  status:      View authentication status
  switch:      Switch active GitHub account
  token:       Print the authentication token gh uses for a hostname and account

INHERITED FLAGS
  --help   Show help for command

LEARN MORE
  Use `gh <command> <subcommand> --help` for more information about a command.
  Read the manual at https://cli.github.com/manual

It isn't obvious from any of the text here that gh auth status would have the information needed to drive gh auth switch

gh auth switch --help

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.


USAGE
  gh auth switch [flags]

FLAGS
  -h, --hostname string   The hostname of the GitHub instance to switch account for
  -u, --user string       The account to switch to

INHERITED FLAGS
  --help   Show help for command

EXAMPLES
  # Select what host and account to switch to via a prompt
  $ gh auth switch

  # Switch to a specific host and specific account
  $ gh auth logout --hostname enterprise.internal --user monalisa

LEARN MORE
  Use `gh <command> <subcommand> --help` for more information about a command.
  Read the manual at https://cli.github.com/manual

gh auth switch --help should also tell people to look at gh auth status for the list of available logged in accounts...

gh auth refresh --help

Expand or fix the permission scopes for stored credentials.

The `--scopes` flag accepts a comma separated list of scopes you want
your gh credentials to have. If no scopes are provided, the command
maintains previously added scopes.

The `--remove-scopes` flag accepts a comma separated list of scopes you
want to remove from your gh credentials. Scope removal is idempotent.
The minimum set of scopes (`repo`, `read:org`, and `gist`) cannot be removed.

The `--reset-scopes` flag resets the scopes for your gh credentials to
the default set of scopes for your auth flow.


USAGE
  gh auth refresh [flags]

FLAGS
  -h, --hostname string         The GitHub host to use for authentication
      --insecure-storage        Save authentication credentials in plain text instead of credential store
  -r, --remove-scopes strings   Authentication scopes to remove from gh
      --reset-scopes            Reset authentication scopes to the default minimum set of scopes
  -s, --scopes strings          Additional authentication scopes for gh to have

INHERITED FLAGS
  --help   Show help for command

EXAMPLES
  $ gh auth refresh --scopes write:org,read:public_key
  # => open a browser to add write:org and read:public_key scopes

  $ gh auth refresh
  # => open a browser to ensure your authentication credentials have the correct minimum scopes

  $ gh auth refresh --remove-scopes delete_repo
  # => open a browser to idempotently remove the delete_repo scope

  $ gh auth refresh --reset-scopes
  # => open a browser to re-authenticate with the default minimum scopes

LEARN MORE
  Use `gh <command> <subcommand> --help` for more information about a command.
  Read the manual at https://cli.github.com/manual

This makes no mention of users...

gh auth token --help

This command outputs the authentication token for an account on a given GitHub host.

Without the `--hostname` flag, the default host is chosen.

Without the `--user` flag, the active account for the host is chosen.


USAGE
  gh auth token [flags]

FLAGS
  -h, --hostname string   The hostname of the GitHub instance authenticated with
  -u, --user string       The account to log out of

INHERITED FLAGS
  --help   Show help for command

LEARN MORE
  Use `gh <command> <subcommand> --help` for more information about a command.
  Read the manual at https://cli.github.com/manual

-u, --user string The account to log out of

This is just wrong. It's technically off-topic here, but I'm exhausted -- and I just woke up.

[williammartin]

It isn't obvious from any of the text here that gh auth status would have the information needed to drive gh auth switch

Sure, happy to have some details in the status description to provide a hint.

gh auth switch --help should also tell people to look at gh auth status for the list of available logged in accounts...

Sure, happy to have some further details in the description.

This makes no mention of users...

Yes, it's not possible through the CLI to target a specific user for refresh because the oauth flow is handed by the platform. Happy to have some details to that affect in the description. You can read some more here: https://github.com/cli/cli/blob/trunk/docs/multiple-accounts.md#auth-refresh

This is just wrong. It's technically off-topic here, but I'm exhausted -- and I just woke up.

Is already fixed in: #8797

---

Labelling this help wanted for the doc changes, thanks.