Inspect GitHub Actions Caches with gh cache list

Before you touch gh cache delete, run gh cache list first: it only reads, and every filter you learn here becomes an argument you can trust later. You will finish able to narrow the list to a key or ref, sort it by age or size, and request machine-readable fields. Allow about ten minutes.

1. Check the installed command

Start with read-only checks. Neither command needs elevated privileges:

$ gh --version
gh version 2.87.3 (2026-02-23)
$ gh cache list --help

Checkpoint: if gh --version fails, install or repair GitHub CLI through your normal system-management process. Do not work around a missing binary by downloading an unverified script.

2. List caches for the current repository

Run the command from a checked-out GitHub repository:

$ gh cache list

With a valid repository and suitable authentication, gh requests the repository's Actions caches and prints a table. The exact rows depend on the repository and can change while workflows run. A successful empty result means there are no caches matching the request, not that the command deleted anything.

If the directory is not the repository you meant, make the target explicit instead:

$ gh cache list --repo OWNER/REPO

Replace OWNER/REPO with a real owner and repository. The inherited --repo option also accepts HOST/OWNER/REPO for another GitHub host.

3. Filter by cache key or ref

Cache keys are often long strings containing an operating-system or dependency version. Use --key to match a key prefix, or an exact key when the supplied value identifies one:

$ gh cache list --key linux-npm-
$ gh cache list --repo OWNER/REPO --key linux-npm-node20-

For a branch, pass the full ref form the command requires:

$ gh cache list --ref refs/heads/BRANCH_NAME

For a pull request merge ref, use its number:

$ gh cache list --repo OWNER/REPO --ref refs/pull/123/merge

Tip: do not pass only main or 123 to --ref. The local help specifies refs/heads/ for branches and refs/pull/<number>/merge for pull requests. Combine filters before increasing the limit; that keeps the result focused and stops you mistaking the default 30-row cap for the total number of matching caches.

4. Sort by age or size

Choose one of the three supported sort fields: created_at, last_accessed_at, or size_in_bytes. The default is most recently accessed first. To find caches that have not been used recently, reverse that order:

$ gh cache list --sort last_accessed_at --order asc

To see the largest returned caches first:

$ gh cache list --sort size_in_bytes --order desc

Sorting happens on the caches fetched for the request, and --limit controls the maximum number fetched. Set it deliberately when investigating a larger repository:

$ gh cache list --limit 100 --sort size_in_bytes --order desc

The limit is a maximum, not a promise that many rows exist. Use a positive integer that fits the investigation. Do not assume the first 30 caches represent all caches unless you have checked the limit and filters.

5. Request stable fields for scripts

Human-readable tables are useful for a quick check, but scripts should request named JSON fields rather than parse columns. This asks for the cache identifier, key, ref and size:

$ gh cache list --repo OWNER/REPO \
    --json id,key,ref,sizeInBytes

The installed help lists these JSON field names: createdAt, id, key, lastAccessedAt, ref, sizeInBytes, and version. Request only what the next step needs; field names are case-sensitive on the command line.

For a compact report, apply gh's built-in jq expression to the JSON result:

$ gh cache list --json key,ref,sizeInBytes \
    --jq '.[] | [.key, .ref, .sizeInBytes] | @tsv'

The expression is evaluated by gh, so this example does not need a separate jq executable. It assumes the JSON result is an array of cache records, which is the shape this command's JSON mode produces. If you change the selected fields, update the expression to match them.

Use a Go template when you need a different presentation and already know gh's formatting rules:

$ gh cache list --json key,ref --template '{{range .}}{{.key}}{{"	"}}{{.ref}}{{"\n"}}{{end}}'

Listing is read-only, but a later maintenance script may take these cache IDs to gh cache delete: review that command independently before you run it, and keep data output separate from destructive commands.

6. Diagnose an empty or failed result

First confirm the selected repository and authentication, without changing configuration:

$ gh repo view --json nameWithOwner
$ gh auth status

Done means