### Add Go Binaries to PATH for E2E Tests

Source: https://github.com/agoda-com/oras-macos-vz/blob/feature/macos-vz-kubelet/test/e2e/README.md

Appends the Go binary directory (where tools like `ginkgo` are installed) to the system's PATH environment variable. This is a workaround for the "ginkgo: not found" error encountered when running E2E tests.

```shell
PATH+=:$(go env GOPATH)/bin
```

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

### Example ORAS Discover Tree Output (Console)

Source: https://github.com/agoda-com/oras-macos-vz/blob/feature/macos-vz-kubelet/docs/proposals/formatted-output.md

An example of the console output produced by the `oras discover` command when using the `--format tree` flag. It illustrates the tree structure showing the artifact reference and its associated referrers, grouped by artifact type, along with their digests.

```Console
$REGISTRY/$REPO@sha256:a3785f78ab8547ae2710c89e627783cfa7ee7824d3468cae6835c9f4eae23ff7
├── application/vnd.cncf.notary.signature
│   └── sha256:8dee8cb9a1334595545e3baf15c3eeed13c4b35ae08e3ab32e1df31fb152dc1d
└── sbom/example
    └── sha256:50fd0dc107d84b5e7b402688000a7ed3aaf8a2692d5cb74da5277fa3c4cecf15
```

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

### Example ORAS Discover JSON Output (JSON)

Source: https://github.com/agoda-com/oras-macos-vz/blob/feature/macos-vz-kubelet/docs/proposals/formatted-output.md

An example of the JSON output produced by the `oras discover` command when using the `--format json` flag. It shows a list of referrer manifests, each containing details such as `reference`, `mediaType`, `digest`, `size`, `annotations`, and `artifactType`, demonstrating how multiple referrers are represented in the JSON array.

```JSON
{
  "manifests": [
    {
      "reference": "$REGISTRY/$REPO@sha256:8dee8cb9a1334595545e3baf15c3eeed13c4b35ae08e3ab32e1df31fb152dc1d",
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "digest": "sha256:8dee8cb9a1334595545e3baf15c3eeed13c4b35ae08e3ab32e1df31fb152dc1d",
      "size": 739,
      "annotations": {
        "io.cncf.notary.x509chain.thumbprint#S256": "[\"79e91aa1e109a16df87d200e493fd3d33c67253f76d41334d7f7c29c00ba55b3\"]",
        "org.opencontainers.image.created": "2024-01-01T10:32:55Z"
      },
      "artifactType": "application/vnd.cncf.notary.signature"
    },
    {
      "reference": "$REGISTRY/$REPO@sha256:50fd0dc107d84b5e7b402688000a7ed3aaf8a2692d5cb74da5277fa3c4cecf15",
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "digest": "sha256:50fd0dc107d84b5e7b402688000a7ed3aaf8a2692d5cb74da5277fa3c4cecf15",
      "size": 739,
      "annotations": {
        "org.opencontainers.image.created": "2024-01-01T07:57:10Z"
      },
      "artifactType": "sbom/example"
    }
  ]
}
```

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

### Example Filtered Output for ORAS Push with Go Template (Console)

Source: https://github.com/agoda-com/oras-macos-vz/blob/feature/macos-vz-kubelet/docs/proposals/formatted-output.md

This is an example of the filtered output produced by `oras push` when using the Go template `{{.reference}}, {{.mediaType}}`. It shows the extracted artifact reference and media type on a single line.

```console
$REGISTRY/$REPO@sha256:85438e6598bf35057962fff34399a362d469ca30a317939427fca6b7a289e70d, application/vnd.oci.image.manifest.v1+json
```

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

### Example Compact JSON Output for ORAS Pull with Go Template (Console)

Source: https://github.com/agoda-com/oras-macos-vz/blob/feature/macos-vz-kubelet/docs/proposals/formatted-output.md

This is an example of the compact JSON output produced by `oras pull` when using the Go template `{{toRawJson .}}`. It contains the same data as the pretty JSON example but without indentation or line breaks.

```console
{"reference":"localhost:5000/oras@sha256:7414904f07f515f48fe4afeaf876e3151039a81e7177b9c66e9e7ed6dd186111","files":[{"path":"/home/user/oras-install/sbom.spdx","reference":"localhost:5000/oras@sha256:7414904f07f515f48fe4afeaf876e3151039a81e7177b9c66e9e7ed6dd186222","mediaType":"application/vnd.oci.image.manifest.v1+json","digest":"sha256:7414904f07f515f48fe4afeaf876e3151039a81e7177b9c66e9e7ed6dd186222","size":820},{"path":"/home/user/oras-install/vul-scan.json","reference":"localhost:5000/oras@sha256:7414904f07f515f48fe4afeaf876e3151039a81e7177b9c66e9e7ed6dd18669b","mediaType":"application/vnd.oci.image.manifest.v1+json","digest":"sha256:7414904f07f515f48fe4afeaf876e3151039a81e7177b9c66e9e7ed6dd18669b","size":820}]}
```

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

### Example Filtered ORAS Manifest Config JSON Output

Source: https://github.com/agoda-com/oras-macos-vz/blob/feature/macos-vz-kubelet/docs/proposals/formatted-output.md

Provides an example of the JSON output generated by the `oras manifest fetch` command when using a Go template to filter for the `.content.config` section, showing the extracted configuration details in a prettified JSON format.

```json
{
  "digest": "sha256:b6f50765242581c887ff1acc2511fa2d885c52d8fb3ac8c4bba131fd86567f2e",
  "mediaType": "application/vnd.docker.container.image.v1+json",
  "size": 3362
}
```

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

### Specifying Reference for ORAS Manifest Fetch

Source: https://github.com/agoda-com/oras-macos-vz/blob/feature/macos-vz-kubelet/docs/proposals/error-handling-guideline.md

Demonstrates the error when fetching a manifest without providing a tag or digest and offers a suggested error message explaining the required reference format.

```console
$ oras manifest fetch --oci-layout /tmp/ginkgo1163328512
Error: "/tmp/ginkgo1163328512": no tag or digest when expecting <name:tag|name@digest>
```

```console
$ oras manifest fetch --oci-layout /tmp/ginkgo1163328512
Error: "/tmp/ginkgo1163328512": no tag or digest specified
Usage: oras manifest fetch [flags] <name>{:<tag>|@<digest>}
You need to specify an artifact reference in the form of "<name>:<tag>" or "<name>@<digest>". Run "oras manifest fetch -h" for more options and examples
```

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

### Pulling and Processing ORAS Artifact Layers (YAML/Shell)

Source: https://github.com/agoda-com/oras-macos-vz/blob/feature/macos-vz-kubelet/docs/proposals/formatted-output.md

Demonstrates installing ORAS using the `setup-oras` GitHub Action and executing a shell script that pulls an artifact, extracts the path of the first layer using a Go template, and pipes that path to the `cat` command for further processing.

```yaml
jobs:
  example-job:
    steps:
      - uses: oras-project/setup-oras@v1
      - run: |
          PATH=`oras pull $REGISTRY/$REPO:$TAG --format go-template='{{(first .files).path}}'`
          cat $PATH
```

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

### Pushing Artifacts with ORAS and Formatting Output with Go Template (Bash)

Source: https://github.com/agoda-com/oras-macos-vz/blob/feature/macos-vz-kubelet/docs/proposals/formatted-output.md

Run `oras push` and use the `--format go-template` flag to customize the output. This example uses a template `{{.reference}}, {{.mediaType}}` to extract and display only the artifact's reference and media type, separated by a comma.

```bash
oras push $REGISTRY/$REPO:$TAG sample-folder --format go-template='{{.reference}}, {{.mediaType}}'
```

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

### Example Prettified ORAS Manifest JSON Output

Source: https://github.com/agoda-com/oras-macos-vz/blob/feature/macos-vz-kubelet/docs/proposals/formatted-output.md

Provides an example of the prettified JSON output generated by the `oras manifest fetch --format json` command, showing the detailed structure of the manifest including reference, media type, digest, size, artifact type, and content details.

```json
{
  "reference": " $REGISTRY/$REPO@sha256:8be4c36a29979c72fdd225654498791fb381a7dd8332ade1981274a16220fe1c",
  "schemaVersion": 2,
  "mediaType": "application/vnd.oci.image.manifest.v1+json",
  "digest": "sha256:8be4c36a29979c72fdd225654498791fb381a7dd8332ade1981274a16220fe1c",
  "artifactType": "application/vnd.unknown.artifact.v1",
  "content": {
    "config": {
      "mediaType": "application/vnd.oci.empty.v1+json",
      "digest": "sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a",
      "size": 2
    },
    "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"
    }
  }
}
```

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

### Example ORAS Attach JSON Output (JSON)

Source: https://github.com/agoda-com/oras-macos-vz/blob/feature/macos-vz-kubelet/docs/proposals/formatted-output.md

An example of the JSON output produced by the `oras attach` command when using the `--format json` flag. It shows the structure and fields included in the descriptor metadata for the attached referrer, such as `reference`, `mediaType`, `digest`, `size`, `annotations`, and `artifactType`.

```JSON
{
  "reference": "$REGISTRY/$REPO@sha256:0afd0f0c35f98dcb607de0051be7ebefd942eef1e3a6d26eefd1b2d80f2affbe",
  "mediaType": "application/vnd.oci.image.manifest.v1+json",
  "digest": "sha256:0afd0f0c35f98dcb607de0051be7ebefd942eef1e3a6d26eefd1b2d80f2affbe",
  "size": 923,
  "annotations": {
    "org.opencontainers.image.created": "2023-12-15T08:59:21Z"
  },
  "artifactType": "example/report-and-sbom"
}
```

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

### Prepare ORAS E2E Test Environment

Source: https://github.com/agoda-com/oras-macos-vz/blob/feature/macos-vz-kubelet/test/e2e/README.md

Executes the preparation script for the ORAS E2E test environment. It first determines the root directory of the Git repository and then runs the `prepare.sh` script located within the test directory, passing the repository root as an argument.

```shell
REPO_ROOT=$(git rev-parse --show-toplevel)
$REPO_ROOT/test/e2e/scripts/prepare.sh $REPO_ROOT
```

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

### Correcting Misuse of ORAS Tag Command

Source: https://github.com/agoda-com/oras-macos-vz/blob/feature/macos-vz-kubelet/docs/proposals/error-handling-guideline.md

Illustrates the error when 'oras tag list' is used incorrectly and provides a suggested error message that guides the user to the correct command ('oras repo tags').

```console
$ oras tag list ghcr.io/oras-project/oras
Error: unable to add tag for 'list': invalid reference: missing repository
```

```console
$ oras tag list ghcr.io/oras-project/oras
Error: There is no "list" sub-command for "oras tag" command.
Usage: oras tag [flags] <name>{:<tag>|@<digest>} <new_tag> [...]
If you want to list available tags in a repository, use "oras repo tags"
```

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

### Providing Content for ORAS Attach Command

Source: https://github.com/agoda-com/oras-macos-vz/blob/feature/macos-vz-kubelet/docs/proposals/error-handling-guideline.md

Shows the error when 'oras attach' is called without providing files via arguments or annotations via the '--annotation' flag, and suggests an error message explaining how to provide content.

```console
$ oras attach --artifact-type sbom/example localhost:5000/sample/images:foobar
Error: no blob is provided
```

```console
$ oras attach --artifact-type sbom/example localhost:5000/sample/images:foobar
Error: neither file nor annotation provided in the command
Usage: oras attach [flags] --artifact-type=<type> <name>{:<tag>|@<digest>} <file>[:<type>] [...]
To attach to an existing artifact, please provide files via argument or annotations via flag "--annotation". Run "oras attach -h" for more options and examples
```

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

### Handling Missing Arguments in ORAS Copy Command

Source: https://github.com/agoda-com/oras-macos-vz/blob/feature/macos-vz-kubelet/docs/proposals/error-handling-guideline.md

Shows the default error message when 'oras copy' receives no arguments and presents a suggested, more informative error message with correct usage instructions.

```console
$ oras cp
Error: accepts 2 arg(s), received 0
```

```console
$ oras cp
Error: "oras copy" requires exactly 2 arguments but received 0.
Usage: oras copy [flags] <from>{:<tag>|@<digest>} <to>[:<tag>[,<tag>][...]]
Please specify 2 arguments as source and destination respectively. Run "oras copy -h" for more options and examples
```

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

### Providing Media Type for ORAS Manifest Push

Source: https://github.com/agoda-com/oras-macos-vz/blob/feature/macos-vz-kubelet/docs/proposals/error-handling-guideline.md

Shows the error when pushing a manifest without specifying the media type and provides a suggested error message indicating how to provide it either via flag or within the manifest JSON.

```console
$ oras manifest push --oci-layout /sample/images:foobar:mediatype manifest.json
Error: media type is not recognized.
```

```console
$ oras manifest push --oci-layout /sample/images:foobar:mediatype manifest.json
Error: media type is not specified via the flag "--media-type" nor in the manifest.json
Usage: oras manifest push [flags] <name>[:<tag>[,<tag>][...]|@<digest>] <file>
You need to specify a valid media type in the manifest JSON or via the "--media-type" flag
```

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

### Watch and Re-run ORAS E2E Tests with Ginkgo

Source: https://github.com/agoda-com/oras-macos-vz/blob/feature/macos-vz-kubelet/test/e2e/README.md

Changes the current directory to the E2E test module root and then starts `ginkgo watch`. This command automatically re-runs tests recursively (`-r`) whenever source files change, facilitating rapid iteration and debugging of re-runnable specs.

```shell
cd $REPO_ROOT/test/e2e
ginkgo watch -r
```

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

### Pushing Without Specifying Registry/Repo (oras)

Source: https://github.com/agoda-com/oras-macos-vz/blob/feature/macos-vz-kubelet/docs/proposals/error-handling-guideline.md

Illustrates the error encountered when attempting to push a folder using the oras CLI without providing a valid registry and repository reference, showing the current and a more informative suggested error message.

```console
$ oras push /oras --format json
Error: Head "https:///v2/oras/manifests/sha256:ffa50b27cd0096150c0338779c5090db41ba50d01179d851d68afa50b393c3a3": http: no Host in request URL
```

```console
$ oras push /oras --format json
Error: "/oras" is an invalid reference
Usage: oras push [flags] <name>[:<tag>[,<tag>][...]] <file>[:<type>] [...]
Please specify a valid reference in the form of <registry>/<repo>[:tag|@digest]
```

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

### Run ORAS E2E Tests using Make

Source: https://github.com/agoda-com/oras-macos-vz/blob/feature/macos-vz-kubelet/test/e2e/README.md

Command to execute the end-to-end test suite for the ORAS CLI using the `make` build tool. This command should be run from the root directory of the ORAS CLI code.

```shell
make teste2e
```

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

### Recommended ORAS Error Message Structure

Source: https://github.com/agoda-com/oras-macos-vz/blob/feature/macos-vz-kubelet/docs/proposals/error-handling-guideline.md

Provides a general template for structuring ORAS CLI error messages, including optional fields for HTTP status, command usage, and recommended solutions.

```text
{
  Error|Error response from registry
}: {
  Error description (HTTP status code can be printed out if any)
}
[Usage: {
  Command usage
}]
[{
  Recommended solution
}]
```

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

### Pushing Non-Existent File/Folder (oras)

Source: https://github.com/agoda-com/oras-macos-vz/blob/feature/macos-vz-kubelet/docs/proposals/error-handling-guideline.md

Shows the error message displayed when the oras CLI is instructed to push a file or folder that does not exist on the local filesystem, presenting both the current and a simplified suggested error.

```console
$ oras push localhost:5000/oras:v1 hello.txt
Error: failed to stat /home/user/hello.txt: stat /home/user/hello.txt: no such file or directory
```

```console
$ oras push localhost:5000/oras:v1 hello.txt
Error: /home/user/hello.txt: no such file or directory
```

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

### Authentication Failure with Credential Store (oras)

Source: https://github.com/agoda-com/oras-macos-vz/blob/feature/macos-vz-kubelet/docs/proposals/error-handling-guideline.md

Demonstrates the error message received when the oras CLI fails to authenticate with a registry using credentials provided via a configuration file, showing the current generic error and a more specific suggested message.

```console
$ oras pull localhost:7000/repo:tag --registry-config auth.config
Error: failed to resolve tag: GET "http://localhost:7000/v2/repo/manifests/tag": credential required for basic auth
```

```console
$ oras pull localhost:7000/repo:tag --registry-config auth.config
Error: failed to authenticate when attempting to pull: no valid credential found in auth.config
Please check whether the registry credential stored in the authentication file is correct
```

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

### Example JSON Output for ORAS Push (JSON)

Source: https://github.com/agoda-com/oras-macos-vz/blob/feature/macos-vz-kubelet/docs/proposals/formatted-output.md

This JSON object shows the structure and content of the output generated by `oras push` when using the `--format json` flag. It provides details about the pushed manifest, including its reference, media type, digest, size, annotations, artifact type, and the tags it was pushed with.

```json
{
  "reference": "$REGISTRY/$REPO@sha256:4a5b8c83d153f52afdfcb422db56c2349aae3bd5ecf8338a58353b5eb6681c45",
  "mediaType": "application/vnd.oci.image.manifest.v1+json",
  "digest": "sha256:4a5b8c83d153f52afdfcb422db56c2349aae3bd5ecf8338a58353b5eb6681c45",
  "size": 820,
  "annotations": {
    "org.opencontainers.image.created": "2023-12-15T09:41:54Z"
  },
  "artifactType": "json/example",
  "referenceByTags": [
    "$REGISTRY/$REPO:$TAG1",
    "$REGISTRY/$REPO:$TAG2"
  ]
}
```

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

### Handling Unknown Distribution Spec Flag in ORAS Attach

Source: https://github.com/agoda-com/oras-macos-vz/blob/feature/macos-vz-kubelet/docs/proposals/error-handling-guideline.md

Illustrates the error when an unknown value is provided for the '--distribution-spec' flag in 'oras attach' and suggests an error message listing the available valid options.

```console
$ oras attach --artifact-type oras/test localhost:5000/command/images:foobar --distribution-spec v1.0
Error: unknown distribution specification flag: v1.0
```

```console
$ oras attach --artifact-type oras/test localhost:5000/sample/images:foobar --distribution-spec ???
Error: unknown distribution specification flag: "v1.0".
Available options: v1.1-referrers-api, v1.1-referrers-tag
```

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

### Pushing with Invalid Annotation Format (oras)

Source: https://github.com/agoda-com/oras-macos-vz/blob/feature/macos-vz-kubelet/docs/proposals/error-handling-guideline.md

Demonstrates the current and suggested error messages when attempting to push an OCI artifact using the oras CLI with an annotation flag that does not follow the required key=value syntax.

```console
$ oras push --annotation "key:value" ghcr.io/library/alpine:3.9
Error: missing key in `--annotation` flag: key:value
```

```console
$ oras push --annotation "key:value" ghcr.io/library/alpine:3.9
Error: annotation value doesn't match the required format.
Please use the correct format in the flag: --annotation "key=value"
```

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

### Validating Annotation File Format for ORAS Push

Source: https://github.com/agoda-com/oras-macos-vz/blob/feature/macos-vz-kubelet/docs/proposals/error-handling-guideline.md

Demonstrates the error when the JSON file provided to '--annotation-file' in 'oras push' has an invalid format and suggests a clearer error message directing the user to the correct documentation.

```console
$ oras push --annotation-file sbom.json ghcr.io/library/alpine:3.9
Error: failed to load annotations from sbom.json: json: cannot unmarshal string into Go value of type map[string]map[string]string. Please refer to the document at https://oras.land/docs/how_to_guides/manifest_annotations
```

```console
$ oras push --annotation-file annotation.json ghcr.io/library/alpine:3.9
Error: invalid annotation json file: failed to load annotations from annotation.json.
Annotation file doesn't match the required format. Please refer to the document at https://oras.land/docs/how_to_guides/manifest_annotations
```

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

### Example JSON Output for ORAS Pull (JSON)

Source: https://github.com/agoda-com/oras-macos-vz/blob/feature/macos-vz-kubelet/docs/proposals/formatted-output.md

This JSON object illustrates the structure and content of the output generated by `oras pull` when using the `--format json` flag. It shows the main artifact reference and a list of files, each with its descriptor metadata like path, reference, media type, digest, size, and annotations.

```json
{
  "reference": "localhost:5000/oras@sha256:7414904f07f515f48fe4afeaf876e3151039a81e7177b9c66e9e7ed6dd186111",
  "files": [
    {
      "path": "/home/user/oras-install/sbom.spdx",
      "reference": "localhost:5000/oras@sha256:7414904f07f515f48fe4afeaf876e3151039a81e7177b9c66e9e7ed6dd186222",
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "digest": "sha256:7414904f07f515f48fe4afeaf876e3151039a81e7177b9c66e9e7ed6dd186222",
      "size": 820,
      "annotations": {
        "org.opencontainers.image.title": "sbom.spdx"
      }
    },
    {
      "path": "/home/user/oras-install/vul-scan.json",
      "reference": "localhost:5000/oras@sha256:7414904f07f515f48fe4afeaf876e3151039a81e7177b9c66e9e7ed6dd18669b",
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "digest": "sha256:7414904f07f515f48fe4afeaf876e3151039a81e7177b9c66e9e7ed6dd18669b",
      "size": 820,
      "annotations": {
        "org.opencontainers.image.title": "vul-scan.json"
      }
    }
  ]
}
```

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

### Pulling from Public Registry Without Authentication/Namespace (oras)

Source: https://github.com/agoda-com/oras-macos-vz/blob/feature/macos-vz-kubelet/docs/proposals/error-handling-guideline.md

Shows the current and suggested error messages when failing to pull an image from a public registry like Docker Hub, often due to missing authentication or an incorrect namespace (e.g., missing 'library/').

```console
$ oras pull docker.io/nginx:latest
Error: failed to resolve latest: GET "https://registry-1.docker.io/v2/nginx/manifests/latest": response status code 401: unauthorized: authentication required: [map[Action:pull Class: Name:nginx Type:repository]]
```

```console
$ oras pull docker.io/nginx:latest
Error response from registry: pull access denied for docker.io/nginx:latest : unauthorized: requested access to the resource is denied
Namespace is missing, do you mean `oras pull docker.io/library/nginx:latest`?
```

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

### Resolving Digest with Empty Registry Error (oras)

Source: https://github.com/agoda-com/oras-macos-vz/blob/feature/macos-vz-kubelet/docs/proposals/error-handling-guideline.md

Illustrates the scenario where the oras CLI attempts to resolve a digest but receives an empty or uninformative error response from the registry, showing the current output and a suggested message that includes the underlying authentication failure.

```console
oras resolve localhost:7000/command/artifacts:foobar -u t -p 2
WARNING! Using --password via the CLI is insecure. Use --password-stdin.
Error response from registry: <nil>
```

```console
oras resolve localhost:7000/command/artifacts:foobar -u t -p 2
WARNING! Using --password via the CLI is insecure. Use --password-stdin.
Error response from registry: recognizable error message not found: failed to resolve digest: HEAD "http://localhost:7000/v2/test/manifests/bar": response status code 401: Unauthorized
Authentication failed. Please verify your login credentials and try again.
```

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

### Run Specific ORAS E2E Test Suite with Go Test

Source: https://github.com/agoda-com/oras-macos-vz/blob/feature/macos-vz-kubelet/test/e2e/README.md

Runs a specific end-to-end test suite directly using the `go test` command. This allows for native execution and debugging of individual test suites within the ORAS E2E test module. Replace `${suite_name}` with the desired suite name.

```shell
go test oras.land/oras/test/e2e/suite/${suite_name}
```

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

### Chaining ORAS Commands in PowerShell

Source: https://github.com/agoda-com/oras-macos-vz/blob/feature/macos-vz-kubelet/docs/proposals/formatted-output.md

This PowerShell script illustrates chaining ORAS commands by parsing the JSON output using `ConvertFrom-Json`. It pushes an artifact, attaches an SBOM to the pushed artifact using the reference obtained from the push command's JSON output, and then signs the attached SBOM using the reference from the attach command's JSON output. It uses `--format json --no-tty` to get machine-readable JSON output.

```PowerShell
$A=oras push $REGISTRY/$REPO:$TAG hello.txt --format json --no-tty | ConvertFrom-Json
$B=oras attach --artifact-type sbom/example $A.reference sbom.spdx --format json --no-tty | ConvertFrom-Json
notation sign $B.reference
```

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

### Compress Docker Directory for Distribution Test Data

Source: https://github.com/agoda-com/oras-macos-vz/blob/feature/macos-vz-kubelet/test/e2e/README.md

Creates a gzipped tar archive (`.tar.gz`) of the `docker/` directory. This command is used to compress registry runtime storage data for creating layered distribution test data, setting owner and group to 0 for consistency. The archive is named based on a repository suffix.

```shell
tar -cvzf ${repo_suffix}.tar.gz --owner=0 --group=0 docker/
```

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

### Fetch ORAS Manifest to File and Format Output (Bash)

Source: https://github.com/agoda-com/oras-macos-vz/blob/feature/macos-vz-kubelet/docs/proposals/formatted-output.md

Demonstrates fetching an ORAS manifest, saving the full manifest content to a local file (`--output`), and simultaneously printing a specific field (`.content.config.mediaType`) to the console using a Go template specified via the `--format` flag. Note that `--output -` is incompatible with `--format`.

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

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

### Attaching Files with ORAS and JSON Output (Bash)

Source: https://github.com/agoda-com/oras-macos-vz/blob/feature/macos-vz-kubelet/docs/proposals/formatted-output.md

Demonstrates using the `oras attach` command to attach two files (`vul-report.json` and `sbom.spdx`) to a specified image reference (`$REGISTRY/$REPO:$TAG`). It sets the artifact type to `example/report-and-sbom` and uses the `--format json` flag to output the referrer descriptor metadata in JSON format.

```Bash
oras attach $REGISTRY/$REPO:$TAG --artifact-type example/report-and-sbom vul-report.json:example/vul-scan sbom.spdx:example/sbom --format json
```

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

### View Saved ORAS Manifest File (Bash)

Source: https://github.com/agoda-com/oras-macos-vz/blob/feature/macos-vz-kubelet/docs/proposals/formatted-output.md

Shows how to display the content of the `sample-manifest` file created by the previous `oras manifest fetch` command, illustrating the compact JSON format of the saved manifest data.

```bash
cat sample-manifest
```

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

### Fetch ORAS Manifest with Go Template Filtering (Bash)

Source: https://github.com/agoda-com/oras-macos-vz/blob/feature/macos-vz-kubelet/docs/proposals/formatted-output.md

Fetches an ORAS manifest using `oras manifest fetch` and applies a custom Go template (`--template`) via the `--format go-template` flag to filter and format the output, specifically extracting and pretty-printing only the `.content.config` section of the manifest.

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

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

### Verifying Local Files Against ORAS Manifest Checksums (Bash)

Source: https://github.com/agoda-com/oras-macos-vz/blob/feature/macos-vz-kubelet/docs/proposals/formatted-output.md

Shows how to fetch an ORAS artifact manifest without pulling the content. It uses a Go template to format the output into a list of checksums and filenames, which is then piped to `shasum -c` to verify the integrity of corresponding local files.

```bash
oras manifest fetch $REGISTRY/$REPO:$TAG --format go-template='{{range .content.layers}}{{if index .annotations "org.opencontainers.image.title"}}{{(split ":" .digest)._1}}  {{index .annotations "org.opencontainers.image.title"}}{{println}}{{end}}{{end}}' | shasum -c
```

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

### Attaching Artifact with v1.1 Referrers API Spec (Bash)

Source: https://github.com/agoda-com/oras-macos-vz/blob/feature/macos-vz-kubelet/docs/proposals/compatibility-mode.md

This command attaches an artifact (sbom.json) to a target manifest, configuring distribution compatibility using the v1.1-referrers-api option. This option requires a registry compliant with OCI v1.1 and Referrers API support.

```Bash
oras attach localhost:5000/hello-world:v1 \
  --artifact-type sbom/example \
  --distribution-spec v1.1-referrers-api \
  sbom.json
```

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

### Discovering ORAS Referrers in JSON Format (Bash)

Source: https://github.com/agoda-com/oras-macos-vz/blob/feature/macos-vz-kubelet/docs/proposals/formatted-output.md

Demonstrates using the `oras discover` command to retrieve the referrers for a specific artifact reference (`$REGISTRY/$REPO:v1`). The `--format json` flag is used to output the list of referrers and their manifest details in JSON format, including fields like `reference`, `mediaType`, `size`, `digest`, `artifactType`, and `annotations`.

```Bash
oras discover $REGISTRY/$REPO:v1 --format json
```

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

### Pushing Artifacts with ORAS and Formatting Output as JSON (Bash)

Source: https://github.com/agoda-com/oras-macos-vz/blob/feature/macos-vz-kubelet/docs/proposals/formatted-output.md

Use the `oras push` command with the `--format json` flag to push artifacts (files or folders) and display detailed metadata about the pushed artifact's image manifest in a pretty JSON format. The output includes the artifact reference, media type, digest, size, annotations, artifact type, and a list of references by tags.

```bash
oras push $REGISTRY/$REPO:$TAG1,$TAG2 sbom.spdx vul-scan.json --format json
```

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

### Fetch ORAS Manifest with JSON Format (Bash)

Source: https://github.com/agoda-com/oras-macos-vz/blob/feature/macos-vz-kubelet/docs/proposals/formatted-output.md

Fetches an ORAS manifest from a registry and outputs its metadata directly to the standard output in a prettified JSON format using the `--format json` flag.

```bash
oras manifest fetch $REGISTRY/$REPO:$TAG --format json
```

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

### Chaining ORAS Commands in Bash

Source: https://github.com/agoda-com/oras-macos-vz/blob/feature/macos-vz-kubelet/docs/proposals/formatted-output.md

This Bash script demonstrates how to chain ORAS commands by capturing the output reference of one command and using it as input for the next. It pushes an artifact, attaches an SBOM to the pushed artifact using its reference, and then signs the attached SBOM using its reference. It utilizes the `--format go-template='{{.reference}}'` option to extract the artifact reference directly.

```Bash
REFERENCE_A=$(oras push $REGISTRY/$REPO:$TAG hello.txt --format go-template='{{.reference}}')
REFERENCE_B=$(oras attach --artifact-type sbom/example $REFERENCE_A sbom.spdx --format go-template='{{.reference}}') 
notation sign $REFERENCE_B
```

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

### Attaching Artifact with v1.1 Referrers Tag Spec (Bash)

Source: https://github.com/agoda-com/oras-macos-vz/blob/feature/macos-vz-kubelet/docs/proposals/compatibility-mode.md

This command attaches an artifact (sbom.json) to a target manifest, configuring distribution compatibility using the v1.1-referrers-tag option. This option provides maximum backward compatibility by attempting to use the referrers tag schema.

```Bash
oras attach localhost:5000/hello-world:v1 \
  --artifact-type sbom/example \
  --distribution-spec v1.1-referrers-tag \
  sbom.json
```

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

### Discovering ORAS Referrers in Tree View (Bash)

Source: https://github.com/agoda-com/oras-macos-vz/blob/feature/macos-vz-kubelet/docs/proposals/formatted-output.md

Shows how to use the `oras discover` command to list the referrers associated with a specific artifact reference (`$REGISTRY/$REPO:$TAG`). The `--format tree` flag is used to display the referrers in a hierarchical tree structure, which is also the default format.

```Bash
oras discover $REGISTRY/$REPO:$TAG --format tree
```

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

### Pulling Artifacts with ORAS and Formatting Output as JSON (Bash)

Source: https://github.com/agoda-com/oras-macos-vz/blob/feature/macos-vz-kubelet/docs/proposals/formatted-output.md

Use the `oras pull` command with the `--format json` flag to download artifacts and display detailed metadata about the pulled artifact and its layers (files) in a pretty JSON format. This output includes the artifact reference, a list of downloaded files with their paths, references, media types, digests, sizes, and annotations.

```bash
oras pull $REGISTRY/$REPO:$TAG --artifact-type example/sbom sbom.spdx  --artifact-type example/vul-scan vul-scan.json --format json
```

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

### Pushing OCI Image Manifest with v1.0 Spec (Bash)

Source: https://github.com/agoda-com/oras-macos-vz/blob/feature/macos-vz-kubelet/docs/proposals/compatibility-mode.md

This command pushes an OCI image manifest to a local registry, explicitly specifying the OCI Image-spec v1.0 for compatibility with older registries. It includes an artifact type and the file to push.

```Bash
oras push localhost:5000/hello-world:v1 \
  --image-spec v1.0 \
  --artifact-type application/vnd.me.config \
  sbom.json
```

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

### Pulling Artifacts with ORAS and Formatting Output with Go Template (Bash)

Source: https://github.com/agoda-com/oras-macos-vz/blob/feature/macos-vz-kubelet/docs/proposals/formatted-output.md

Execute `oras pull` and use the `--format go-template` flag with `{{toRawJson .}}` to output the entire result object as a compact, raw JSON string. This is useful for scripting or piping the output to other tools that expect single-line JSON.

```bash
oras pull $REGISTRY/$REPO:$TAG --format go-template='{{toRawJson .}}'
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.