What is the version of your ORAS CLI

1.3.0

What would you like to be added?

Since oras is already capable of handling multiple platforms where appropriate (such as oras cp), it would be ideal if --platform could support a list of preferred platforms.

Potentially support a wildcard syntax as a shorthand for filtering a group of platforms. For example when parsing an image index, filtering platforms returned by applying the wildcard pattern. For example:

• All archs for a given OS.
• All variants of an arch.
• All OS with a specific arch.

# Single platform (already supported):
oras cp docker.io/library/caddy:latest --to-oci-layout oras-caddy --platform linux/arm64

# Multiple platforms (unsupported, requires repeating the command with a different `--platform`):
oras cp docker.io/library/caddy:latest --to-oci-layout oras-caddy --platform 'linux/amd64,linux/arm64'
oras cp docker.io/library/caddy:latest --to-oci-layout oras-caddy --platform linux/amd64 --platform linux/arm64

# Multiple platforms with wildcard (unsupported):
oras cp docker.io/library/caddy:latest --to-oci-layout oras-caddy --platform 'linux/*'
oras cp docker.io/library/caddy:latest --to-oci-layout oras-caddy --platform 'linux/arm*'
oras cp docker.io/library/caddy:latest --to-oci-layout oras-caddy --platform '*/arm64'

I don't have a specific requirement for the related wildcard filtering, it is just something familiar with Docker Bake --set and HCL "splat", along with other tools that support a similar filter/selection pattern.

Why is this needed for ORAS?

When using oras cp the default behaviour for an image index is to pull all platforms.

When using --platform explicitly, whichever the last specified option was is the platform that will be stored. The command must be invoked multiple times with a different platform each time.

For an image index like docker.io/library/caddy:latest this is not only multi-arch but multi-platform, with the windows images variants using several GB while the Alpine linux images are considerably smaller (approx 20MB each). I was interested in using oras cp with only the linux platform as I had no need for the windows platform to be copied (nor the spare disk space in this case).

With a single --platform, the oras cp results in making a copy of just the image manifest (eg: with an OCI layout index.json) rather than an implicitly creating an image index (thus would need to be manually constructed afterwards to support tags referring to both archs).

Likewise for images built via Docker, their docker build attestation feature attaches unknown platforms to the image index which would also be lost:

{
  "manifests": [
    {
      "annotations": {
        "com.docker.official-images.bashbrew.arch": "amd64",
        "org.opencontainers.image.base.digest": "sha256:85f2b723e106c34644cd5851d7e81ee87da98ac54672b29947c052a45d31dc2f",
        "org.opencontainers.image.base.name": "alpine:3.22",
        "org.opencontainers.image.created": "2025-10-08T23:21:09Z",
        "org.opencontainers.image.revision": "5572371a83e48fd0368a4917d0fc48e44ef30582",
        "org.opencontainers.image.source": "https://github.com/caddyserver/caddy-docker.git#5572371a83e48fd0368a4917d0fc48e44ef30582:2.10/alpine",
        "org.opencontainers.image.url": "https://hub.docker.com/_/caddy",
        "org.opencontainers.image.version": "2.10.2-alpine"
      },
      "digest": "sha256:5c18f4b845cd8f2cbb344ffa6fe0391d8c975ed921848c9968298f1eb8940a97",
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "platform": {
        "architecture": "amd64",
        "os": "linux"
      },
      "size": 1916
    },
    {
      "annotations": {
        "com.docker.official-images.bashbrew.arch": "amd64",
        "vnd.docker.reference.digest": "sha256:5c18f4b845cd8f2cbb344ffa6fe0391d8c975ed921848c9968298f1eb8940a97",
        "vnd.docker.reference.type": "attestation-manifest"
      },
      "digest": "sha256:c49b5bb9fafca5664bab24f64ba8ed9dbf93ef119619a617a6452dbf94aaec01",
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "platform": {
        "architecture": "unknown",
        "os": "unknown"
      },
      "size": 840
    },

I wouldn't expect that to be supported by this feature request, since filtering by platform would lack context (technically the image manifest is referenced via vnd.docker.reference.digest) and either result in none or all (IIRC the Docker maintainers were opposed to supporting the OCI tag fallback for when the Referrer API was unavailable, which is the case with GHCR last I checked).

Are you willing to submit PRs to contribute to this feature?

• Yes, I am willing to implement it.