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.

• You need: GitHub CLI and authentication that can read Actions data for the repository.
• What it touches: nothing. The examples below do not delete or change repository data. The examples use gh 2.87.3, installed here on 23 September 2026; check your own version, since flags and output fields can change between releases.

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

• There is a shorter alias. The command is also available as gh cache ls.
• Defaults matter. The help output is the local contract for this installation: the default limit is 30 caches, the default sort is last_accessed_at, and the default order is descending.

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

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

• Wrong repository? Rerun with --repo OWNER/REPO.
• Missing or insufficient authentication? Sign in through your organisation's approved GitHub CLI process. Never paste a token into shell history or into this command's arguments.
• Empty result? Remove one filter at a time. Start with gh cache list --repo OWNER/REPO, then add --ref, --key, sorting and formatting separately. A branch filter that omits refs/heads/, a pull request ref with the wrong number, or a key that is not a prefix are the common causes.
• Result too large? Lower the noise with a specific key or ref before raising --limit.
• Request failed? Keep the error text and check the repository name, host and account access. Elevated privileges will not repair a GitHub permission or API problem, so do not reach for sudo on these commands.