List Your GitHub GPG Keys with gh

A stray scope error is the most common surprise from gh gpg-key list, and this guide checks the keys and fixes that error cleanly. Allow about five minutes. The listing itself is read-only, but refreshing authentication changes the scopes on 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 install reporting gh 2.87.3. That distinction matters when package documentation and executable behaviour disagree. 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 run queries the active account for the selected host. Check that account before you interpret the keys, especially on a workstation with more than one GitHub login stored:

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

Replace YOUR_LOGIN only in your notes, never 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 just diagnostic metadata.

3. List the account's GPG keys

Run the read-only listing command:

$ GH_PAGER=cat gh gpg-key list

Rows and column labels are account-dependent. No registered keys means no rows at all, not an error. 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 keeps a one-shot terminal check out of an interactive pager, which helps in scripts and when a reader is following along by copy and paste. It changes nothing about 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

That is an authorisation problem, not proof the account has no keys. The documented fix adds the read:gpg_key scope to the active credentials:

$ gh auth refresh -s read:gpg_key

This changes stored authentication state and normally asks you to authorise the extra scope in a browser or device flow. Check the host and active account first. Do not reach for --insecure-storage just to make a scope error go away: 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

Granted the scope to the wrong login: stop rather than piling on more permissions. Switch to the intended account, then refresh that one instead. To undo an unnecessary scope, use the supported gh auth refresh --remove-scopes read:gpg_key operation where your authentication flow allows it, or remove the credential through your normal GitHub account-management process. Removing a scope can affect other commands, so check what else uses it first.

5. Distinguish common failures

A non-zero exit status means the listing did not finish 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"

• Scope error. Use the refresh procedure from step 4.
• Authentication error. Run gh auth status --active --hostname github.com and repair the login before touching scopes.
• Network or API error. Retry later and check the host setting. Do not assume an empty-looking result is a valid empty key list until the command actually exits successfully.

There is no undo operation for gh gpg-key list, because it never adds, edits or deletes a key. Keep the separate destructive command gh gpg-key delete out of scripts meant only to audit keys: deleting a key changes the GitHub account and sits outside this guide entirely.