Refresh gh Credentials Without Losing Scopes

A command suddenly demands a scope your token does not have, and gh auth refresh fixes it without forcing a full re-login from scratch. This guide adds or removes OAuth scopes on stored GitHub CLI credentials and confirms the intended account and host actually changed. The examples match GitHub CLI 2.87.3, installed here in package gh. Allow about ten minutes, plus however long your browser sign-in takes.

You need an existing gh login and access to the GitHub account whose credentials you are changing. This guide changes stored authentication state, so read the command before pressing Enter. It does not need sudo; use an ordinary user shell so the credentials belong to the account that normally runs gh.

1. Check the installed command

Confirm the binary and version first. This is a read-only checkpoint:

$ command -v gh
/usr/bin/gh
$ gh --version
gh version 2.87.3 (2026-02-23)

Your version may differ, and the local manual is the authority for the command installed on your machine. Check the refresh-specific options before using an older or newer installation in a script:

$ gh auth refresh --help

Do not confuse gh auth refresh with gh auth login. Refresh works on stored credentials and changes their permission scopes; it does not create a new GitHub account.

2. Identify the account and host

Inspect the current login without changing it:

$ gh auth status
github.com
  ✓ Logged in to github.com account ACCOUNT_NAME
  - Active account: true
  - Git operations protocol: https
  - Token scopes: ...

Account name, active marker and scope list are host-specific: treat this as a checkpoint, not as text to paste into another command. On GitHub Enterprise, record the exact hostname and pass it explicitly later:

$ gh auth status --hostname github.example.com
$ gh auth refresh --hostname github.example.com --scopes read:project

3. Add only the scopes you need

Use --scopes with a comma-separated list. This example requests organisation write access and public-key read access:

$ gh auth refresh --scopes write:org,read:public_key

The command opens a browser authentication flow. Complete it in the account and host you checked in the previous step. Requested scopes are additional, not a replacement list; run refresh without --scopes and previously added scopes are kept.

When the command returns, check the stored result:

$ gh auth status
# Confirm the expected host, active account and scopes in the output

Do not treat a successful browser sign-in as proof that a particular scope was granted; compare the scope output with the permission you actually require. If the browser flow is unsuitable for your terminal, version 2.87.3 also provides --clipboard, which copies a one-time OAuth device code to the clipboard.

4. Remove an unnecessary scope

Removing a scope is the safer direction once a temporary task has finished. Pass the scope name to --remove-scopes:

$ gh auth refresh --remove-scopes delete_repo

The operation is idempotent, so requesting removal again does not require the scope to be present first, though it still opens a browser flow because the stored credentials must be refreshed. Verify the result:

$ gh auth status
# Confirm delete_repo is no longer listed for the active account

The minimum set of scopes, repo, read:org and gist, cannot be removed with this command. A failed attempt to remove one of them is a scope boundary, not a reason to try a different spelling or reach for elevated privileges.

5. Reset to the default minimum set

Use --reset-scopes to discard additional scopes and re-authenticate with the default minimum set:

$ gh auth refresh --reset-scopes

There is no undo command for a reset. Recovery means refreshing again with each required scope, for example:

$ gh auth refresh --scopes read:project,workflow

Use the smallest set that supports the work. Do not copy this example unchanged unless both scopes are genuinely required by your workflow.

6. Handle multiple accounts carefully

gh auth refresh operates on the active account. If gh auth status shows multiple accounts and you need to refresh an inactive one, switch to it first:

$ gh auth switch
# Select the intended account when prompted
$ gh auth status
# Confirm that the intended account is active
$ gh auth refresh --scopes SCOPE_NAME
$ gh auth switch
# Select the account you normally use again
$ gh auth status

Exact prompts and account names depend on your configuration. Do not assume the last account listed is active. If a refresh lands on the wrong account, switch to it and use --remove-scopes for the unwanted scope, then return to the intended account.

7. Avoid leaking refreshed credentials

Leave credential storage in its normal mode unless you have a specific, documented reason to change it. --insecure-storage saves credentials in plain text instead of a credential store; that weakens local protection and is not a general fix for a failed refresh. Do not use it on a shared machine merely to make the command complete.