gh-cache

List caches for the current repository

$ gh cache [[ls|list]]

$ gh cache [[ls|list]] [[-R|--repo]] [owner]/[repository]

$ gh cache [[ls|list]] [[-k|--key]] [key_prefix]

$ gh cache [[ls|list]] [[-r|--ref]] refs/heads/[branch_name]

$ gh cache [[ls|list]] [[-S|--sort]] last_accessed_at [[-O|--order]] asc

$ gh cache delete [cache_id]

$ gh cache delete [cache_key]

$ gh cache delete [[-a|--all]]

gh cache command [options]
gh cache list [flags]
gh cache delete <key> [flags]
gh cache download <key> [flags]

Common Flags:
    

-R, --repo <owner/repo>
    Selects a different repository for the operation using the [HOST/]OWNER/REPO format.

For list subcommand:
    Lists GitHub Actions caches.

-B, --ref <branch>
    Filters caches by the specified Git branch name.

-L, --limit <int>
    Limits the maximum number of caches to list.

-q, --query <string>
    Filters caches by a search query, typically on the cache key or path.

-S, --sort <SORT>
    Sorts fetched caches by last_accessed_at or size. Default is last_accessed_at.

-u, --user <string>
    Lists caches created by a specific user.

For delete subcommand:
    Deletes one or more GitHub Actions caches specified by key.

<key>
    The exact cache key to delete. Can accept multiple keys or patterns.

--dry-run
    Performs a dry run without actually deleting the cache(s).

For download subcommand:
    Downloads a GitHub Actions cache specified by key.

<key>
    The exact cache key to download.

-D, --dest <path>
    The path where the cache content will be extracted. Defaults to the current directory.

-a, --archive-path <path>
    The path where the raw cache archive will be downloaded to, without extraction.

The `gh cache` command, a subcommand of the GitHub CLI, provides functionalities to interact with GitHub Actions caches directly from the command line. It enables developers to list existing caches, view details about them, download cache content, and delete specific caches. This is particularly useful for debugging caching issues in CI/CD workflows, freeing up storage space, or manually inspecting cached dependencies.

Caching in GitHub Actions helps speed up workflow execution by reusing previously built dependencies or build outputs. The `gh cache` command makes cache management more accessible and efficient for users working with GitHub Actions.

Using `gh cache` requires the GitHub CLI (`gh`) to be installed and authenticated to your GitHub account.
Access to caches is subject to repository permissions, meaning you need appropriate access to view or modify caches.
Deleting caches is an irreversible operation, so proceed with caution.
The cache key matching logic is crucial; ensure your keys are correctly identified for listing, deleting, or downloading.

GitHub Actions caching allows you to store and reuse dependencies or build outputs between workflow runs. This significantly reduces the time taken to re-create the same dependencies, making your CI/CD pipelines faster and more efficient. Caches are identified by a unique key and can be restored if a matching key is found during subsequent workflow runs.

When a workflow run starts, GitHub Actions attempts to find a cache entry that matches the provided key. It supports exact matches and, for some actions, prefix matches. If no exact match is found, it looks for a partial match based on a list of fallback keys. Understanding how cache keys are formed and matched is vital for effective caching strategies and using `gh cache` effectively.

The `gh cache` functionality was introduced as part of the GitHub CLI to provide better management and debugging capabilities for GitHub Actions caches. It reflects the growing importance of CI/CD workflows and cache optimization in modern development. By extending the existing `gh actions` commands, it makes direct cache interaction more accessible and powerful from the command line, complementing the web interface and GitHub Actions workflow syntax.

gh(1), gh actions(1), git(1)