regctl

regctl [global options] <command> [command options] [arguments]

Common Commands:
  regctl pull [options] <image_ref> [<file_path>]
  regctl push [options] <file_path> <image_ref>
  regctl manifest get [options] <image_ref>
  regctl login [<registry>]
  regctl blob get [options] <image_ref> <digest>

-c, --config <path>
    Specify an alternate configuration file for credentials and settings.

--host-platform <os/arch>
    Set the host platform for local image/manifest operations, e.g., 'linux/amd64'.

--platform <os/arch>
    Specify the target platform for manifest operations (e.g., manifest get/create).

-v, --verbose
    Enable verbose output for debugging and detailed operation information.

--user-agent <string>
    Set the User-Agent header for HTTP requests to the registry.

--insecure
    Allow communication with registries over insecure HTTP or with unverified HTTPS certificates.

--skip-config-hosts
    Do not load host-specific configuration from the config file.

--log-format <format>
    Set log output format (text, json).

--log-level <level>
    Set log level (trace, debug, info, warn, error).

regctl is a powerful and versatile command-line interface (CLI) tool designed for deep interaction with OCI (Open Container Initiative) compatible registries. Written in Go, it offers a granular level of control over various registry components, including images, manifests, blobs, repositories, and tags. Unlike higher-level container clients like docker or podman that abstract away much of the registry interaction, regctl provides direct access to the registry's API, making it an indispensable tool for automation, scripting, and advanced registry management tasks.

Key functionalities include pulling and pushing images, creating and manipulating image manifests (including multi-platform manifests), managing individual blobs, and listing or deleting repositories and tags. It supports authentication mechanisms for secure registry access and can work with both local and remote registries. Its design emphasizes headless operations, making it ideal for CI/CD pipelines, custom registry solutions, and scenarios requiring precise control over image data stored in OCI registries.

While regctl offers powerful low-level control, users should be aware of several considerations:

Security: Direct interaction with registry APIs means that improper handling of credentials or using the --insecure flag can expose sensitive data. Always use secure practices and strong authentication.

Complexity: Its granular control can be more complex than higher-level tools for simple tasks. Understanding OCI specifications (manifests, blobs, layers) is beneficial for effective use.

No Image Execution: regctl is purely for registry interaction; it does not build, run, or manage containers or images on a local host filesystem directly (beyond pulling/pushing content). For these tasks, tools like docker, podman, or crictl are required.

regctl is designed from the ground up for scripting and automation. Its command structure, predictable output (often JSON), and focus on direct registry API interaction make it ideal for use in CI/CD pipelines, custom tooling, and automated workflows where precise control over image and artifact management in OCI registries is required. It can be a vital component for tasks like garbage collection, manifest manipulation for multi-architecture images, and synchronized content deployment.

regctl strictly adheres to the Open Container Initiative (OCI) Distribution Specification. This ensures broad compatibility with any OCI-compliant registry, providing a consistent interface regardless of the underlying registry implementation (e.g., Docker Hub, Quay.io, GitHub Container Registry, Azure Container Registry, local registries).

regctl is an open-source project, primarily developed by Greg O'Malley (GoCD team). It emerged as a dedicated tool for interacting with OCI registries, filling a niche for scenarios requiring direct and programmatic control over registry content, particularly in CI/CD environments and for specialized registry management tasks. Written in Go, it leverages the Go standard library and various OCI-related libraries, providing a robust and performant solution for registry operations. Its development reflects a growing need for versatile, automation-friendly tools within the cloud-native ecosystem, distinct from general-purpose container engines.

docker(1), podman(1), skopeo(1), oras(1)