Clear GitHub CLI's Local Cache Without Touching Authentication

GitHub CLI's local cache goes stale after a token or repository change, and gh config clear-cache clears it in under a second. This guide runs the command, checks the result, and tells you when to stop troubleshooting and look elsewhere. The installed package here is GitHub CLI 2.87.3, released on 23 February 2026, matching the gh-config-clear-cache(1) manual page.

Allow about five minutes. You need a shell and a working gh installation. The command does not need a repository, a GitHub network connection or elevated privileges in the normal case.

1. Check the installed command

Confirm which executable and version you are about to use:

$ 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

Your path and release may differ. If more than one gh is installed, resolve that first. A shell can find a different binary from the one you expected, especially after installing a package manually or changing PATH.

Checkpoint: continue only if gh --version completes successfully and identifies the installation whose cache you intend to clear.

2. Understand the boundary before clearing

gh config clear-cache clears GitHub CLI's local CLI cache. It is not the GitHub Actions cache command, and it is not a general cleanup command for repositories, build artefacts or operating-system caches. It also is not a sign-out operation: do not use it when your goal is to remove an account or credential.

The subcommand has no positional arguments or cache-name selector. The only flag shown by the installed help is the inherited --help flag. That means the operation applies to the CLI cache as a whole rather than to one named entry.

Warning: cached data will need to be fetched or rebuilt when a later gh command needs it. The clear operation is not a destructive change to a repository, but it is still a state change in your user configuration area. Close scripts or interactive gh work that should not race with it.

3. Clear the cache

Run the command as your ordinary user:

$ gh config clear-cache
Cleared the cache

On GitHub CLI 2.87.3, a successful run prints Cleared the cache and returns exit status 0. The command does not ask for confirmation in this version. Do not add sudo just because the word "cache" appears in the command. Running it as root would target root's GitHub CLI configuration rather than repair your user's installation.

Checkpoint: if you need the status in a script, capture it immediately after the command:

gh config clear-cache
status=$?
if [ "$status" -ne 0 ]; then
    printf 'gh config clear-cache failed with status %s\n' "$status" >&2
    exit "$status"
fi
printf '%s\n' 'GitHub CLI cache cleared'

Do not test only for the tick in displayed output. Output can be redirected, changed by a future release or hidden by the calling environment; the exit status is the reliable script decision.

4. Verify with a harmless follow-up

There is no cache-list command in this manual entry, and clearing an empty cache is still a valid operation. Verify the command itself and that the CLI remains usable:

$ gh config clear-cache
Cleared the cache
$ gh config list
git_protocol: https
prompt: enabled

The exact lines from gh config list depend on your settings, so do not compare the example as a complete expected file. The useful check is that the follow-up command runs. Configuration settings and authentication are separate concerns from this cache operation. If your installation uses a different set of settings, that is not evidence that the clear failed.

For a minimal verification in automation, use the exit status of the clear command and then run the specific read-only gh operation your job needs. Avoid a network request merely to prove that a local cache was cleared.

5. Diagnose failures without making them worse

If the command returns non-zero or cannot write its cache location, read the error text and check the executable and environment first:

$ command -v gh
$ gh --version
$ gh config clear-cache
$ printf '%s\n' "$?"

Do not delete the whole configuration directory by hand as a first response. That can remove settings or credentials that you did not intend to touch, and it is not the operation documented by gh-config-clear-cache(1). Do not retry with sudo unless an administrator has deliberately configured a shared installation and understands which user's cache should change.

If the next GitHub CLI command is slower, that is an expected consequence of an empty local cache. Let it repopulate. If a command still fails after the cache has been rebuilt, investigate that command's own authentication, repository, network or API error rather than repeatedly clearing the cache. Re-running this command is safe but cannot fix an expired token, a missing repository or a service outage.

There is no undo command for restoring discarded cached entries. The practical recovery is to run the affected gh command again and allow it to recreate the data. Your original repository files remain the recovery source for repository work; do not confuse this local cache with GitHub Actions caches, which are managed by the separate gh cache command family.

Done means