Skip to main content

OCI CLI Usage

This page describes the common commands for OCI images and artifacts after you create and configure an OCI repository in Nexus.

Pull and Push Container Images with Docker and Podman

Docker and Podman are container tools that can pull, tag, and push container images to OCI-compatible registries. Docker and Podman use the same image reference format for these commands.

  • Docker pull through a proxy repository (from upstream registry)

    docker pull <NexusURL>/<repo>/<image>:<tag>

    For multi architectural images, a docker pull of a multi-architecture tag automatically selects the platform matching the client.

  • Podman pull through a proxy repository (from upstream registry):

    podman pull <NexusURL>/<repo>/<image>:<tag>

  • Docker tag and push to a hosted repository:

    docker tag <image>:<tag> <NexusURL>/<repo>/<image>:<tag>
docker push <NexusURL>/<repo>/<image>:<tag>

    For multi architectural images:

    docker buildx build --platform linux/amd64,linux/arm64 -t
[NexusURL]/<REPO_NAME>/<image>:<tag> --push .

  • Podman tag and push to a hosted repository:

    podman tag <image>:<tag> <NexusURL>/<repo>/<image>:<tag>
podman push <NexusURL>/<repo>/<image>:<tag>

Where,

  • <NexusURL> - Your Nexus repository URL, for example example.nexus.com

  • <image> - Image name

  • <tag> - Image tag, such as 1.0

Examples:

#docker pull
docker pull example.nexus.com/oci-proxy/nginx:1.27

#docker tag
docker tag nginx:1.27 example.nexus.com/oci-hosted/nginx:1.27

#docker push
docker push example.nexus.com/oci-hosted/nginx:1.27

#podman pull
podman pull example.nexus.com/oci-proxy/nginx:1.27

#podman push
podman push example.nexus.com/oci-hosted/nginx:1.27

#multi architecture images
docker buildx build \  --platform linux/amd64,linux/arm64 \  -t
repo.example.com/oci-hosted/sample-app:1.0.0 \  --push .

Pull and Push Helm Charts

Helm charts are stored and served as OCI artifacts. OCI support is generally available from Helm 3.8.0 and later.

  • Pull a Helm chart:

    helm pull oci://<NexusURL>/<REPO_NAME>/mychart --version 0.1.0

  • Package and publish a chart to a hosted repository:

    helm package mychart/                                      # produces mychart-0.1.0.tgz
helm push mychart-0.1.0.tgz oci://<NexusURL>/<REPO_NAME>

Where,

  • <NexusURL> - Your Nexus repository URL, for example example.nexus.com

  • <REPO_NAME> - Your Nexus Repository name.

Examples:

# Package a chart
helm package nginx-chart/

# Push the packaged chart
helm push nginx-chart-1.0.0.tgz oci://example.nexus.com/oci-hosted

# Pull a specific chart version
helm pull oci://example.nexus.com/oci-hosted/nginx-chart --version 1.0.0

Pull, Push and Attach OCI Artifacts (ORAS)

OCI Registry As Storage (ORAS) works with arbitrary OCI artifacts and the OCI 1.1 Referrers API. Use a recent ORAS 1.x release for finalized OCI 1.1 behaviour. The following are few commands that can be used along with Nexus Repository:

  • Pull a generic artifact:

    oras pull [NexusURL]/<REPO_NAME>/<artifact>:v1

  • Push a generic artifact:

    oras push [NexusURL]/<REPO_NAME>/<artifact>:v1 file.txt:text/plain

  • Attach an artifact to an image as a referrer:

    oras attach --artifact-type application/spdx+json [NexusURL]/<REPO_NAME>/<image>:<tag>
sbom.spdx.json

  • Discover the referrers attached to an image (optionally filter by type):

    oras discover [NexusURL]/<REPO_NAME>/<image>:<tag>
oras discover [NexusURL]/<REPO_NAME>/<image>:<tag> --artifact-type application/spdx+json

  • Copy an image (preserves a multi-architecture index) and list tags:

    oras cp [NexusURL]/<REPO_NAME>/<image>:<tag> [NexusURL]/<REPO_NAME>/<image>:copy
oras repo tags [NexusURL]/<REPO_NAME>/<image>

Where,

  • [NexusURL] - Your Nexus repository URL, for example example.nexus.com

  • <REPO_NAME> - Your Nexus Repository name

  • <image> - Image name

  • <tag> - Image tag, such as 1.0

Examples:

# Push a generic artifact
oras push example.nexus.com/oci-hosted/sample-artifact:v1 \
  readme.txt:text/plain

# Pull the artifact
oras pull example.nexus.com/oci-hosted/sample-artifact:v1

# Attach an SBOM to an image
oras attach \
  --artifact-type application/spdx+json \
  example.nexus.com/oci-hosted/nginx:1.27 \
  sbom.spdx.json

# Discover attached referrers
oras discover example.nexus.com/oci-hosted/nginx:1.27

# Discover only SPDX SBOM referrers
oras discover \
  example.nexus.com/oci-hosted/nginx:1.27 \
  --artifact-type application/spdx+json

# Copy an image
oras cp \
  example.nexus.com/oci-hosted/nginx:1.27 \
  example.nexus.com/oci-hosted/nginx:copy

# List available tags
oras repo tags example.nexus.com/oci-hosted/nginx

Sign and Verify Images (Cosign)

Cosign is an open-source command-line Sigstore client used to digitally sign, verify, and store signatures for container images and other OCI artifacts. Cosign 3.x stores signatures as OCI 1.1 referrers and attaches them to the image. They are discoverable with oras discover.

Internal Nexus registry signs with a local key pair rather than the public Sigstore infrastructure. Use the following flags to disable the Sigstore's public transparency log and keyless signing-config lookups:

  • --tlog-upload=false

  • --use-signing-config=false

  • --insecure-ignore-tlog=true

Omit the flags only if you intend to use public Sigstore or Rekor.

cosign generate-key-pair

# Sign with a local key
cosign sign --key cosign.key [NexusURL]/<REPO_NAME>/<image>:<tag> \
  --tlog-upload=false --use-signing-config=false --yes

# Verify against the public key
cosign verify --key cosign.pub [NexusURL]/<REPO_NAME>/<image>:<tag> --insecure-ignore-tlog=true

Where,

  • [NexusURL] - Your Nexus repository URL, for example example.nexus.com

  • <REPO_NAME> - Your Nexus Repository name

Example:

# Generate a key pair
cosign generate-key-pair

# Sign an image
cosign sign \
  --key cosign.key \
  example.nexus.com/oci-hosted/nginx:1.27 \
  --tlog-upload=false \
  --use-signing-config=false \
  --yes

# Verify the signature
cosign verify \
  --key cosign.pub \
  example.nexus.com/oci-hosted/nginx:1.27 \
  --insecure-ignore-tlog=true

Note

Nexus Repository stores and serves the signatures from the Cosign client as referrers. Server-side enforcement, such as rejecting pulls of unsigned images, is not available.

Use Crane and Skopeo with Nexus Repository

Crane and Skopeo are command-line tools for working with remote container images and registries. Use these tools to copy images, inspect manifests, view digests, and list tags. The following commands can be used with Nexus Repository:

  • To pull an image using Crane:

    crane pull <NexusURL>/<REPO_NAME>/<image>:<tag> <image>.tar

  • To push an image using Crane:

    crane push <image>.tar <NexusURL>/<REPO_NAME>/<image>:<tag>

  • To inspect an image using skopeo:

    skopeo inspect docker://[NexusURL]/<REPO_NAME>/<image>:<tag>

  • To copy all image variants using skopeo:

    skopeo copy --all docker://[NexusURL]/<REPO_NAME>/<image>:<tag>
docker://[NexusURL]/<REPO_NAME>/<image>:copy

Where,

  • [NexusURL] - Your Nexus repository URL, for example example.nexus.com

  • <REPO_NAME> - Your Nexus Repository name

  • <image> - Image name

  • <tag> - Image tag, such as 1.0

Examples:

# Pull an image to a local tarball
crane pull example.nexus.com/oci-hosted/nginx:1.27 nginx.tar

# Push a local tarball to the repository
crane push nginx.tar example.nexus.com/oci-hosted/nginx:1.27

# Inspect an image
skopeo inspect \
  docker://example.nexus.com/oci-hosted/nginx:1.27

# Copy all image variants
skopeo copy --all \
  docker://example.nexus.com/oci-hosted/nginx:1.27 \
  docker://example.nexus.com/oci-hosted/nginx:copy