> ## 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](/features/scheduler) and `@send` to get notified when a new tag of a base image you track is published.
</Tip>