ORAS

https://oras.land/docs
Admin
ORAS (OCI Registry As Storage) enables users and developers to push, pull, and manage arbitrary OCI...
Tokens:74,292
Snippets:760
Trust Score:8.8
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install bash completions on Linux

Source: https://oras.land/docs/commands/oras_completion_bash

Installs bash completions system-wide on Linux. Run once, then start a new shell for the setup to take effect.

```bash
oras completion bash > /etc/bash_completion.d/oras
```

--------------------------------

### Run ORAS Go script example

Source: https://oras.land/docs/how_to_guides/go_script

Commands to set up a Go module and run the ORAS scripting example. Requires Go and the ORAS module version v1.3.0; the example code must be copied into main.go before running.

```bash
mkdir example  

cd example  

go mod init example  

go mod edit --require oras.land/oras@v1.3.0  

# copy the example code into the directory...  

cat >main.go  

go mod tidy  

go run main.go  
```

--------------------------------

### Example annotations.json file

Source: https://oras.land/docs/how_to_guides/manifest_annotations

Example annotations for $config, $manifest, and a file named cake.txt.

```json
{
  "$config": {
    "hello": "world"
  },
  "$manifest": {
    "foo": "bar"
  },
  "cake.txt": {
    "fun": "more cream"
  }
}

```

--------------------------------

### Install ORAS via Go

Source: https://oras.land/docs/installation

Install ORAS CLI using go install for Go 1.24 or later.

```bash
go install oras.land/oras/cmd/oras@v1.3.4  
```

--------------------------------

### Install ORAS on Windows

Source: https://oras.land/docs/installation

Install ORAS CLI on Windows. Ensure %USERPROFILE%\bin\ is added to your PATH environment variable.

```batch
set VERSION="1.3.4"  

curl.exe -sLO  "https://github.com/oras-project/oras/releases/download/v%VERSION%/oras_%VERSION%_windows_amd64.zip"  

tar.exe -xvzf oras_%VERSION%_windows_amd64.zip  

mkdir -p %USERPROFILE%\bin\  

copy oras.exe %USERPROFILE%\bin\  

set PATH=%USERPROFILE%\bin\;%PATH%  
```

--------------------------------

### Install bash completions on macOS

Source: https://oras.land/docs/commands/oras_completion_bash

Installs bash completions on macOS using Homebrew's prefix. Run once, then start a new shell for the setup to take effect.

```bash
oras completion bash > $(brew --prefix)/etc/bash_completion.d/oras
```

--------------------------------

### Example manifest output

Source: https://oras.land/docs/how_to_guides/pushing_and_pulling

Shows the JSON manifest generated by the multi-file push, including config and layer details.

```json
{
  "schemaVersion": 2,
  "config": {
    "mediaType": "application/vnd.acme.rocket.config.v1+json",
    "digest": "sha256:7aa5d0dee9a3a73c81db4356cf7aa5666e175d96e68ee763eeb977bd7ba59ee5",
    "size": 20
  },
  "layers": [
    {
      "mediaType": "text/plain",
      "digest": "sha256:a948904f2f0f479b8f8197694b30184b0d2ed1c1cd2a1ec0fb85d299a192a447",
      "size": 12,
      "annotations": {
        "org.opencontainers.image.title": "artifact.txt"
      }
    },
    {
      "mediaType": "application/vnd.acme.rocket.docs.layer.v1+tar",
      "digest": "sha256:20ae7d51e2365405e6942439140d897548e1d4610db60354aef8a5ce1f1699a7",
      "size": 196,
      "annotations": {
        "io.deis.oras.content.digest": "sha256:4329ea6c620ca4e9cedc5f5e8040432114cb5d64fc53107ea870db149e3d2b9e",
        "io.deis.oras.content.unpack": "true",
        "org.opencontainers.image.title": "docs"
      }
    }
  ]
}
```

--------------------------------

### Install ORAS via Snap

Source: https://oras.land/docs/installation

Install ORAS on Linux using Snap. The --classic flag is required for access to files outside the snap sandbox.

```bash
snap install oras --classic  
```

--------------------------------

### Discover command output

Source: https://oras.land/docs/how_to_guides/backup-restore

Example output displaying the discovered image and its referrers, including signatures and metadata.

```text
docker.io/myorg/oras-cli@sha256:7ab47454c95a177cbbccea9569abde6ccfd6b1367bc6407032fe78224cacc86e
├── application/vnd.cncf.notary.signature
│   └── sha256:cb90b160364b291474fc44249e59b01fd626bb25b2d8842b3345b9f3c06ea4ba
│       └── [annotations]
│           ├── io.cncf.notary.x509chain.thumbprint#S256: '[c788b80157a0cee4f7e9fb60fd533a7079181f4d74a2b62881dfbe320ccb13f9,9b1894f223d934cbd6575af3c6e1f6096b9221a7da132185f5a5cdc92235b5dc,23ffe2b8bdb9a1711515d4cffda04bc7f793d513c76c243f1020507d8669b7db]'
│           └── org.opencontainers.image.created: "2025-06-23T22:43:51Z"
├── application/vnd.in-toto+json
│   ├── sha256:b8387e1905107f771adbc5900d0d4d85ebf5c943dd83e28181acf9f1e50344a6
│   │   └── [annotations]
│   │       └── org.opencontainers.image.created: "2025-06-23T22:43:57Z"
│   └── sha256:eb87c8b2e8c24470e5c3125d60ae32071db9b89e544f6e572d42e5ede3f16a0e
│       └── [annotations]
│           └── org.opencontainers.image.created: "2025-06-23T22:44:02Z"
└── application/spdx+json
    ├── sha256:900d08c004d48ab1f792c05b69d7cbfd7c9430ba5b2712f0e5b6a4aa6893abcb
    │   └── [annotations]
    │       └── org.opencontainers.image.created: "2025-06-23T22:43:58Z"
    └── sha256:7fdcd4dce4449b9dddbaefa1bc02ba408d119c5d50227eb36ba730b3980d5e26
        └── [annotations]
            └── org.opencontainers.image.created: "2025-06-23T22:43:52Z"
```

--------------------------------

### Restore process output

Source: https://oras.land/docs/how_to_guides/backup-restore

Example output showing the successful restoration of tags and referrers from the backup archive.

```text
Loaded backup archive: oras-cli.tar (32.2 MB)

Found 3 tag(s) in the backup: sha256-7ab47454c95a177cbbccea9569abde6ccfd6b1367bc6407032fe78224cacc86e, v1.2.3, v1.2.3-2

...

Pushed tag v1.2.3-2 with 5 referrer(s)

Successfully restored 3 tag(s) to "docker.io/myorg/oras-cli" in 31s
```

--------------------------------

### Install completions on Linux

Source: https://oras.land/docs/commands/oras_completion_zsh

Command to persist completions for every new session on Linux systems.

```bash
oras completion zsh > "${fpath[1]}/_oras"
```

--------------------------------

### OCI Layout index.json example

Source: https://oras.land/docs/concepts/reference

Example index.json file from an OCI Layout directory. It contains a reference to a manifest file that can be accessed as 'v1' or by the digest 'sha256:921f70dafac450afd63cc4210b2086cb4290ef7d51249eb79c4777e731b87746'.

```json
{
  "schemaVersion": 2,
  "manifests": [
    {
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "digest": "sha256:921f70dafac450afd63cc4210b2086cb4290ef7d51249eb79c4777e731b87746",
      "size": 555,
      "annotations": {
        "org.opencontainers.image.created": "2023-08-19T00:05:47Z",
        "org.opencontainers.image.ref.name": "v1"
      },
      "artifactType": "application/example"
    }
  ]
}
```

--------------------------------

### Run zot registry with Docker

Source: https://oras.land/docs/quickstart

Starts a local zot registry container on port 5000. Requires Docker to be installed.

```bash
docker run -d -p 5000:5000 --name oras-quickstart ghcr.io/project-zot/zot-linux-amd64:latest
```

--------------------------------

### Output of oras discover

Source: https://oras.land/docs/how_to_guides/remote_registries

Example output from the `oras discover` command, showing the referrer tree.

```text
ghcr.io/my_github_username/my-repository@sha256:b557297d52ec1bee854717827994fb616bffe936c583c7ce66fb21eb0c557df6  

└── doc/example  

    └── sha256:a461956f5500056ca03ee325c4c607ef421dfff6ad1902eeb2da67686c62004b  

```

--------------------------------

### Install completions on macOS

Source: https://oras.land/docs/commands/oras_completion_zsh

Command to persist completions for every new session on macOS systems using Homebrew.

```bash
oras completion zsh > $(brew --prefix)/share/zsh/site-functions/_oras
```

--------------------------------

### Plain HTTP Docker Registry setup with ORAS --plain-http

Source: https://oras.land/docs/compatible_oci_registries

Grouped blocks for setting up and using a plain HTTP registry. Create htpasswd, run the registry on HTTP (debug `--plain-http` flag), then login, push, pull, and logout using the `--plain-http` flag. Use the registry IP, not localhost.

```bash
htpasswd -cB -b auth.htpasswd myuser mypass
```

```bash
docker run -it --rm -p 5000:5000 \
  -v $(pwd)/auth.htpasswd:/etc/docker/registry/auth.htpasswd \
  -e REGISTRY_AUTH="{htpasswd: {realm: localhost, path: /etc/docker/registry/auth.htpasswd}}" \
  -e REGISTRY_HTTP_ADDR=0.0.0.0:5000 \
  registry
```

```bash
oras login -u myuser -p mypass --insecure <registry-ip>:5000
```

```bash
oras push <registry-ip>:5000/library/hello:latest hi.txt --plain-http
```

```bash
oras pull <registry-ip>:5000/library/hello:latest --plain-http
```

```bash
oras logout <registry-ip>:5000
```

--------------------------------

### Execute ORAS CLI command from Go script

Source: https://oras.land/docs/how_to_guides/go_script

Shows how to invoke the ORAS CLI from a Go program by constructing command-line arguments and executing the root command. The example runs `oras repo ls mcr.microsoft.com` and prints the output; on error it exits with code -1. This feature is experimental and may change.

```go
package main  

import (  

	"fmt"  

	"os"  

	"strings"  

	"oras.land/oras/cmd/oras/root"  

)  

func main() {  

	// change below array to play with your own cmd args:  

	args := []string{"repo", "ls", "mcr.microsoft.com"}  

	cmd := root.New()  

	cmd.SetArgs(args)  

	builder := &strings.Builder{}  

	cmd.SetOut(builder)  

	fmt.Printf("Executing 'oras %s':", strings.Join(args, " "))  

	err := cmd.Execute()  

	fmt.Println(builder.String())  

	if err != nil {  

		fmt.Errorf("Failed to execute : %w", err)  

		os.Exit(-1)  

	}  

	os.Exit(0)  

}  
```

--------------------------------

### Create sample file hi.txt

Source: https://oras.land/docs/quickstart

Creates a sample file named hi.txt containing 'hello world' for attaching to an artifact.

```bash
echo "hello world" > hi.txt
```

--------------------------------

### Create a simple artifact file

Source: https://oras.land/docs/how_to_guides/remote_registries

Creates a simple text file named artifact.txt containing 'hello world' to be pushed to the registry.

```bash
echo "hello world" > artifact.txt  

```

--------------------------------

### Authenticated Docker Registry setup and ORAS login/logout

Source: https://oras.land/docs/compatible_oci_registries

Grouped blocks for setting up an authenticated registry using htpasswd (with -B for bcrypt). Creates auth.htpasswd, starts the registry with the auth file, logs in with ORAS, and logs out. Credentials appear in ~/.docker/config.json.

```bash
htpasswd -cB -b auth.htpasswd myuser mypass
```

```bash
docker run -it --rm -p 5000:5000 \
    -v $(pwd)/auth.htpasswd:/etc/docker/registry/auth.htpasswd \
    -e REGISTRY_AUTH="{htpasswd: {realm: localhost, path: /etc/docker/registry/auth.htpasswd}}" \
    registry
```

```bash
oras login -u myuser -p mypass localhost:5000
```

```bash
oras logout localhost:5000
```

--------------------------------

### Insecure Docker Registry: self-signed cert setup and registry start

Source: https://oras.land/docs/compatible_oci_registries

Part 1 of the insecure registry workflow: create htpasswd file and generate self-signed certificates. The registry listens on 0.0.0.0:5000 with TLS using the generated cert. The next snippet continues with ORAS login and file operations.

```bash
htpasswd -cB -b auth.htpasswd myuser mypass
```

```bash
$ mkdir -p certs
$ openssl req \
  -newkey rsa:4096 -nodes -sha256 -keyout certs/domain.key \
  -x509 -days 365 -out certs/domain.crt
```

```bash
docker run -it --rm -p 5000:5000 \
    -v `pwd`/certs:/certs \
    -v $(pwd)/auth.htpasswd:/etc/docker/registry/auth.htpasswd \
    -e REGISTRY_AUTH="{htpasswd: {realm: localhost, path: /etc/docker/registry/auth.htpasswd}}" \
    -e REGISTRY_HTTP_ADDR=0.0.0.0:5000 \
    -e REGISTRY_HTTP_TLS_CERTIFICATE=/certs/domain.crt \
    -e REGISTRY_HTTP_TLS_KEY=/certs/domain.key \
    registry
```

--------------------------------

### List available ORAS commands with oras help

Source: https://oras.land/docs/commands/use_oras_cli

Run `oras` with no parameters or `oras help` to display the usage information, including available commands and flags. The output lists commands such as attach, backup, blob, completion, cp, discover, help, login, logout, manifest, pull, push, repo, resolve, restore, tag, and version. Use `oras [command] --help` for more information about a specific command.

```text
Usage:  

  oras [command]  

  

Available Commands:  

  attach      Attach files to an existing artifact  

  backup      [Experimental] Back up artifacts from a registry into an OCI image layout  

  blob        Blob operations  

  completion  Generate the autocompletion script for the specified shell  

  cp          Copy artifacts from one target to another  

  discover    [Preview] Discover referrers of a manifest in a registry or an OCI image layout  

  help        Help about any command  

  login       Log in to a remote registry  

  logout      Log out from a remote registry  

  manifest    Manifest operations  

  pull        Pull files from a registry or an OCI image layout  

  push        Push files to a registry or an OCI image layout  

  repo        Repository operations  

  resolve     [Preview] Resolves digest of the target artifact  

  restore     [Experimental] Restore artifacts to a registry from an OCI image layout  

  tag         Tag a manifest in a registry or an OCI image layout  

  version     Show the oras version information  

  

Flags:  

  -h, --help   help for oras  

  

Use "oras [command] --help" for more information about a command.  

```

--------------------------------

### Verify ORAS Installation

Source: https://oras.land/docs/installation

Check the installed version of ORAS.

```bash
$ oras version  

  

Version:        1.3.4  

Go version:     go1.26.2  

OS/Arch:        linux/amd64  

Git commit:     db9e29505c3059f2b8fde34ae8cae266c5c765e9  

Git tree state: clean  
```

--------------------------------

### Discover referrers in OCI image layout (tagged example.com:v1)

Source: https://oras.land/docs/commands/oras_discover

Discovers referrers of the manifest tagged 'example.com:v1' in an OCI image layout folder 'layout-dir' using the `--oci-layout-path` flag.

```bash
oras discover example.com:v1 --oci-layout-path layout-dir  
```

--------------------------------

### Attach file with manifest annotations

Source: https://oras.land/docs/commands/oras_attach

Attach file 'hi.txt' and add manifest annotations.

```bash
oras attach --artifact-type doc/example --annotation "key=val" localhost:5000/hello:v1 hi.txt
```

--------------------------------

### Install ORAS on Linux AMD64

Source: https://oras.land/docs/installation

Install ORAS on an AMD64-based Linux machine using the release artifact.

```bash
VERSION="1.3.4"  

curl -LO "https://github.com/oras-project/oras/releases/download/v${VERSION}/oras_${VERSION}_linux_amd64.tar.gz"  

mkdir -p oras-install/  

tar -zxf oras_${VERSION}_*.tar.gz -C oras-install/  

sudo mv oras-install/oras /usr/local/bin/  

rm -rf oras_${VERSION}_*.tar.gz oras-install/  
```

--------------------------------

### List repositories using a Go template

Source: https://oras.land/docs/commands/oras_repo_ls

Experimental feature to format the output using a custom Go template.

```bash
oras repo ls localhost:5000 --format go-template --template "{{.repositories}}"
```

--------------------------------

### Attach file to manifest

Source: https://oras.land/docs/commands/oras_attach

Attach file 'hi.txt' with artifact type 'doc/example' to manifest 'hello:v1' in registry 'localhost:5000'.

```bash
oras attach --artifact-type doc/example localhost:5000/hello:v1 hi.txt
```

--------------------------------

### Install ORAS on macOS Apple Silicon

Source: https://oras.land/docs/installation

Install ORAS on a Mac computer with Apple silicon using the release artifact.

```bash
VERSION="1.3.4"  

curl -LO "https://github.com/oras-project/oras/releases/download/v${VERSION}/oras_${VERSION}_darwin_arm64.tar.gz"  

mkdir -p oras-install/  

tar -zxf oras_${VERSION}_*.tar.gz -C oras-install/  

sudo mv oras-install/oras /usr/local/bin/  

rm -rf oras_${VERSION}_*.tar.gz oras-install/  
```

--------------------------------

### Install ORAS from Release Artifacts

Source: https://oras.land/docs/installation

Download and install the latest ORAS release for macOS and Linux by dynamically determining the OS and architecture.

```bash
OS="$(uname -s | tr A-Z a-z)"  

ARCH=$(uname -m | sed -e 's/x86_64/amd64/g')  

VERSION="1.3.4"  

curl -LO "https://github.com/oras-project/oras/releases/download/v${VERSION}/oras_${VERSION}_${OS}_${ARCH}.tar.gz"  

mkdir -p oras-install/  

tar -zxf oras_${VERSION}_${OS}_${ARCH}.tar.gz -C oras-install/  

sudo chown root:0 oras-install/oras  

sudo mv oras-install/oras /usr/local/bin/  

rm -rf oras_${VERSION}_${OS}_${ARCH}.tar.gz oras-install/  
```

--------------------------------

### Create Index With Tag

Source: https://oras.land/docs/commands/oras_manifest_index_create

Create an index from source manifests tagged 'linux-amd64' and 'linux-arm64', and push with the tag 'v1'.

```bash
oras manifest index create localhost:5000/hello:v1 linux-amd64 linux-arm64
```

--------------------------------

### Create a config file referencing the entry doc

Source: https://oras.land/docs/how_to_guides/pushing_and_pulling

Creates a config.json file with content {"doc":"readme.md"} to reference the entry document.

```bash
echo "{\"doc\":\"readme.md\"}" > config.json
```

--------------------------------

### List repositories in a registry

Source: https://oras.land/docs/commands/oras_repo_ls

Basic command to list all repositories under the specified registry.

```bash
oras repo ls localhost:5000
```

--------------------------------

### Logout from a registry

Source: https://oras.land/docs/commands/oras_logout

Example of logging out from a registry at localhost:5000.

```bash
oras logout localhost:5000
```

--------------------------------

### Fetch the config and save it to a local file

Source: https://oras.land/docs/commands/oras_manifest_fetch-config

Save the fetched configuration directly to a local file using the --output flag.

```bash
oras manifest fetch-config --output config.json localhost:5000/hello:v1
```

--------------------------------

### Fetch the config

Source: https://oras.land/docs/commands/oras_manifest_fetch-config

Basic command to fetch the configuration of a manifest from a registry.

```bash
oras manifest fetch-config localhost:5000/hello:v1
```

--------------------------------

### Show tags of a repository

Source: https://oras.land/docs/commands/oras_repo_tags

Displays all tags of the target repository localhost:5000/hello.

```bash
oras repo tags localhost:5000/hello  
```

--------------------------------

### Create Index With Annotations

Source: https://oras.land/docs/commands/oras_manifest_index_create

Create and push an index with annotations.

```bash
oras manifest index create localhost:5000/hello:v1 linux-amd64 --annotation "key=val"
```

--------------------------------

### Output of oras pull

Source: https://oras.land/docs/how_to_guides/remote_registries

Example output from the `oras pull` command, showing the pulled artifact and manifest.

```text
✓ Pulled      artifact.txt                                                                                 12/12  B 100.00%    2ms  

  └─ sha256:a948904f2f0f479b8f8197694b30184b0d2ed1c1cd2a1ec0fb85d299a192a447  

✓ Pulled      application/vnd.oci.image.manifest.v1+json                                                 591/591  B 100.00%  329µs  

  └─ sha256:b557297d52ec1bee854717827994fb616bffe936c583c7ce66fb21eb0c557df6  

Pulled [registry] ghcr.io/my_github_username/my-repository:v1  

Digest: sha256:b557297d52ec1bee854717827994fb616bffe936c583c7ce66fb21eb0c557df6  

```

--------------------------------

### Fetch and print the prettified config

Source: https://oras.land/docs/commands/oras_manifest_fetch-config

Fetch the configuration and output it in a prettified JSON format.

```bash
oras manifest fetch-config --pretty localhost:5000/hello:v1
```

--------------------------------

### Attach file to OCI image layout path

Source: https://oras.land/docs/commands/oras_attach

Attach file to the manifest tagged 'example.com:v1' in an OCI image layout folder 'layout-dir'.

```bash
oras attach --artifact-type doc/example --oci-layout-path layout-dir example.com:v1 hi.txt
```

--------------------------------

### Resolve digest of target artifact (example)

Source: https://oras.land/docs/commands/oras_resolve

Resolves the digest of the artifact with tag 'v1' on the registry 'localhost:5000'.

```sh
oras resolve localhost:5000/hello-world:v1  
```

--------------------------------

### Create ORAS Docker Alias

Source: https://oras.land/docs/installation

Create a local alias to use the ORAS Docker image instead of installing a binary.

```bash
alias doras='docker run -it --rm -v $(pwd):/workspace ghcr.io/oras-project/oras:v1.3.4'  
```

--------------------------------

### Push with null device for empty config

Source: https://oras.land/docs/how_to_guides/manifest_config

Use the null device to provide an empty configuration file.

```bash
oras push --config /dev/null:application/vnd.oras.config.v1+json localhost:5000/hello:latest hi.txt
```

--------------------------------

### Output of oras attach

Source: https://oras.land/docs/how_to_guides/remote_registries

Example output from the `oras attach` command, showing the uploaded reference and the new manifest digest.

```text
✓ Uploaded  ref-artifact.txt                                                                                           13/13  B 100.00%  490ms  

  └─ sha256:9e820c753b29c9ea7b85a7d1b9d88107330d625546c216facba451effe1b8dbd  

✓ Exists    application/vnd.oci.empty.v1+json                                                                            2/2  B 100.00%     0s  

  └─ sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a  

✓ Uploaded  application/vnd.oci.image.manifest.v1+json                                                               746/746  B 100.00%  930ms  

  └─ sha256:a461956f5500056ca03ee325c4c607ef421dfff6ad1902eeb2da67686c62004b  

Attached to [registry] ghcr.io/my_github_username/my-repository@sha256:b557297d52ec1bee854717827994fb616bffe936c583c7ce66fb21eb0c557df6  

Digest: sha256:a461956f5500056ca03ee325c4c607ef421dfff6ad1902eeb2da67686c62004b  

```

--------------------------------

### Output of oras push

Source: https://oras.land/docs/how_to_guides/remote_registries

Example output from the `oras push` command, showing uploaded blobs and the final manifest digest.

```text
✓ Uploaded  application/vnd.oci.empty.v1+json                                                                2/2  B 100.00%  913ms  

  └─ sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a  

✓ Uploaded  artifact.txt                                                                                   12/12  B 100.00%  912ms  

  └─ sha256:a948904f2f0f479b8f8197694b30184b0d2ed1c1cd2a1ec0fb85d299a192a447  

✓ Uploaded  application/vnd.oci.image.manifest.v1+json                                                   591/591  B 100.00%  717ms  

  └─ sha256:b557297d52ec1bee854717827994fb616bffe936c583c7ce66fb21eb0c557df6  

Pushed [registry] ghcr.io/my_github_username/my-repository:v1  

ArtifactType: application/vnd.unknown.artifact.v1  

Digest: sha256:b557297d52ec1bee854717827994fb616bffe936c583c7ce66fb21eb0c557df6  

```

--------------------------------

### View multi-architecture manifest with oras manifest fetch

Source: https://oras.land/docs/how_to_guides/multiarch

Use the --pretty flag to display the manifest structure, including the list of platform-specific manifests.

```bash
$ oras manifest fetch localhost:15000/oras:v1 --pretty  

{  

  "schemaVersion": 2,  

  "mediaType": "application/vnd.oci.image.index.v1+json",  

  "manifests": [  

    {  

      "mediaType": "application/vnd.oci.image.manifest.v1+json",  

      "digest": "sha256:302df4334cffe5132b6b81c06742be8ab3345bff3ce922662bc8674e79113bfd",  

      "size": 590,  

      "platform": {  

        "architecture": "arm64",  

        "os": "linux"  

      }  

    },  

    {  

      "mediaType": "application/vnd.oci.image.manifest.v1+json",  

      "digest": "sha256:e5b0ffe309a91893d4423f09e82410364607fd749ea2f93dd1c286d718d9c1e4",  

      "size": 590,  

      "platform": {  

        "architecture": "amd64",  

        "os": "linux"  

      }  

    }  

  ]  

}  
```

--------------------------------

### Fetch manifest with --output and --format go-template

Source: https://oras.land/docs/how_to_guides/format_output

Runs `oras manifest fetch` with `--output sample-manifest` and `--format go-template='{{.content.config.mediaType}}'`. The command writes the manifest to a file and prints the mediaType to the console. The `--output -` option cannot be used with `--format`.

```bash
$ oras manifest fetch $REGISTRY/$REPO:$TAG --output sample-manifest --format go-template='{{.content.config.mediaType}}'  

application/vnd.oci.empty.v1+json  

```

--------------------------------

### Load bash completions in current session

Source: https://oras.land/docs/commands/oras_completion_bash

Loads bash completions for the current shell session. Requires the 'bash-completion' package to be installed.

```bash
source <(oras completion bash)
```

--------------------------------

### OCI Image Manifest with Config Blob

Source: https://oras.land/docs/concepts/artifact

An example where the config blob uses its own mediaType and the artifactType property indicates the artifact type.

```json
   {  

     "schemaVersion": 2,  

     "mediaType": "application/vnd.oci.image.manifest.v1+json",  

     "artifactType": "application/vnd.example+type",  

     "config": {  

       "mediaType": "application/vnd.example.config.v1+json",  

       "digest": "sha256:5891b5b522d5df086d0ff0b110fbd9d21bb4fc7163af34d08286a2e846f6be03",  

       "size": 123  

     },  

     "layers": [  

       {  

         "mediaType": "application/vnd.example.data.v1.tar+gzip",  

         "digest": "sha256:e258d248fda94c63753607f7c4494ee0fcbe92f1a76bfdac795c9d84101eb317",  

         "size": 1234  

       }  

     ]  

   }  
```

--------------------------------

### Fetch blob and print raw content

Source: https://oras.land/docs/commands/oras_blob_fetch

Fetches a blob from a registry and prints the raw blob content to stdout using --output -.

```bash
oras blob fetch --output - localhost:5000/hello@sha256:9a201d228ebd966211f7d1131be19f152be428bd373a92071c71d8deaf83b3e5
```

--------------------------------

### List referrers by artifactType

Source: https://oras.land/docs/concepts/reftypes

Example request and response for listing referrers filtered by a specific media type using the artifactType query parameter.

```http
GET /v2/hello-world/referrers/sha256:5e140a6..?artifactType=application%2Fexample HTTP/1.1  

  

// response  

Content-Type: application/vnd.oci.image.index.v1+json  

Oci-Filters-Applied: artifactType  

  

{  

  "schemaVersion": 2,  

  "mediaType": "application/vnd.oci.image.index.v1+json",  

  "manifests": [  

    {  

      "mediaType": "application/vnd.oci.image.manifest.v1+json",  

      "digest": "sha256:a10d2cf503458e48996a3e3030c75fb5f5cd967e21a38ca69ce6c1e1dee5fd27",  

      "size": 677,  

      "annotations": {  

        "org.opencontainers.image.created": "2023-08-05T07:08:43Z"  

      },  

      "artifactType": "application/example"  

    }  

  ]  

}  
```

--------------------------------

### Fetch manifest with media type

Source: https://oras.land/docs/commands/oras_manifest_fetch

Retrieves the manifest from a registry by specifying the accepted media type.

```bash
oras manifest fetch --media-type 'application/vnd.oci.image.manifest.v1+json' localhost:5000/hello:v1
```

--------------------------------

### Define OCI artifact annotations

Source: https://oras.land/docs/concepts/artifact

Example of adding key-value metadata pairs to an OCI artifact manifest or index using the annotations field.

```json
{

  ...  

  "annotations": {  

    "oci.opencontainers.image.created": "2023-01-02T03:04:05Z",  

    "com.example.information": "useful-info"  

  }  

}
```

--------------------------------

### Annotations-only OCI Artifact Manifest

Source: https://oras.land/docs/concepts/artifact

An example of an artifact that stores metadata as annotations without a functional config or blobs. It includes an empty layer for maximum compatibility.

```json
{  

  "schemaVersion": 2,  

  "mediaType": "application/vnd.oci.image.manifest.v1+json",  

  "artifactType": "application/vnd.example+type",  

  "config": {  

    "mediaType": "application/vnd.oci.empty.v1+json",  

    "digest": "sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a",  

    "size": 2  

  },  

  "layers": [  

    {  

      "mediaType": "application/vnd.oci.empty.v1+json",  

      "digest": "sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a",  

      "size": 2  

    }  

  ],  

  "annotations": {  

    "oci.opencontainers.image.created": "2023-01-02T03:04:05Z",  

    "com.example.info": "useful-info"  

  }  

}  
```

--------------------------------

### Push and pull config using manifest annotations

Source: https://oras.land/docs/how_to_guides/manifest_config

Use manifest annotations to make a configuration file pullable.

```bash
$ cat config.json

{

    "foo": "bar"

}

$ cat annotations.json

{

    "$config": {

        "org.opencontainers.image.title": "config.json"

    }

}

$ oras push --config config.json --annotation-file annotations.json localhost:5000/hello:latest hi.txt

Uploading a948904f2f0f hi.txt

Uploading 57f840b6073c config.json

Pushed localhost:5000/hello:latest

Digest: sha256:12e3de7e4a65ffc46a6158ac2df07ecc6fd1af8b0109b4c42a90067f7e907f43

$ oras pull -a localhost:5000/hello:latest

Downloaded a948904f2f0f hi.txt

Downloaded 57f840b6073c config.json

Pulled localhost:5000/hello:latest

Digest: sha256:12e3de7e4a65ffc46a6158ac2df07ecc6fd1af8b0109b4c42a90067f7e907f43
```

--------------------------------

### Legacy OCI Image Manifest without artifactType

Source: https://oras.land/docs/concepts/artifact

An example of an artifact manifest from before version 1.1 of the image specification, where the artifact type is indicated solely by the config.mediaType.

```json
{  

  "schemaVersion": 2,  

  "mediaType": "application/vnd.oci.image.manifest.v1+json",  

  "config": {  

    "mediaType": "application/vnd.cncf.helm.config.v1+json",  

    "digest": "sha256:34bf03806938a59ee7dc3e2c33e314d0eaef573313ff9dcc677113502d568523",  

    "size": 145  

  },  

  "layers": [  

    {  

      "mediaType": "application/vnd.cncf.helm.chart.content.v1.tar+gzip",  

      "digest": "sha256:4d80464e9d8e9f3ba92e6ead6d3b5afd0532cb0a81e980599a0bced99fdc6e01",  

      "size": 3763  

    }  

  ]  

}  
```

--------------------------------

### OCI Image Manifest with Blobs

Source: https://oras.land/docs/concepts/artifact

An example of an artifact using an Image Manifest with an artifactType and blobs referenced in the layers property. The config property uses an empty blob as per empty descriptor guidance.

```json
 {

  "schemaVersion": 2,  

  "mediaType": "application/vnd.oci.image.manifest.v1+json",  

  "artifactType": "application/vnd.example+type",  

  "config": {  

    "mediaType": "application/vnd.oci.empty.v1+json",  

    "digest": "sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a",  

    "size": 2  

  },  

  "layers": [  

    {  

      "mediaType": "application/vnd.oci.image.layer.v1.tar",  

      "digest": "sha256:d2a84f4b8b650937ec8f73cd8be2c74add5a911ba64df27458ed8229da804a26",  

      "size": 12,  

      "annotations": {  

        "org.opencontainers.image.title": "hello.txt"  

      }  

    }  

  ],  

  "annotations": {  

    "org.opencontainers.image.created": "2023-08-03T00:21:51Z"  

  }  

}  
```

--------------------------------

### Create Docker buildx builder

Source: https://oras.land/docs/how_to_guides/distributing_oci_layouts

Initialize a new builder instance with a single node.

```bash
docker buildx create —use  
```

--------------------------------

### Run local unauthenticated distribution container

Source: https://oras.land/docs/compatible_oci_registries

Starts CNCF Distribution as a container listening on localhost:5000 with wide-open access, no persistence outside the container. Used for local -offline verification of ORAS and OCI Artifacts.

```bash
docker run -it --rm -p 5000:5000 registry
```

--------------------------------

### Attach file with Go template output

Source: https://oras.land/docs/commands/oras_attach

[Experimental] Attach file 'hi.txt' and format output with Go template.

```bash
oras attach --artifact-type doc/example localhost:5000/hello:v1 hi.txt --format go-template --template "{{.digest}}"
```

--------------------------------

### Create multi-arch manifest with tags

Source: https://oras.land/docs/how_to_guides/multiarch

Creates an OCI image index manifest using the tags 'linux_arm64' and 'linux_amd64' instead of SHA digests. The command fetches the tagged artifacts, packs the index, and pushes it to the registry, outputting the digest.

```bash
$ oras manifest index create localhost:15000/oras:v1 linux_arm64 linux_amd64  

Fetching  linux_arm64  

Fetched   sha256:302df4334cffe5132b6b81c06742be8ab3345bff3ce922662bc8674e79113bfd linux_arm64  

Fetching  linux_amd64  

Fetched   sha256:e5b0ffe309a91893d4423f09e82410364607fd749ea2f93dd1c286d718d9c1e4 linux_amd64  

Packed    0fd4ac889c6f application/vnd.oci.image.index.v1+json  

Pushed    [registry] localhost:15000/oras:v1  

Digest: sha256:0fd4ac889c6f1f3e4fbb1c88b0cc18b97176bf7fd0841ac9c5264d20dd54e2d8  

```

--------------------------------

### Create Index in OCI Layout

Source: https://oras.land/docs/commands/oras_manifest_index_create

Create an index and push to an OCI image layout folder 'layout-dir' and tag with 'v1'.

```bash
oras manifest index create layout-dir:v1 linux-amd64 sha256:99e4703fbf30916f549cd6bfa9cdbab614b5392fbe64fdee971359a77073cdf9 --oci-layout
```

--------------------------------

### Push with custom config file and media type

Source: https://oras.land/docs/how_to_guides/manifest_config

Push a file with a custom configuration file and a specific media type.

```bash
oras push --config config.json:application/vnd.oras.config.v1+json localhost:5000/hello:latest hi.txt
```

--------------------------------

### Create Index With Multiple Tags

Source: https://oras.land/docs/commands/oras_manifest_index_create

Create an index and push it with multiple tags.

```bash
oras manifest index create localhost:5000/hello:tag1,tag2,tag3 linux-amd64 linux-arm64 sha256:99e4703fbf30916f549cd6bfa9cdbab614b5392fbe64fdee971359a77073cdf9
```

--------------------------------

### View manifest output with oras manifest fetch

Source: https://oras.land/docs/how_to_guides/manifest_annotations

Fetches and pretty-prints the manifest to verify the annotations applied.

```bash
oras manifest fetch localhost:5000/club:party --pretty  
```

--------------------------------

### Define Dockerfile for Alpine Linux

Source: https://oras.land/docs/how_to_guides/distributing_oci_layouts

Create a Dockerfile to run an Alpine Linux image that outputs 'hello world!'.

```dockerfile
FROM alpine  

CMD echo 'hello world!'  
```

--------------------------------

### Command Syntax

Source: https://oras.land/docs/commands/oras_manifest_index_create

The basic syntax for the oras manifest index create command.

```bash
oras manifest index create [flags] <target>[:<tag[,<tag>][...]] <sources>[{<tag>|<digest>}...]
```

--------------------------------

### Create a config file for pushing

Source: https://oras.land/docs/how_to_guides/pushing_and_pulling

Creates a JSON config file named config.json with the content {"name":"foo","value":"bar"}.

```bash
echo "{\"name\":\"foo\",\"value\":\"bar\"}" > config.json
```

--------------------------------

### Create Index Using Tags and Digests

Source: https://oras.land/docs/commands/oras_manifest_index_create

Create an index from source manifests using both tags and digests, and push with tag 'v1'.

```bash
oras manifest index create localhost:5000/hello:v1 linux-amd64 sha256:99e4703fbf30916f549cd6bfa9cdbab614b5392fbe64fdee971359a77073cdf9
```

--------------------------------

### Fetch and print the prettified descriptor of the config

Source: https://oras.land/docs/commands/oras_manifest_fetch-config

Retrieve and display the prettified descriptor of the configuration.

```bash
oras manifest fetch-config --descriptor --pretty localhost:5000/hello:v1
```

--------------------------------

### Back up a single artifact to a directory

Source: https://oras.land/docs/commands/oras_backup

Backs up a single artifact to a directory. The output path `hello` does not end with `.tar`, so a directory is created.

```bash
oras backup --output hello localhost:5000/hello:v1  
```

--------------------------------

### View generated manifest file with cat

Source: https://oras.land/docs/how_to_guides/format_output

Displays the content of the `sample-manifest` file generated by the previous command. The output is compact JSON data.

```bash
$ cat sample-manifest  

{"schemaVersion":2,"mediaType":"application/vnd.oci.image.manifest.v1+json","artifactType":"application/vnd.unknown.artifact.v1","config":{"mediaType":"application/vnd.oci.empty.v1+json","digest":"sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a","size":2,"data":"e30="},"layers":[{"mediaType":"application/vnd.oci.image.layer.v1.tar","digest":"sha256:6cb759c4296e67e35b0367f3c0f51dfdb776a0c99a45f39d0476e43d82696d65","size":14477,"annotations":{"org.opencontainers.image.title":"sbom.spdx"}},{"mediaType":"application/vnd.oci.image.layer.v1.tar","digest":"sha256:54c0e84503c8790e03afe34bfc05a5ce45c933430cfd9c5f8a99d2c89f1f1b69","size":6639,"annotations":{"org.opencontainers.image.title":"scan-test-verify-image.json"}}],"annotations":{"org.opencontainers.image.created":"2023-12-15T09:41:54Z"}}  

```

--------------------------------

### Attach file and export manifest

Source: https://oras.land/docs/commands/oras_attach

Attach file 'hi.txt' and export the pushed manifest to 'manifest.json'.

```bash
oras attach --artifact-type doc/example --export-manifest manifest.json localhost:5000/hello:v1 hi.txt
```

--------------------------------

### Fetch the config of certain platform

Source: https://oras.land/docs/commands/oras_manifest_fetch-config

Fetch the configuration for a specific platform using the --platform flag.

```bash
oras manifest fetch-config --platform 'linux/arm/v5' localhost:5000/hello:v1
```

--------------------------------

### Push blob 'hi.txt' to a registry

Source: https://oras.land/docs/commands/oras_blob_push

Pushes the file 'hi.txt' to the registry at localhost:5000 under the repository 'hello'.

```bash
oras blob push localhost:5000/hello hi.txt  
```
Tokens:
Raw