.nh
.TH umoci-stat(1) # umoci stat - Display status information about an image tag
Aleksa Sarai
SEPTEMBER 2018

.SH NAME
.PP
umoci stat - Display status information about an image tag


.SH SYNOPSIS
.PP
\fBumoci stat\fP
\fB--image\fP=\fIimage\fP[:\fItag\fP]
[\fB--json\fP]


.SH DESCRIPTION
.PP
Generates various pieces of status information about an image tag, including
the history of the image.

.PP
\fBWARNING\fP: Do not depend on the output of this tool. Previously we
recommended the use of \fB--json\fP as the "stable" interface but this interface
will be reworked in future.


.SH OPTIONS
.PP
The global options are defined in \fBumoci\fP(1).

.PP
\fB--image\fP=\fIimage\fP[:\fItag\fP]
  The OCI image tag to display information about. \fIimage\fP must be a path to a
  valid OCI image and \fItag\fP must be a valid tag in the image. If \fItag\fP is not
  provided it defaults to "latest".

.PP
\fB--json\fP
  Output the status information as a JSON encoded blob.


.SH FORMAT
.PP
The format of the \fB--json\fP blob is as follows. Many of these fields come from
the OCI image specification
\[la]https://github.com/opencontainers/image-spec\[ra]\&.

.PP
.RS

.nf
{
  # This is the set of history entries for the image.
  "history": [
    {
      "layer":       <descriptor>, # null if empty_layer is true
      "diff_id":     <diffid>,
      "created":     <created>,
      "created_by":  <created_by>,
      "author":      <author>,
      "empty_layer": <empty_layer>
    }...
  ]
}

.fi
.RE

.PP
In future versions of \fBumoci\fP(1) there may be extra fields added to the above
structure. However, the currently defined fields will always be set (until a
backwards-incompatible release is made).


.SH EXAMPLE
.PP
The following gets information about an image downloaded from a \fBdocker\fP(1)
registry using \fBskopeo\fP(1).

.PP
.RS

.nf
% skopeo copy docker://opensuse/amd64:42.2 oci:image:latest
% umoci stat --image image
LAYER                                                                   CREATED                        CREATED BY                                                                                        SIZE     COMMENT
<none>                                                                  2016-12-05T22:52:33.085510751Z /bin/sh -c #(nop)  MAINTAINER SUSE Containers Team <containers@suse.com>                          <none>
sha256:e800e72a0a88984bd1b47f4eca1c188d3d333dc8e799bfa0a02ea5c2697216d5 2016-12-05T22:52:46.570617134Z /bin/sh -c #(nop) ADD file:6e0044405547c4c209fac622b3c6ddc75e7370682197f7920ec66e4e5e00b180 in /  49.25 MB

.fi
.RE


.SH SEE ALSO
.PP
\fBumoci\fP(1)