crane-catalog

List the repositories in a registry

$ crane catalog [registry_address]

$ crane catalog [registry_address] --full-ref

$ crane catalog [[-h|--help]]

crane catalog registry [flags]

registry
    The mandatory positional argument specifying the address of the container registry to query (e.g., gcr.io, docker.io, my.private.registry:5000).

--help, -h
    Displays help information for the catalog command.

--insecure
    Allows communication with insecure registries that do not use HTTPS. Use with caution.

--json
    Outputs the list of repositories in JSON format, which is useful for scripting and programmatic parsing.

--key string
    Specifies a path to a key file, typically for signing operations (less common for catalog).

--plain-http
    Forces the use of plain HTTP instead of HTTPS for requests, bypassing TLS/SSL. Similar to --insecure.

--token string
    Provides an authentication token for accessing private registries (e.g., an access token from gcloud auth print-access-token).

--username string
    Specifies the username for basic authentication with a private registry.

--password string
    Specifies the password for basic authentication with a private registry. It's generally recommended to avoid putting passwords directly on the command line for security reasons.

crane-catalog is a powerful subcommand of the crane CLI tool, which is part of the go-containerregistry project. Its primary function is to query a specified container registry and retrieve a comprehensive list of all available repository names. This command is invaluable for discovery, auditing, and managing content within a registry, providing a quick overview of what images are stored. It achieves this by typically leveraging the registry's standard /v2/_catalog API endpoint, offering a programmatic way to explore registry contents without needing to pull individual images.

API Support: Not all container registries fully implement the Docker Registry HTTP API V2 /v2/_catalog endpoint, or they might disable it for security or performance reasons. In such cases, crane-catalog may fail to list repositories or return an incomplete list.

Authentication: Accessing private registries requires proper authentication. crane-catalog supports various methods (username/password, tokens, Docker config files), but misconfiguration will lead to access denied errors.

Large Registries: Querying very large registries might be slow, return truncated results if the registry has pagination limits not fully handled by the client, or if the command times out. Network conditions also play a role.

crane-catalog can authenticate using standard Docker configuration files (e.g., ~/.docker/config.json), environment variables like DOCKER_CONFIG, or explicitly via the --username, --password, and --token flags. For cloud-based registries like Google Container Registry (GCR) or Artifact Registry, it often leverages credentials obtained via cloud provider CLI tools (e.g., gcloud) that populate the Docker config.

The command's functionality is directly dependent on the target registry's implementation of the Docker Registry HTTP API V2, specifically the GET /v2/_catalog endpoint. If this endpoint is not exposed or enabled by the registry, crane-catalog will not be able to list repositories.

crane and its subcommands, including crane-catalog, are integral parts of the go-containerregistry project. This project, primarily developed and open-sourced by Google, provides a robust Go library and command-line tools for programmatically working with OCI (Open Container Initiative) and Docker registries. It gained popularity as a lightweight, Go-native alternative or complement to traditional container tools like docker and podman for scriptable registry interactions, making it especially useful in CI/CD pipelines and automation workflows.

crane(1), docker(1), podman(1), reg(1)