Repository navigation
Improve discoverability of active accounts in gh auth status #8832
Description
Activity
gh auth statuslists the accounts that are available for you toswitchto, and indicate which account is currentlyactive. Is there something missing in there?We should probably update the help text of
auth statusto be a bit clearer about its behaviour in the multi-account world, it's definitely not obvious.Reacted by Josh SorefSo...
gh authAuthenticate 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/manualIt isn't obvious from any of the text here that
gh auth statuswould have the information needed to drivegh auth switchgh auth switch --helpSwitch 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/manualgh auth switch --helpshould also tell people to look atgh auth statusfor the list of available logged in accounts...gh auth refresh --helpExpand 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/manualThis makes no mention of users...
gh auth token --helpThis 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 ofThis is just wrong. It's technically off-topic here, but I'm exhausted -- and I just woke up.
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
statusdescription 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 wantedfor the doc changes, thanks.- changed the title
[-]Please add `gh auth list`[/-][+]Improve discoverability of active accounts in `gh auth status`[/+]on Mar 18, 2024 - marked add
gh auth listas alias forgh auth status#13686 as a duplicate of this issueon Jun 19, 2026
Describe the feature or problem you’d like to solve
Apparently
gh auth switchexists, but there doesn't appear to be any easy way to determine which accounts are availableProposed solution
add
gh auth list-- see alsogcloud auth listThis would allow for a more natural flow for users -- no need for them to guess how
gh auth switchwill behave or whether they need to usegh auth login.Additional context