Skip to main content
The @registry-tags tool lists the tags published for a container image across public and private OCI registries — Docker Hub, GCR, GHCR, Quay, ACR, Harbor and Artifactory. It is keyless for public images and reads ~/.docker/config.json for private ones. No image is pulled — only the registry’s read-only tags API is queried, so it is fast and side-effect free.
Use it before referencing an image:tag in a Dockerfile, Helm chart or Kubernetes manifest — you confirm the tag exists (and discover which ones do) without a docker pull.

​
Usage

<tool_call name="@registry-tags" args='{"image":"redis"}' />
<tool_call name="@registry-tags" args='{"image":"ghcr.io/cli/cli"}' />
<tool_call name="@registry-tags" args='{"image":"myreg.example.com/team/app","username":"robot","password":"$REG_PASS"}' />
The registry is inferred from the image reference; Docker Hub is the default when there is no host. The LLM invokes @registry-tags automatically when it needs to validate or discover tags.

​
Arguments

ArgumentDescriptionDefault
imageImage reference (required). E.g. redis, library/nginx, ghcr.io/cli/cli, myreg.example.com/team/app(required)
registryOverride the registry base URL (e.g. https://harbor.example.com)(inferred from image)
usernameRegistry username (private images)(optional)
passwordPassword/token paired with username(optional)
tokenPre-issued Bearer token (GHCR PAT, GCR OAuth, Harbor robot token)(optional)
limitMaximum number of tags returned200 (cap 1000)

​
Credentials

Credentials are optional. When omitted, the resolution order is:
1

Explicit arguments

username/password or token passed in the call.
2

~/.docker/config.json

The auths entry (base64) or identitytoken for the matching registry — exactly how docker and crane read it. (The credsStore/credHelpers helpers are not invoked.)
3

Environment variables

REGISTRY_USERNAME / REGISTRY_PASSWORD / REGISTRY_TOKEN.
Public images need no credentials at all.

​
Registries that gate anonymous reads

GHCR, Quay and GCR require a token even to read public tags. @registry-tags performs the OCI Bearer-token negotiation automatically (it reads the WWW-Authenticate challenge, fetches the token from the realm and retries the call), so those images return tags with no setup on your side.

​
Output

One tag per line, with an image/host/count header. When the number of tags exceeds limit, the output is truncated and the truncation is flagged: 
redis (hub.docker.com) — 200 tag(s), truncated at 200
7.4.1
7.4.0
7.2-alpine
...

​
Notes

  • It is read-only and concurrency-safe — the orchestrator can run several @registry-tags in parallel.
  • It follows pagination (Docker Hub next, OCI Link) up to limit, instead of silently truncating at the first page.
  • It uses the shared web-tools HTTP client: it honors the corporate proxy (HTTPS_PROXY) and the global TLS trust (CHATCLI_CA_BUNDLE).
  • Internal registries (registry.company.com, localhost:5000) work — only cloud metadata endpoints are blocked (SSRF protection).
Combine it with the Scheduler and @send to get notified when a new tag of a base image you track is published.