Check GitHub CLI Accounts and Tokens with gh auth status

gh auth status answers the question you ask mid-deploy: which GitHub account is gh actually using, and is it even logged in properly. You will finish with a repeatable check across every host configured on your machine, including which account is active and whether anything has gone wrong. The examples match GitHub CLI 2.87.3, installed here as package gh. Allow about ten minutes.

The route

Jump straight to the step you need, or tick off Done means at the end.

1. Confirm the installed command
2. Check all configured hosts
3. Restrict the check to one host or account
4. Use JSON for a scriptable check
5. Capture diagnostics without leaking secrets
6. Treat token output as a deliberate exception
7. Diagnose the usual failure paths

You need: an ordinary shell and an existing gh configuration.
It will not touch: nothing here logs you in, switches accounts, or changes credentials. It only reads.

Security boundary

Checking status is normally unprivileged. Do not use sudo to run gh auth status unless you deliberately mean to inspect a different root user's configuration. The command can print a token in plain text when asked, so leave --show-token out of normal checks.

1. Confirm the installed command

Check the executable and version before relying on its output or scripting around it. These are read-only commands and need no elevated privileges:

$ command -v gh
/usr/bin/gh
$ gh --version
gh version 2.87.3 (2026-02-23)
https://github.com/cli/cli/releases/tag/v2.87.3

Path and date will differ. The important checkpoint is that the command you tested is the one your shell actually runs.
Missing gh? Install it through your normal package-management process, then come back. Do not copy a token or hosts file from another machine just to make the check pass.

2. Check all configured hosts

Run the default status check:

$ gh auth status
github.com
  ✓ Logged in to github.com account ACCOUNT_NAME (/home/USER/.config/gh/hosts.yml)
  - Active account: true
  - Git operations protocol: https
  - Token: gho_************************************
  - Token scopes: 'gist', 'read:org', 'repo', 'workflow'

The account name, token prefix, scopes and configuration path above are examples; your output is host-specific. A host section identifies the active account, the one the CLI uses when targeting that host. With several known accounts, the default check tests each one and reports any issue it finds, not just the active account.

Checkpoint

The expected host appears, one account is marked active, and no line reports an authentication problem. A clean-looking account line is still not a reason to paste the whole output into a ticket: even masked tokens and hostnames can leak useful operational detail.

3. Restrict the check to one host or account

For a machine that uses both github.com and an Enterprise hostname, name the host exactly:

$ gh auth status --hostname github.example.com
github.example.com
  ✓ Logged in to github.example.com account ACCOUNT_NAME (/home/USER/.config/gh/hosts.yml)
  - Active account: true
  - Git operations protocol: https

Use your real hostname. Replace github.example.com with the one from your own configuration, with no https:// or repository path.
Why bother narrowing it? A failure on one Enterprise installation would otherwise drown out a healthy public GitHub account in the same output.
Add --active when you need the account selected for normal operations, not every known account.

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

If the command prints no expected account, check the hostname spelling first, then inspect the configuration with the account-management commands documented by gh auth --help. Status never selects a different account for you. Only use gh auth switch once you have confirmed switching is what you actually want, and you have recorded how to switch back.

4. Use JSON for a scriptable check

Human-readable output is fine at a terminal, but a script should request the documented JSON field explicitly:

$ gh auth status --json hosts
{"hosts":[...]}

The contents are compact and host-specific, so treat ... above as a shape rather than literal output. Inspect the top-level host collection with the built-in filter:

$ gh auth status --json hosts --jq '.hosts | add'
[{...}]

The --jq expression is evaluated by GitHub CLI's own JSON formatting support. Quote expressions so the shell does not interpret punctuation. If a script needs a particular field, run the full --json hosts command on the installed version first and inspect its keys; do not assume a value missing from one host is present on another.

Warning

There is a subtle exit-status trap here. In normal human-readable mode, an authentication issue makes gh auth status exit with status 1 and write the issue to standard error. With --json, the command exits zero for an authentication issue unless it hits a fatal error. A JSON health check must inspect the returned data, not just the process status.

5. Capture diagnostics without leaking secrets

Separate standard output and standard error when investigating a failure:

$ gh auth status > /tmp/gh-auth-status.out 2> /tmp/gh-auth-status.err
$ status=$?
$ printf 'gh auth status exit: %s\n' "$status"
gh auth status exit: 1
$ sed -n '1,80p' /tmp/gh-auth-status.err

Those temporary files can contain account names, hostnames and diagnostic text. Read them locally, then remove them:

$ rm -- /tmp/gh-auth-status.out /tmp/gh-auth-status.err

Warning

This is the only deletion in the whole workflow. Confirm the two exact paths before running it, and never use a broad wildcard such as /tmp/*. If you need to keep a report, redact hostnames and account details, and make sure no token value was ever requested or captured.

Exit status 0 means the status check succeeded without an authentication issue in the mode you selected. Status 1 means an error or authentication issue. The manual also documents 2 for cancellation and 4 when authentication is required. A non-zero result does not tell you which repair is correct: check the reported host, account and the intended authentication method before changing anything.

6. Treat token output as a deliberate exception

--show-token prints the authentication token in plain text. Use it only for a controlled local diagnostic with a specific reason and a safe handling plan:

$ gh auth status --hostname github.example.com --show-token

Warning

Never run that form in a shared terminal, screen recording, CI log, shell transcript or copied support bundle, and never combine it with redirection, a command substitution or a pipeline that writes to a file. If a token has been exposed, treat it as compromised and revoke or replace it through the appropriate GitHub account settings or organisation process; the status command itself does not revoke, rotate or repair anything.

The JSON form can also include a plain-text token when combined with --show-token. Avoid the combination unless the same strict handling rules apply:

$ gh auth status --json hosts --show-token

For ordinary checks, leave the flag out. The masked token line in human-readable output is enough to tell a configured credential from a missing one, without exposing the secret itself.

7. Diagnose the usual failure paths

Narrow it first. If a host reports an authentication problem, rerun with --hostname to remove unrelated accounts from the output.
Check which account. If only a non-active account fails, add --active to see whether normal operations are actually affected.
Stop if the active account fails. Do not run commands that create releases, modify repositories or touch organisation data until it is fixed.

Work out whether the failure is local configuration or remote authentication: confirm the hostname is right, that the machine can reach the host, and that the account still has the required scopes. Network checks and account repair are separate jobs from status inspection. Do not delete the hosts file as a first response, since that removes local account configuration and can make recovery harder. If you eventually reach for gh auth logout or gh auth login, record the current host and account first and follow your organisation's credential policy.

When a script must fail on an authentication issue, use the human-readable command and its exit status, or parse JSON and apply an explicit policy to the returned host data. Never write a script that assumes a zero exit from --json proves every account is usable.

Done means

Version confirmed. You checked the installed GitHub CLI version and executable.
Hosts checked. All relevant hosts, or the exact host and active account you needed.
Exit codes understood. Normal status checks report authentication issues through exit status 1.
JSON caveat noted. JSON mode can exit zero despite an authentication issue, so scripts check the data itself.
No secrets exposed. You left --show-token out of ordinary commands.
Nothing changed. No login, account switch, logout or persistent configuration change happened.