Add kernels cache ls to list cached kernels with their versions/refs and build variants #930

Motivation

Right now the only way to see which kernels are on disk is hf cache ls. That command lists repos and refs, including multiple refs per repo, but it doesn't show which build variants (e.g. torch28-cxx11-cu128-x86_64-linux) of each kernel version are actually in the cache. For kernels, the variant is usually what matters: it tells you whether a cached kernel will load in your current environment, or whether it's going to be downloaded again.

This came up while reworking the Basic usage docs. The hf cache ls hint there isn't very useful for kernels as it stands, and we'd like a cache section that points to a kernels-specific tool.

Proposal

Add a kernels cache ls subcommand that lists, for each cached kernel repo:

• repo id
• cached versions / refs (branch, tag, vX version) and the revision they resolve to
• build variants present for each revision
• size on disk (nice to have)
• optionally, which variant the current environment would select (could reuse the logic behind kernels variants)

It should respect the same cache configuration as get_kernel (HF_HUB_CACHE / kernels cache env vars).

Later we could add kernels cache rm (e.g. to prune unused variants), but that's out of scope here.

Related

• Document kernels cache a bit more #838 (document the kernels cache better). The docs could point to this command once it exists.

Requested by Sayak Paul - Slack thread - Agent trace