List Your GitHub GPG Keys with gh, Including the Scope Fix

You will check the GPG keys registered to the active GitHub account with gh gpg-key list, and recover cleanly if the stored credentials do not have permission to read them. Allow about five minutes. The listing is read-only, but refreshing authentication changes the scopes attached to your stored credentials and may open a browser authorisation flow.

1. Check the installed command

You need GitHub CLI, an account authenticated for the GitHub host you intend to query, and access to that account's GPG-key settings. The Debian package database on this machine reports gh 2.45.0-1ubuntu0.3+esm3, but the executable found first on PATH is a Homebrew installation reporting gh 2.87.3. That distinction matters when package documentation and executable behaviour differ. Confirm the binary and its help text before putting the command into a script:

$ command -v gh
/home/linuxbrew/.linuxbrew/bin/gh
$ gh --version
gh version 2.87.3 (2026-02-23)
https://github.com/cli/cli/releases/tag/v2.87.3
$ gh gpg-key list --help
Lists GPG keys in your GitHub account

The installed manual gives the same basic syntax: gh gpg-key list [flags]. In this release, the subcommand has no command-specific flags. Do not add output-format, account-selection or filtering options unless your installed help explicitly shows them.

2. Confirm which account is active

A successful command queries the active account for the selected host. Check that account before interpreting the keys, especially on a workstation where more than one GitHub login is stored:

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

Replace YOUR_LOGIN only in your notes, not in the command. The exact status wording varies by CLI version and credential store. Never use --show-token while copying output into a terminal log or support ticket. It prints a credential, not merely diagnostic metadata.

3. List the account's GPG keys

Run the read-only listing command:

$ GH_PAGER=cat gh gpg-key list

The rows and column labels are account-dependent. An account with no registered keys may produce no key rows, while a successful response with several keys will contain one row per key. Treat the identifiers and timestamps as account data: avoid pasting them into a public issue unless the owner has agreed.

GH_PAGER=cat is optional. It makes a one-shot terminal check avoid an interactive pager, which is useful in scripts and when a returning reader is following a copy-and-paste example. It does not alter GitHub data or the stored authentication token.

4. Fix the missing-scope error

On this machine, the command reached GitHub but failed with:

Error: insufficient OAuth scopes to list GPG keys
Run the following to grant scopes: gh auth refresh -s read:gpg_key

This is an authorisation problem, not evidence that the account has no keys. The documented remedy is to add the read:gpg_key scope to the active credentials:

$ gh auth refresh -s read:gpg_key

This command changes stored authentication state and normally asks you to authorise the additional scope in a browser or device flow. Check the host and active account first. Do not use --insecure-storage merely to solve a scope error: that option can save credentials in plain text.

After the refresh completes, verify the account and retry the listing:

$ gh auth status --active --hostname github.com
$ GH_PAGER=cat gh gpg-key list

If you granted the scope to the wrong login, stop rather than adding more permissions. Switch to the intended account, then refresh that account. To undo an unnecessary scope, use the supported gh auth refresh --remove-scopes read:gpg_key operation when your authentication flow permits it, or remove the credential through your normal GitHub account-management process. Removing a scope can affect other commands, so check its use before doing so.

5. Distinguish common failures

A non-zero exit status means the listing did not complete successfully. Capture it without hiding the error:

$ GH_PAGER=cat gh gpg-key list
$ status=$?
$ printf 'gh gpg-key list exit status: %s\n' "$status"

For a scope error, use the refresh procedure above. For an authentication error, run gh auth status --active --hostname github.com and repair the login before changing scopes. For a network or GitHub API error, retry later and check the host setting; do not assume that an empty-looking result is a valid empty key list until the command exits successfully.

There is no undo operation for gh gpg-key list because it does not add, edit or delete a key. Keep the separate destructive command gh gpg-key delete out of scripts intended only to audit keys. Deleting a key changes the GitHub account and is outside this guide.