Switch GitHub Accounts Safely with gh auth switch

You will finish with the GitHub CLI using the intended account for a chosen GitHub host, and a quick way to prove which account is active. The examples use GitHub CLI 2.87.3, installed on this machine. Allow about five minutes. You need an existing gh login with at least two accounts available for the same host.

This command changes which stored authentication entry gh uses. It does not log an account in, create a token, change repository permissions or alter Git configuration. It is still security-sensitive: selecting the wrong account can make later commands read or write through the wrong identity.

1. Check the installed command

First confirm the version and read the local command help. These are ordinary, read-only commands and do not need elevated privileges:

$ gh --version
gh version 2.87.3 (2026-02-23)
$ gh auth switch --help
Switch the active account for a GitHub host.

The command has only two options: --hostname (or -h) chooses the GitHub host, and --user (or -u) chooses the account. Do not use sudo. A root shell can see a different home directory and therefore a different gh authentication configuration.

Checkpoint: if gh --version reports an older release, use gh auth switch --help on that installation as the final authority for its available behaviour.

2. See the accounts and current selection

Before switching anything, ask gh to show the active account for each known host:

$ gh auth status --active
github.com
  - Active account: true

Real output also includes the account name and authentication details. The exact hosts and accounts are machine-specific, so do not copy an identity from this example. To narrow the check to one host, use:

$ gh auth status --active --hostname github.com

If the command reports an authentication problem, fix or refresh that login before switching. A switch selects an account that gh already knows; it is not a replacement for gh auth login or gh auth refresh.

3. Switch interactively when the host is obvious

Run the command without options when you want gh to guide the selection:

$ gh auth switch
? Choose an account:  [use arrows to move, type to filter]
  account-one
  account-two

Select the intended account and accept the prompt. The exact prompt formatting is release-dependent. When a host has two accounts, the command can switch between them automatically. With more than two accounts, disambiguation is needed through --user or the interactive prompt.

Do not press through a prompt merely to make it disappear. Read the host and account shown by the selection, especially on a machine used for both personal and organisation work.

4. Use explicit host and user values in repeatable work

For a script, runbook or shell history entry, name both values so the target is unambiguous:

$ gh auth switch --hostname github.com --user ACCOUNT_NAME

Replace ACCOUNT_NAME with the exact account name shown by gh auth status. For a GitHub Enterprise Server host, use its host name rather than github.com:

$ gh auth switch --hostname github.example.com --user ORG_ACCOUNT

Do not include a protocol, path or trailing repository name in --hostname. The value is a host such as github.com or github.example.com. Keep account values quoted if your shell input is generated from another command, and inspect generated values before running a state-changing command.

The switch itself normally produces no useful success text. Treat the command's exit status as the first check:

$ gh auth switch --hostname github.com --user ACCOUNT_NAME
$ printf 'switch status: %s\n' "$?"
switch status: 0

5. Verify before using a repository command

Run the status check again, restricted to the host you changed:

$ gh auth status --active --hostname github.com
github.com
  ✓ Logged in to github.com account ACCOUNT_NAME
  - Active account: true

The check may also report the Git operations protocol, token scopes and the local configuration path. Never use --show-token for routine verification: it prints a credential in plain text. Do not paste authentication output into an issue, terminal recording or support ticket.

For an additional identity check against GitHub, use a harmless API request after confirming the host and account:

$ gh api user --hostname github.com --jq .login
ACCOUNT_NAME

This makes a network request but does not modify GitHub data. If the result is not the account you expected, stop before running commands that create, edit or delete remote resources.

6. Recover from a wrong selection

Switching accounts is reversible. If the verification shows the wrong account, run the same command with the intended account:

$ gh auth switch --hostname github.com --user CORRECT_ACCOUNT
$ gh auth status --active --hostname github.com

Replace both placeholders with known values. If the account is missing, do not guess another host or edit authentication files by hand. Stop and inspect gh auth status --hostname github.com; you may need to authenticate the account with gh auth login or repair it with gh auth refresh. Those commands have their own prompts and credential consequences.

A failed switch does not prove that the previous account was changed. Always rerun the host-specific status check after an error. Common causes include a misspelled user, a host mismatch between github.com and an Enterprise host, and an account whose token has expired or lacks required access.