> ## Documentation Index
> Fetch the complete documentation index at: https://chatcli.edilsonfreitas.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Image Tags (@registry-tags)

> Lists the tags published for a container image across public and private OCI registries (Docker Hub, GCR, GHCR, Quay, ACR, Harbor, Artifactory) — keyless, without pulling the image.

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.

<Tip>
  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`.
</Tip>

***

## Usage

```text theme={"system"}
<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)* |

<Warning>
  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.
</Warning>

***

## Credentials

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

<Steps>
  <Step title="Explicit arguments">
    `username`/`password` or `token` passed in the call.
  </Step>

  <Step title="~/.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.)
  </Step>

  <Step title="Environment variables">
    `REGISTRY_USERNAME` / `REGISTRY_PASSWORD` / `REGISTRY_TOKEN`.
  </Step>
</Steps>

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:

```text theme={"system"}
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).

<Tip>
  Combine it with the [Scheduler](/tools/scheduler) and `@send` to get notified when a new tag of a base image you track is published.
</Tip>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.