# oras-project/oras architecture

> Architecture diagram of the GitHub repository oras-project/oras, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/oras-project/oras
- Repository: https://github.com/oras-project/oras

## Overview

ORAS CLI transfers and manages OCI artifacts in registries and OCI layouts. Users invoke commands to resolve references, move or inspect manifests and blobs, and receive formatted metadata or progress. The clearest sampled workflow is copy: it prepares source and destination targets, applies graph-copy options, transfers artifact content, then may tag additional references. The tree also exposes pull/push, discovery, backup/restore, repository, manifest, and authentication command families. Command wiring beyond the sampled copy and display-handler code is inferred only at the subsystem level; those detailed links are omitted.

Main entry points: [`cmd/oras/root/cmd.go`](https://github.com/oras-project/oras/blob/main/cmd/oras/root/cmd.go) (Command root), [`cmd/oras/root/cp.go`](https://github.com/oras-project/oras/blob/main/cmd/oras/root/cp.go) (Copy artifacts), [`cmd/oras/internal/option/target.go`](https://github.com/oras-project/oras/blob/main/cmd/oras/internal/option/target.go) (Target options), [`cmd/oras/internal/display/handler.go`](https://github.com/oras-project/oras/blob/main/cmd/oras/internal/display/handler.go) (Display handlers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI commands"]
  node_main["CLI entry<br/>[main.go]"]
  node_root["Command root<br/>[cmd.go]"]
  node_transfer_commands["Pull and push<br/>[pull.go]"]
  node_copy["Copy artifacts<br/>[cp.go]"]
  node_discovery["Discover artifacts<br/>[discover.go]"]
  node_manifest_commands["Manifest operations"]
  node_blob_commands["Blob operations"]
  node_repo_commands["Repository queries"]
  node_backup_restore["Backup and restore<br/>[backup.go]"]
  node_auth_commands["Registry login<br/>[login.go]"]
end

subgraph group_transfer["Artifact transfer"]
  node_targets["Target options<br/>[target.go]"]
  node_content_util["Content traversal<br/>[traverse.go]"]
  node_graph_logic["Artifact graph<br/>[graph.go]"]
end

subgraph group_registry["Registry access"]
  node_registry_service{{"OCI registries"}}
  node_oci_layout[("OCI layouts")]
end

subgraph group_presentation["Output and status"]
  node_handler_factory["Display handlers<br/>[handler.go]"]
  node_output["Formatted output<br/>[print.go]"]
  node_progress["Transfer progress<br/>[manager.go]"]
end

subgraph group_shared["Shared runtime"]
  node_repository_parse["Reference parsing<br/>[repository.go]"]
end

node_user(("CLI user"))

node_user -->|"invokes"| node_main
node_main -->|"executes"| node_root
node_root -->|"dispatches"| node_transfer_commands
node_root -->|"dispatches"| node_copy
node_root -->|"dispatches"| node_discovery
node_root -->|"dispatches"| node_manifest_commands
node_root -->|"dispatches"| node_blob_commands
node_root -->|"dispatches"| node_repo_commands
node_root -->|"dispatches"| node_backup_restore
node_root -->|"dispatches"| node_auth_commands
node_copy -->|"creates targets"| node_targets
node_copy -->|"uses graph traversal"| node_graph_logic
node_copy -->|"copies content"| node_registry_service
node_targets -->|"accesses"| node_registry_service
node_targets -.->|"accesses"| node_oci_layout
node_copy -->|"wraps destination"| node_content_util
node_copy -->|"selects handlers"| node_handler_factory
node_handler_factory -->|"formats metadata"| node_output
node_handler_factory -->|"selects status"| node_progress
node_copy -->|"parses references"| node_repository_parse

click node_main "https://github.com/oras-project/oras/blob/main/cmd/oras/main.go"
click node_root "https://github.com/oras-project/oras/blob/main/cmd/oras/root/cmd.go"
click node_transfer_commands "https://github.com/oras-project/oras/blob/main/cmd/oras/root/pull.go"
click node_copy "https://github.com/oras-project/oras/blob/main/cmd/oras/root/cp.go"
click node_discovery "https://github.com/oras-project/oras/blob/main/cmd/oras/root/discover.go"
click node_manifest_commands "https://github.com/oras-project/oras/tree/main/cmd/oras/root/manifest"
click node_blob_commands "https://github.com/oras-project/oras/tree/main/cmd/oras/root/blob"
click node_repo_commands "https://github.com/oras-project/oras/tree/main/cmd/oras/root/repo"
click node_backup_restore "https://github.com/oras-project/oras/blob/main/cmd/oras/root/backup.go"
click node_auth_commands "https://github.com/oras-project/oras/blob/main/cmd/oras/root/login.go"
click node_targets "https://github.com/oras-project/oras/blob/main/cmd/oras/internal/option/target.go"
click node_content_util "https://github.com/oras-project/oras/blob/main/internal/contentutil/traverse.go"
click node_graph_logic "https://github.com/oras-project/oras/blob/main/internal/graph/graph.go"
click node_handler_factory "https://github.com/oras-project/oras/blob/main/cmd/oras/internal/display/handler.go"
click node_output "https://github.com/oras-project/oras/blob/main/cmd/oras/internal/output/print.go"
click node_progress "https://github.com/oras-project/oras/blob/main/cmd/oras/internal/display/status/progress/manager.go"
click node_repository_parse "https://github.com/oras-project/oras/blob/main/internal/repository/repository.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_root,node_transfer_commands,node_copy,node_discovery,node_manifest_commands,node_blob_commands,node_repo_commands,node_backup_restore,node_auth_commands,node_user toneBlue
class node_targets,node_content_util,node_graph_logic toneAmber
class node_registry_service,node_oci_layout toneMint
class node_handler_factory,node_output,node_progress toneRose
class node_repository_parse toneIndigo
```

## Components

### CLI commands

- [CLI entry](https://github.com/oras-project/oras/blob/main/cmd/oras/main.go): `cmd/oras/main.go`
- [Command root](https://github.com/oras-project/oras/blob/main/cmd/oras/root/cmd.go): `cmd/oras/root/cmd.go`
- [Pull and push](https://github.com/oras-project/oras/blob/main/cmd/oras/root/pull.go): `cmd/oras/root/pull.go`
- [Copy artifacts](https://github.com/oras-project/oras/blob/main/cmd/oras/root/cp.go): `cmd/oras/root/cp.go`
- [Discover artifacts](https://github.com/oras-project/oras/blob/main/cmd/oras/root/discover.go): `cmd/oras/root/discover.go`
- [Manifest operations](https://github.com/oras-project/oras/tree/main/cmd/oras/root/manifest): `cmd/oras/root/manifest`
- [Blob operations](https://github.com/oras-project/oras/tree/main/cmd/oras/root/blob): `cmd/oras/root/blob`
- [Repository queries](https://github.com/oras-project/oras/tree/main/cmd/oras/root/repo): `cmd/oras/root/repo`
- [Backup and restore](https://github.com/oras-project/oras/blob/main/cmd/oras/root/backup.go): `cmd/oras/root/backup.go`
- [Registry login](https://github.com/oras-project/oras/blob/main/cmd/oras/root/login.go): `cmd/oras/root/login.go`

### Artifact transfer

- [Target options](https://github.com/oras-project/oras/blob/main/cmd/oras/internal/option/target.go): `cmd/oras/internal/option/target.go`
- [Content traversal](https://github.com/oras-project/oras/blob/main/internal/contentutil/traverse.go): `internal/contentutil/traverse.go`
- [Artifact graph](https://github.com/oras-project/oras/blob/main/internal/graph/graph.go): `internal/graph/graph.go`

### Registry access

- **OCI registries**
- **OCI layouts**

### Output and status

- [Display handlers](https://github.com/oras-project/oras/blob/main/cmd/oras/internal/display/handler.go): `cmd/oras/internal/display/handler.go`
- [Formatted output](https://github.com/oras-project/oras/blob/main/cmd/oras/internal/output/print.go): `cmd/oras/internal/output/print.go`
- [Transfer progress](https://github.com/oras-project/oras/blob/main/cmd/oras/internal/display/status/progress/manager.go): `cmd/oras/internal/display/status/progress/manager.go`

### Shared runtime

- [Reference parsing](https://github.com/oras-project/oras/blob/main/internal/repository/repository.go): `internal/repository/repository.go`

### Other components

- **CLI user**

## Connections

- CLI user → CLI entry: invokes
- CLI entry → Command root: executes
- Command root → Pull and push: dispatches
- Command root → Copy artifacts: dispatches
- Command root → Discover artifacts: dispatches
- Command root → Manifest operations: dispatches
- Command root → Blob operations: dispatches
- Command root → Repository queries: dispatches
- Command root → Backup and restore: dispatches
- Command root → Registry login: dispatches
- Copy artifacts → Target options: creates targets
- Copy artifacts → Artifact graph: uses graph traversal
- Copy artifacts → OCI registries: copies content
- Target options → OCI registries: accesses
- Target options → OCI layouts: accesses
- Copy artifacts → Content traversal: wraps destination
- Copy artifacts → Display handlers: selects handlers
- Display handlers → Formatted output: formats metadata
- Display handlers → Transfer progress: selects status
- Copy artifacts → Reference parsing: parses references