> ## 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.

# Tags de Imagens (@registry-tags)

> Lista as tags publicadas de uma imagem de contêiner em registries OCI públicos e privados (Docker Hub, GCR, GHCR, Quay, ACR, Harbor, Artifactory) — keyless, sem baixar a imagem.

O tool **`@registry-tags`** lista as tags publicadas de uma imagem de contêiner em registries OCI públicos e privados -- **Docker Hub, GCR, GHCR, Quay, ACR, Harbor e Artifactory**. É **keyless** para imagens públicas e lê o `~/.docker/config.json` para as privadas. **Nenhuma imagem é baixada** -- só a API read-only de tags do registry é consultada, então é rápido e sem efeito colateral.

<Tip>
  Use antes de referenciar um `image:tag` num `Dockerfile`, chart Helm ou manifesto Kubernetes -- assim você confirma que a tag existe (e descobre quais existem) sem `docker pull`.
</Tip>

***

## Uso

```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"}' />
```

O registry é inferido a partir da referência da imagem; o Docker Hub é o default quando não há host. O LLM invoca `@registry-tags` automaticamente quando precisa validar ou descobrir tags.

### Argumentos

| Argumento  | Descrição                                                                                                               | Default                |
| :--------- | :---------------------------------------------------------------------------------------------------------------------- | :--------------------- |
| `image`    | Referência da imagem (obrigatório). Ex.: `redis`, `library/nginx`, `ghcr.io/cli/cli`, `myreg.example.com/team/app`      | *(obrigatório)*        |
| `registry` | Sobrescreve a URL base do registry (ex.: `https://harbor.example.com`)                                                  | *(inferido da imagem)* |
| `username` | Usuário do registry (imagens privadas)                                                                                  | *(opcional)*           |
| `password` | Senha/token pareado com `username`                                                                                      | *(opcional)*           |
| `token`    | Bearer token pré-emitido (PAT do GHCR, OAuth do GCR, robot token do Harbor)                                             | *(opcional)*           |
| `limit`    | Máximo de tags retornadas                                                                                               | `200` (teto `1000`)    |
| `sort`     | Ordena antes de truncar: `newest` (maior versão primeiro) · `oldest` · `name` · `pushed` (último pushado primeiro, OCI) | *(ordem do registry)*  |
| `last`     | Atalho: as N tags mais recentes (equivale a `sort=newest`, `limit=N`)                                                   | *(opcional)*           |

<Warning>
  Registries OCI como o **GHCR** listam as tags em ordem de push (mais antigas primeiro). Sem `sort`, o `@registry-tags` retorna as **primeiras** N — então as versões novas ficam de fora. Use `sort: "newest"` (ou `last: 10`): a busca **pagina até o fim**, ordena por versão (semver) e então corta para o `limit`. `newest`/`oldest` usam um comparador semver próprio (release > pre-release; tags não-versionadas vão por último); `pushed` inverte a ordem do registry.
</Warning>

***

## Credenciais

Credenciais são **opcionais**. Quando omitidas, a ordem de resolução é:

<Steps>
  <Step title="Argumentos explícitos">
    `username`/`password` ou `token` passados na chamada.
  </Step>

  <Step title="~/.docker/config.json">
    A entrada `auths` (base64) ou `identitytoken` do registry correspondente -- exatamente como o `docker` e o `crane` leem. (Os helpers `credsStore`/`credHelpers` não são invocados.)
  </Step>

  <Step title="Variáveis de ambiente">
    `REGISTRY_USERNAME` / `REGISTRY_PASSWORD` / `REGISTRY_TOKEN`.
  </Step>
</Steps>

Imagens públicas não precisam de credencial alguma.

### Registries que gateiam leitura anônima

GHCR, Quay e GCR exigem um token mesmo para ler tags públicas. O `@registry-tags` faz a **negociação de Bearer token** do padrão OCI automaticamente (lê o desafio `WWW-Authenticate`, pega o token no realm e repete a chamada), então essas imagens retornam tags sem você configurar nada.

***

## Saída

Uma tag por linha, com cabeçalho de imagem/host/contagem. Quando o número de tags excede o `limit`, a saída é truncada e o aviso é indicado:

```text theme={"system"}
redis (hub.docker.com) — 200 tag(s), truncado em 200
7.4.1
7.4.0
7.2-alpine
...
```

***

## Notas

* É **read-only** e concurrency-safe -- o orquestrador pode rodar vários `@registry-tags` em paralelo.
* Segue paginação (Docker Hub `next`, OCI `Link`) até o `limit`, em vez de truncar silenciosamente na primeira página.
* Usa o cliente HTTP compartilhado das web tools: respeita proxy corporativo (`HTTPS_PROXY`) e o trust de TLS global (`CHATCLI_CA_BUNDLE`).
* Registries internos (`registry.empresa.com`, `localhost:5000`) funcionam -- só endpoints de metadata de nuvem são bloqueados (proteção SSRF).

<Tip>
  Combine com o [Scheduler](/pt/features/scheduler) e o `@send` para ser avisado quando uma nova tag de uma imagem base que você acompanha for publicada.
</Tip>