oras

oras [OPTIONS] COMMAND [ARG...]

oras --help
oras --version
oras --debug COMMAND

oras push [OPTIONS] NAME[:TAG|@DIGEST] FILE[:TYPE] [FILE[:TYPE]...]
oras pull [OPTIONS] NAME[:TAG|@DIGEST]
oras attach [OPTIONS] NAME[:TAG|@DIGEST] FILE[:TYPE] [FILE[:TYPE]...]
oras login [OPTIONS] SERVER

--help
    Displays help information for oras or a specific subcommand.

--version
    Shows the version of the oras CLI.

--debug
    Enables debug logging for more verbose output.

--registry-config <file>
    Specify a custom registry configuration file.

--insecure
    Allow connections to insecure registries.

--verbose
    Enable verbose output.

--config <file> (for 'push')
    Path to the configuration file for the artifact manifest.

--artifact-type <type> (for 'push', 'attach')
    Specify the artifact type for the uploaded content (e.g., application/vnd.cncf.sbom.cyclonedx+json).

--annotation <key=value> (for 'push', 'attach')
    Add annotations to the manifest or artifact.

--output <path> (for 'pull')
    Specify the output directory for pulled artifacts.

--path <path> (for 'pull')
    Specify the output path for a specific file when pulling.

--media-type <type> (for 'pull')
    Pull only files matching the specified media type.

--referrers-as-subject (for 'pull', 'attach')
    Treat the current artifact as a subject for referrers, pulling associated content.

The oras command-line interface (CLI) is a powerful tool designed to manage OCI (Open Container Initiative) artifacts within OCI-compliant registries. While commonly associated with Docker images, OCI registries can store a much broader range of content, including software bills of materials (SBOMs), signatures, WebAssembly modules, configuration files, and more.

oras enables users to push, pull, copy, and tag these diverse artifacts, treating them as first-class citizens in a registry. This capability is crucial for implementing robust software supply chain security practices, as it allows for the secure storage and distribution of all related components alongside container images. It simplifies the process of managing complex dependencies and ensures that all elements of an application, from code to metadata, are versioned and accessible through a standardized registry.

It extends the utility of container registries beyond just containers, making them central hubs for all types of cloud-native components and metadata.

oras relies on the OCI Distribution Specification. While widely adopted, ensure your target registry is fully compliant and supports the specific features (like referrers) you intend to use.

Authentication with oras is typically handled via oras login, but it can also integrate with Docker's credential store, which might require proper configuration.

As the OCI artifact ecosystem continues to evolve, some features or behaviors might change with newer versions of oras or registry implementations.

oras login <registry-server> is used to authenticate with OCI registries, similar to docker login. It stores credentials in a configuration file (e.g., ~/.config/oras/config.json or ~/.docker/config.json).

A key feature of oras is its support for OCI referrers, which allow artifacts to point to other related artifacts (e.g., a container image can "refer" to its associated SBOM, vulnerability scan results, or digital signatures). This enables a robust and verifiable software supply chain.

oras originated from Microsoft in collaboration with various partners and was later contributed to the CNCF (Cloud Native Computing Foundation) as a sandbox project. Its development was driven by the need to extend OCI registries beyond just container images to support a broader range of artifacts, crucial for modern software supply chains and security. It plays a pivotal role in implementing the OCI Distribution Specification's capabilities for managing non-image artifacts and referrers, which link artifacts together (e.g., an image to its SBOM or signature).

docker(1): The de-facto CLI for managing Docker containers and images., podman(1): A daemonless container engine for developing, managing, and running OCI containers., skopeo(1): A command-line utility for various operations on container images and image repositories, including copying between registries without a daemon., regctl(1): A tool for interacting with OCI registries, often used for advanced manifest and blob operations.