.nh
.TH podman-artifact-extract 1
.SH WARNING: Experimental command
\fIThis command is considered experimental and still in development. Inputs, options, and outputs are all
subject to change.\fP

.SH NAME
podman-artifact-extract \- Extract an OCI artifact to a local path

.SH SYNOPSIS
\fBpodman artifact extract\fP \fIartifact\fP \fItarget\fP

.SH DESCRIPTION
Extract the blobs of an OCI artifact to a local file or directory.

.PP
If the target path is a file or does not exist, the artifact must either consist
of one blob (layer) or if it has multiple blobs (layers) then the \fB--digest\fP or
\fB--title\fP option must be used to select only a single blob. If the file already
exists it will be overwritten.

.PP
If the target is a directory (it must exist), all blobs will be copied to the
target directory. As the target file name the value from the \fBorg.opencontainers.image.title\fR
annotation is used. If the annotation is missing, the target file name will be the
digest of the blob (with \fB:\fR replaced by \fB-\fR in the name).
If the target file already exists in the directory, it will be overwritten.

.SH OPTIONS
.SS \fB--digest\fP=\fBdigest\fP
When extracting blobs from the artifact only use the one with the specified digest.
If the target is a directory then the digest is always used as file name instead even
when the title annotation exists on the blob.
Conflicts with \fB--title\fP\&.

.SS \fB--help\fP
Print usage statement.

.SS \fB--title\fP=\fBtitle\fP
When extracting blobs from the artifact only use the one with the specified title.
It looks for the \fBorg.opencontainers.image.title\fR annotation and compares that
against the given title.
Conflicts with \fB--digest\fP\&.

.SH EXAMPLES
Extract an artifact with a single blob

.EX
$ podman artifact extract quay.io/artifact/foobar1:test /tmp/myfile
.EE

.PP
Extract an artifact with multiple blobs

.EX
$ podman artifact extract quay.io/artifact/foobar2:test /tmp/mydir
$ ls /tmp/mydir
CONTRIBUTING.md  README.md
.EE

.PP
Extract only a single blob from an artifact with multiple blobs

.EX
$ podman artifact extract --title README.md quay.io/artifact/foobar2:test /tmp/mydir
$ ls /tmp/mydir
README.md
.EE

.PP
Or using the digest instead of the title

.EX
$ podman artifact extract --digest sha256:c0594e012b17fd9e6548355ceb571a79613f7bb988d7d883f112513601ac6e9a quay.io/artifact/foobar2:test /tmp/mydir
$ ls /tmp/mydir
README.md
.EE

.SH SEE ALSO
\fBpodman(1)\fP, \fBpodman-artifact(1)\fP

.SH HISTORY
Feb 2025, Originally compiled by Paul Holzinger pholzing@redhat.com
\[la]mailto:pholzing@redhat.com\[ra]