Installing

Updated on Jan 27, 2025

Downloading Binaries
Running as a Container
Building From Source
GitHub Actions
Verifying Signatures
Reproducible Builds
Community Maintained Packages
- Brew
- Snap
- Wolfi

Downloading Binaries

Binaries are available on the releases page.

The latest release can be downloaded using curl (adjust “regctl” and “linux-amd64” for the desired command and your own platform):

curl -L https://github.com/regclient/regclient/releases/latest/download/regctl-linux-amd64 >regctl
chmod 755 regctl

Merges into the main branch also have binaries available as artifacts within GitHub Actions

Binaries downloaded on MacOS systems may have the quarantine attribute set. That attribute can be removed with the following command (replacing regctl with the path to the binary to modify):

xattr -d com.apple.quarantine regctl

Running as a Container

You can run regctl, regsync, and regbot in a container.

For regctl (include a -t for any commands that require a tty, e.g. registry login):

docker container run -i --rm --net host \
  -v regctl-conf:/home/appuser/.regctl/ \
  ghcr.io/regclient/regctl:latest --help

For regsync:

docker container run -i --rm --net host \
  -v "$(pwd)/regsync.yml:/home/appuser/regsync.yml" \
  ghcr.io/regclient/regsync:latest -c /home/appuser/regsync.yml check

For regbot:

docker container run -i --rm --net host \
  -v "$(pwd)/regbot.yml:/home/appuser/regbot.yml" \
  ghcr.io/regclient/regbot:latest -c /home/appuser/regbot.yml once --dry-run

On Linux and Mac environments, here’s example shell script to run regctl in a container with settings for accessing content as your own user and using docker credentials and certificates:

#!/bin/sh
opts=""
case "$*" in
  "registry login"*) opts="-t";;
esac
docker container run $opts -i --rm --net host \
  -u "$(id -u):$(id -g)" -e HOME -v $HOME:$HOME \
  -v /etc/docker/certs.d:/etc/docker/certs.d:ro \
  ghcr.io/regclient/regctl:latest "$@"

Images are also included with an alpine base, which are useful for CI pipelines that expect the container to include a /bin/sh. These alpine based images also include the ecr-login and gcr credential helpers.

Building From Source

Installing commands directly with Go may be done using:

go install github.com/regclient/regclient/cmd/regctl@latest
go install github.com/regclient/regclient/cmd/regsync@latest
go install github.com/regclient/regclient/cmd/regbot@latest

For development, code can be built using make:

git clone https://github.com/regclient/regclient.git
cd regclient
make
bin/regctl version

GitHub Actions

GitHub Actions have been provided at github.com/regclient/actions. An example of installing regctl and logging into GHCR looks like:

jobs:
  example:
    runs-on: ubuntu-latest
    name: example
    steps:
      - name: Install regctl
        uses: regclient/actions/regctl-installer@main
      - name: regctl login
        uses: regclient/actions/regctl-login@main

For more details, see the github.com/regclient/actions repo.

Verifying Signatures

Binaries and images have been signed with cosign.

For images:

cosign verify \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  --certificate-identity-regexp https://github.com/regclient/regclient/.github/workflows/ \
  ghcr.io/regclient/regctl:latest

For binaries:

curl -L https://github.com/regclient/regclient/releases/latest/download/regctl-linux-amd64 >regctl
chmod 755 regctl
curl -L https://github.com/regclient/regclient/releases/latest/download/metadata.tgz >metadata.tgz
tar -xzf metadata.tgz regctl-linux-amd64.pem regctl-linux-amd64.sig
cosign verify-blob \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  --certificate-identity-regexp https://github.com/regclient/regclient/.github/workflows/ \
  --certificate regctl-linux-amd64.pem \
  --signature regctl-linux-amd64.sig \
  regctl
rm metadata.tgz regctl-linux-amd64.pem regctl-linux-amd64.sig

Reproducible Builds

Images can be rebuilt reproducibly. This requires the following:

source code to be cloned locally
docker with buildx
regctl
syft

make oci-image

# compare regctl digests to edge/main
regctl image digest ocidir://output/regctl:scratch
regctl image digest ghcr.io/regclient/regctl:edge
regctl image digest ocidir://output/regctl:alpine
regctl image digest ghcr.io/regclient/regctl:edge-alpine

# compare regsync digests to edge/main
regctl image digest ocidir://output/regsync:scratch
regctl image digest ghcr.io/regclient/regsync:edge
regctl image digest ocidir://output/regsync:alpine
regctl image digest ghcr.io/regclient/regsync:edge-alpine

# compare regbot digests to edge/main
regctl image digest ocidir://output/regbot:scratch
regctl image digest ghcr.io/regclient/regbot:edge
regctl image digest ocidir://output/regbot:alpine
regctl image digest ghcr.io/regclient/regbot:edge-alpine