Icon by @graffitonic on Instagram. Previous icon available here.
RegShape (from REGistry reSHAPE) is a command-line interface (CLI) tool and a Python library for manipulating artifacts in an Open Container Initiative (OCI) registry. While there are many other tools that can do this (see ORAS, regclient, or Google's crane), the goal of RegShape is to provide flexibility to manipulate the requests with an intention to break the consistency of the artifacts.
You can use RegShape in two modes:
- Standard mode — interact with registries as you would with any other tool: pull and push manifests, blobs, tags, and more.
- Expert / break mode — manually craft requests to test registry implementations and probe their security boundaries.
RegShape is written in Python and offers Python libraries that can be leveraged to build your own tools. The CLI is built on top of the libraries and uses the Click framework.
Note: The tool is still in early development and the API is not stable yet.
# Homebrew (macOS / Linux) — recommended
brew install toddysm/regshape/regshape
# pip (from PyPI)
pip install regshape
# From source
git clone https://github.com/toddysm/regshape.git
cd regshape
pip install -e .Ping a registry to verify connectivity:
regshape ping registry-1.docker.ioRetrieve a manifest:
regshape manifest get -a docker.io/library/alpine:latestDevelopment builds containing manifest progress show one live stderr row for a
manifest or index, completing only after output succeeds. Check installed help
for --no-progress. See the manifest download workflow
for file/raw/part examples and the distinction between receipt and success.
List tags for a repository:
regshape tag list -a docker.io/library/alpineRetrieve every page of tags:
regshape tag list -a docker.io/library/alpine --allUse --n to set the all-pages request size and --last to start after a tag.
See the tag command reference for pagination and output options.
--artifact / -a is the preferred selector in versions containing the 0.2
artifact-option change. Older --image-ref / -i aliases remain functional but
are deprecated in 0.2 help/docs; there is no runtime warning or removal date.
Check installed command help if using an older release. See the
artifact-option migration guide for the eight
affected commands and unchanged Docker/blob options.
Development builds targeting 0.2 also support complete artifact download, offline verification, and round-trip push, including all platforms and directory/gzip-tar output. These operations require Linux/macOS, a supported filesystem, and a trusted private namespace; Windows fails closed. See the guide's prerequisites before running them. This is not a release announcement or the separate planned config/layer-position selector.
- Complete Artifact Download and Round-trip
- Creating OCI Layouts
- Docker Desktop Integration
- Live Transfer Progress
- Manifest/Index Download Progress
- Library Transfer Callbacks
- Manifest Receive Observations
- Artifact Options and Migration
| Command | Spec |
|---|---|
| Artifact Pull | specs/cli/artifact.md |
| Auth | specs/cli/auth.md |
| Blob | specs/cli/blob.md |
| Catalog | specs/cli/catalog.md |
| Manifest | specs/cli/manifest.md |
| Tag | specs/cli/tag.md |
| Referrer | specs/cli/referrer.md |
| Ping | specs/cli/ping.md |
| Layout | specs/cli/layout.md |
| Layout Push | specs/cli/layout-push.md |
| Formatting | specs/cli/formatting.md |
- Models — Blob, Catalog, Error, Manifest, Referrer, Tags
- Operations — Blobs, Catalog, Manifests, Referrers, Tags
- Complete Artifact Library — pull, observations, limits, and snapshots
See CONTRIBUTING.md for instructions on setting up your development environment.
To report a vulnerability, please see SECURITY.md.
This project is licensed under the Apache License 2.0 — see the LICENSE file for details.