Image Tags (@registry-tags)

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

Argument	Description	Default
`image`	Image reference (required). E.g. `redis`, `library/nginx`, `ghcr.io/cli/cli`, `myreg.example.com/team/app`	(required)
`registry`	Override the registry base URL (e.g. `https://harbor.example.com`)	(inferred from image)
`username`	Registry username (private images)	(optional)
`password`	Password/token paired with `username`	(optional)
`token`	Pre-issued Bearer token (GHCR PAT, GCR OAuth, Harbor robot token)	(optional)
`limit`	Maximum number of tags returned	`200` (cap `1000`)
`sort`	Order before truncating: `newest` (highest version first) · `oldest` · `name` · `pushed` (most recently pushed first, OCI)	(registry order)
`last`	Shorthand: the N most recent tags (equals `sort=newest`, `limit=N`)	(optional)

OCI registries like GHCR list tags in push order (oldest first). Without sort, @registry-tags returns the first N — so the newest versions are left out. Use sort: "newest" (or last: 10): the fetch reads every page, sorts by version (semver), then truncates to limit. newest/oldest use a self-contained semver comparator (a release outranks its pre-release; non-versioned tags sort last); pushed reverses the registry order.

Credentials

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

Explicit arguments

username/password or token passed in the call.

~/.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.)

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.

Home

Getting Started

Core Concepts

Features

Security

Support

Image Tags (@registry-tags)

Usage

Arguments

Credentials

Registries that gate anonymous reads

Output

Notes

​Usage

​Arguments

​Credentials

​Registries that gate anonymous reads

​Output

​Notes

Usage

Arguments

Credentials

Registries that gate anonymous reads

Output

Notes