Refresh gh Credentials Without Losing the Right Scopes

You will finish with a repeatable way to refresh GitHub CLI credentials, add or remove OAuth scopes, and confirm that the intended account and host were 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. 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: ...

The account name, active marker and scope list are host-specific. Treat the output as a checkpoint, not as text to paste into another command. If you use 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

Refreshing credentials is security-sensitive. A scope can permit actions that the account could not previously perform. If the result is not meant for the active account, stop here and do not continue.

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. The requested scopes are additional scopes; they are not a replacement list. If you run refresh without --scopes, previously added scopes are maintained.

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 when 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. 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 use elevated privileges.

5. Reset to the default minimum set

Use --reset-scopes when you want to discard additional scopes and re-authenticate with the default minimum set for the authentication flow:

$ gh auth refresh --reset-scopes

This is a destructive credential change: permissions needed by a later command may disappear. Record the current scope list first if you may need to restore it. After completing the browser flow, run gh auth status and confirm that the additional scopes are gone.

There is no undo command for a reset. Recovery means refreshing again with each required additional 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

The exact prompts and account names depend on your configuration. Do not assume that the last account listed is active. If a refresh was applied to the wrong account, switch to that account 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. The --insecure-storage flag 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.

Do not put tokens, one-time device codes or complete authentication output in shell history, tickets or chat. If a refresh fails, capture the error without copying secret-shaped values and check the host, active account, network connection and browser session. Repeating the same refresh is less useful than confirming which account and OAuth flow you are actually using.