# oras pull: Retrieve OCI Artifacts From a Registry

> oras pull downloads the files of an OCI artifact from a registry. Reference for -o output dir, media-type filtering, credentials, and CI errors.

Source: https://latchkey.dev/learn/command-reference/oras-pull-artifact  
Updated: 2026-06-30

oras pull downloads the files stored in an OCI artifact back to the local filesystem, the counterpart to oras push.

Whatever oras push stored (an SBOM, config, or bundle) oras pull retrieves in a later job, reading the artifact directly from the registry.

## What it does

oras pull fetches the layers of an OCI artifact and writes each file to disk, using the file name recorded in the manifest annotations. `-o` sets the output directory; media-type filters can select a subset of layers.

## Common usage

```Terminal
# pull an artifact into ./out
oras pull ghcr.io/acme/configs:v1 -o ./out

# pull by digest for reproducibility
oras pull ghcr.io/acme/bundle@sha256:abc... -o ./bundle

# list what an artifact contains without downloading blobs
oras manifest fetch ghcr.io/acme/bundle:v1 | jq .
```

## Options

| Flag | What it does |
| --- | --- |
| REF | Artifact reference to pull (positional) |
| -o, --output <dir> | Directory to write files into |
| --allowed-media-type <type> | Only pull layers of this media type |
| --plain-http | Use HTTP instead of HTTPS |
| --concurrency N | Number of concurrent blob downloads |

## In CI

oras pull fetches build metadata that a previous stage stored with oras push, without re-running the producer. Pull by digest (`@sha256:...`) when you need the exact bytes a specific run produced.

## Common errors in CI

"Error: no valid credentials found" means run `oras login`. "Error: <ref>: not found" means the artifact reference is wrong. If nothing is written, the layers may all be filtered out by `--allowed-media-type`; drop the filter or match the real type. "http: server gave HTTP response to HTTPS client" needs `--plain-http` for a local registry.

## FAQ

### oras pull: Retrieve OCI Artifacts From a Registry?

Whatever oras push stored (an SBOM, config, or bundle) oras pull retrieves in a later job, reading the artifact directly from the registry.

### What it does?

oras pull fetches the layers of an OCI artifact and writes each file to disk, using the file name recorded in the manifest annotations. -o sets the output directory; media-type filters can select a subset of layers.

### In CI?

oras pull fetches build metadata that a previous stage stored with oras push, without re-running the producer. Pull by digest (@sha256:...) when you need the exact bytes a specific run produced.

### Common errors in CI?

"Error: no valid credentials found" means run oras login. "Error: <ref>: not found" means the artifact reference is wrong. If nothing is written, the layers may all be filtered out by --allowed-media-type; drop the filter or match the real type. "http: server gave HTTP response to HTTPS client" needs --plain-http for a local registry.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt