Add a subcommand to discover available CLI docker images for reproducible builds

[leighmcculloch]

What problem does your feature solve?

When someone wants to reproduce a build, they need to find the exact stellar-cli docker image that matches a given CLI version, commit, Rust version, and architecture. With the new tagging scheme (see stellar/stellar-cli-docker#11 (comment)) a single CLI version can map to many images: per-architecture variants, multiple Rust versions, and ref-pinned immutable tags that include the commit SHA, for example 26.1.0-1228cff8022b804659750b94b315932b0e0f3f6a-rust1.95.0-slim-trixie and its -amd64/-arm64 siblings. The Docker Hub UI is hard to navigate once there are lots of tags, so finding the right image to rebuild with, especially for someone who originally built without an image or with a different one, is painful. The goal is to make it easy to discover and pick an image to rebuild with so a reproduction can be made.

What would you like to see?

A subcommand that lists the available CLI docker images for a given version, sorted by release date, with both human-readable tabulated output and machine-readable JSON output. The proposed shape is stellar contract build image search --version 21.6.0, where image is a noun grouping that leaves room for other image subcommands later. It would take options to filter and refine the results: --arch multi|amd64|arm64 (defaulting to multi) to select the architecture; --version accepting either a version like 21.6.0, a commit <sha>, or a specific 21.6.0-<sha> to pin exactly; --date to list versions released before a given date (useful when you only know roughly when the original build happened); and --rust-version 1.90.0 to filter by the Rust toolchain used to build the image. Candidate images should be sourced from the Docker Hub tag listings so that only actually-published images are shown.

Example tabulated output for stellar contract build image search --version 21.6.0, sorted by release date (newest first):

TAG                                                                             ARCH   RUST     DEBIAN         RELEASED
21.6.0                                                                           multi  1.95.0   slim-trixie    2026-05-20  (alias)
21.6.0-1228cff8022b804659750b94b315932b0e0f3f6a-rust1.95.0-slim-trixie           multi  1.95.0   slim-trixie    2026-05-20
21.6.0-1228cff8022b804659750b94b315932b0e0f3f6a-rust1.95.0-slim-trixie-amd64     amd64  1.95.0   slim-trixie    2026-05-20
21.6.0-1228cff8022b804659750b94b315932b0e0f3f6a-rust1.95.0-slim-trixie-arm64     arm64  1.95.0   slim-trixie    2026-05-20
21.6.0-1228cff8022b804659750b94b315932b0e0f3f6a-rust1.94.1-slim-trixie           multi  1.94.1   slim-trixie    2026-05-18
21.6.0-1228cff8022b804659750b94b315932b0e0f3f6a-rust1.94.1-slim-trixie-amd64     amd64  1.94.1   slim-trixie    2026-05-18
21.6.0-1228cff8022b804659750b94b315932b0e0f3f6a-rust1.94.1-slim-trixie-arm64     arm64  1.94.1   slim-trixie    2026-05-18
21.6.0-9a7bf02e3c1d4b5a6f7e8d9c0b1a2f3e4d5c6b7a-rust1.90.0-slim-bookworm          multi  1.90.0   slim-bookworm  2026-03-02
21.6.0-9a7bf02e3c1d4b5a6f7e8d9c0b1a2f3e4d5c6b7a-rust1.90.0-slim-bookworm-amd64    amd64  1.90.0   slim-bookworm  2026-03-02
21.6.0-9a7bf02e3c1d4b5a6f7e8d9c0b1a2f3e4d5c6b7a-rust1.90.0-slim-bookworm-arm64    arm64  1.90.0   slim-bookworm  2026-03-02

Example JSON output (--output json):

{
  "version": "21.6.0",
  "images": [
    {
      "rust_version": "1.95.0",
      "debian": "slim-trixie",
      "commit": "1228cff8022b804659750b94b315932b0e0f3f6a",
      "released": "2026-05-20T00:00:00Z",
      "aliases": ["21.6.0"],
      "architectures": {
        "multi": "21.6.0-1228cff8022b804659750b94b315932b0e0f3f6a-rust1.95.0-slim-trixie",
        "amd64": "21.6.0-1228cff8022b804659750b94b315932b0e0f3f6a-rust1.95.0-slim-trixie-amd64",
        "arm64": "21.6.0-1228cff8022b804659750b94b315932b0e0f3f6a-rust1.95.0-slim-trixie-arm64"
      }
    },
    {
      "rust_version": "1.94.1",
      "debian": "slim-trixie",
      "commit": "1228cff8022b804659750b94b315932b0e0f3f6a",
      "released": "2026-05-18T00:00:00Z",
      "aliases": [],
      "architectures": {
        "multi": "21.6.0-1228cff8022b804659750b94b315932b0e0f3f6a-rust1.94.1-slim-trixie",
        "amd64": "21.6.0-1228cff8022b804659750b94b315932b0e0f3f6a-rust1.94.1-slim-trixie-amd64",
        "arm64": "21.6.0-1228cff8022b804659750b94b315932b0e0f3f6a-rust1.94.1-slim-trixie-arm64"
      }
    },
    {
      "rust_version": "1.90.0",
      "debian": "slim-bookworm",
      "commit": "9a7bf02e3c1d4b5a6f7e8d9c0b1a2f3e4d5c6b7a",
      "released": "2026-03-02T00:00:00Z",
      "aliases": [],
      "architectures": {
        "multi": "21.6.0-9a7bf02e3c1d4b5a6f7e8d9c0b1a2f3e4d5c6b7a-rust1.90.0-slim-bookworm",
        "amd64": "21.6.0-9a7bf02e3c1d4b5a6f7e8d9c0b1a2f3e4d5c6b7a-rust1.90.0-slim-bookworm-amd64",
        "arm64": "21.6.0-9a7bf02e3c1d4b5a6f7e8d9c0b1a2f3e4d5c6b7a-rust1.90.0-slim-bookworm-arm64"
      }
    }
  ]
}

What alternatives are there?

Browsing the Docker Hub web UI directly, which is the current approach and is the motivation for this request since it does not scale well to many tags and offers no good filtering by Rust version, architecture, commit, or release date. Another alternative is querying the Docker Hub registry API by hand with curl and jq, which works but requires knowing the tagging scheme and is not discoverable for most users.

[leighmcculloch]

One refinement on the command shape: running stellar contract build image list without the search subcommand (and without any filters) should just list the latest 20 images, so you get a useful default view immediately. search (with options like --version, --arch, --rust-version, --date) is then for when you need to narrow things down.