IBM Cloud Docs
Formatting and filtering the CLI output

Formatting and filtering the CLI output

You can format and filter the IBM Cloud® Container Registry CLI output for supported IBM Cloud Container Registry commands.

By default, the CLI output is displayed in a human-readable format. However, this view might limit your ability to use the output, particularly if the command is run programmatically. For example, in the ibmcloud cr image-list CLI output, you might want to sort the Size field by numerical size, but the command returns a string description of the size. The container-registry CLI plug-in provides the format option that you can use to apply a Go template to the CLI output. The Go template is a feature of the Go programming language that you can use to customize the CLI output.

You can alter the CLI output by applying the format option in two different ways:

  • Format data in your CLI output. For example, change the Created field output from UNIX® time to standard time.
  • Filter data in your CLI output. For example, filter by details of the image to display a specific subset of images by using the Go template if gt condition.

You can use the format option with the following IBM Cloud Container Registry commands. Click a command to view a list of available fields and their data types.

The following code examples demonstrate how you might use the formatting and filtering options.

  • Run the following ibmcloud cr image-digests command to display all untagged images referenced by their digests.

    ibmcloud cr image-digests --format '{{if not .Tags}}{{.Repository}}@{{.Digest}}{{end}}'
    

    The following message is an example of the output from the command

    example-<region>.icr.io/user1/my_first_repo@<digest1>
    example-<region>.icr.io/user1/my_first_repo@<digest2>
    example-<region>.icr.io/user1/my_first_repo@<digest3>
    
  • Run the following ibmcloud cr image-list command to display repository, tag, and security status of all tagged images that have a size over 1 MB.

    ibmcloud cr image-list --format "{{ if gt .Size 1000000 }}{{ .Repository }}:{{ .Tag }} {{ .SecurityStatus.Status }}{{end}}"
    

    The following message is an example of the output from the command:

    example-<region>.icr.io/user1/my_first_repo:latest No Issues
    example-<region>.icr.io/user1/my_second_repo:1 2 Issues
    example-<region>.icr.io/user1/my_second_repo:test1 1 Issue
    example-<region>.icr.io/user1/my_second_repo_2:test2 7 Issues
    

    If the listing images command times out, see Why is it timing out when I list images? for assistance.

  • Run the following ibmcloud cr image-inspect command to display where IBM Documentation is hosted for a specified IBM public image.

    ibmcloud cr image-inspect ibm_public_image --format "{{ .ContainerConfig.Labels }}"
    

    The following message is an example of the output from the command:

    map[doc.url:/docs/images/docker_image_ibm_public_image/ibm_public_image_starter.html]
    
  • Run the following ibmcloud cr image-inspect command to display the exposed ports for a specified image.

    ibmcloud cr image-inspect ibm_public_image --format "{{ .Config.ExposedPorts }}"
    

    The following message is an example of the output from the command:

    map[9080/tcp: 9443/tcp:]
    

Go template options for ibmcloud cr image-digests

Review the following table to find available Go template options and data types for the ibmcloud cr image-digests command.

Table 1. Available fields and data types in the Container Registry command to list image digests
Field Type Description
Created Integer (64 bit) Displays when the image was created, expressed in number of seconds in UNIX time.
Digest String Displays the unique identifier for an image.
ManifestType String Displays the image manifest type.
Repository String Displays the repository of the image.
SecurityStatus Object Displays the vulnerability status for the image. You can filter and format the following values:

  • Status string
  • IssueCount int
  • ExemptionCount int

The possible statuses are described in Reviewing a vulnerability report by using the CLI.

Size Integer (64 bit) Displays the size of the image in bytes.
Tags Array of strings Displays the tags for the image.

Go template options for ibmcloud cr image-list

Review the following table to find available Go template options and data types for the ibmcloud cr image-list command.

Table 2. Available fields and data types in the Container Registry command to list images
Field Type Description
Created Integer (64 bit) Displays when the image was created, expressed in number of seconds in UNIX time.
Digest String Displays the unique identifier for an image.
ManifestType String Displays the image manifest type.
Namespace String Displays the namespace where the image is stored.
Repository String Displays the repository of the image.
SecurityStatus Object Displays the vulnerability status for the image. You can filter and format the following values:

  • Status string
  • IssueCount int
  • ExemptionCount int

The possible statuses are described in Reviewing a vulnerability report by using the CLI.

Size Integer (64 bit) Displays the size of the image in bytes.
Tag String Displays the tag for the image.

Go template options for ibmcloud cr image-inspect

Review the following table to find available Go template options and data types for the ibmcloud cr image-inspect command.

Table 3. Available fields and data types in the Container Registry command to inspect images
Field Type Description
Architecture String Displays the processor architecture that was used to build this image, and that is required to run the image.
Author String Displays the author of the image.
Comment String Displays the description of the image.
Config Object Displays configuration metadata for the image. For more information, see Config field details.
Container String Displays the ID of the container that created the image.
ContainerConfig Object Displays the default configuration for containers that are started from this image. For more information, see Config field details.
Created String Displays the UNIX timestamp when the image was created.
DockerVersion String Displays the Docker version that was used to build this image.
ID String Displays the unique identifier for an image.
Os String Displays the operating system family that was used to build this image, and that is required to run the image.
OsVersion String Displays the version of the operating system that was used to build this image.
Parent String Displays the ID of the parent image that was used to build this image.
RootFS Object Displays metadata that describes the root file system for the image. For more information, see RootFS field details.
Size Integer (64 bit) Displays the size of the image in bytes.
VirtualSize Integer (64 bit) Displays the sum of the size of each layer in the image in bytes.

Config field details

Table 4. Available fields and data types in Config
Field Type Description
ArgsEscaped Boolean Windows Displays true if the command is already escaped (Windows® specific).
AttachStderr Boolean Displays true if the standard error stream is attached to the container and false if not.
AttachStdin Boolean Displays true if the standard input stream is attached to the container and false if not.
AttachStdout Boolean Displays true if the standard output stream is attached to the container and false if not.
Cmd Array of strings Describes the commands and arguments that are passed to a container to run when the container is started.
Domainname String Displays the fully qualified domain name of the container.
Entrypoint Array of strings Describes the command that is run when the container starts.
Env Array of strings Displays the list of environment variables in the form of key-value pairs.
ExposedPorts Key-value map Displays the list of exposed ports in the format [123:,456:].
Healthcheck Object Describes how to check that the container is working correctly. For more information, see Healthcheck field details.
Hostname String Displays the hostname of the container.
Image String Displays the name of the image that was passed by the operator.
Labels Key-value map Displays the list of labels that were added to the image as key-value pairs.
MacAddress String Displays the MAC address that is assigned to the container.
NetworkDisabled Boolean Displays true if the networking is disabled for the container and false if the networking is enabled for the container.
OnBuild Array of strings Displays the ONBUILD metadata that was defined on the image Dockerfile.
OpenStdin Boolean Displays true if the standard input stream is opened and false if the standard input stream is closed.
Shell Array of strings Displays the shell-form of RUN, CMD, ENTRYPOINT.
StdinOnce Boolean Displays true if the standard input stream is closed after the attached client disconnects and false if the standard input stream stays open.
StopSignal String Describes the UNIX® stop signal to send when to stop the container.
StopTimeout Integer Displays the timeout in seconds to stop a container.
Tty Boolean Displays true if a pseudo-tty is allocated to the container and false if not.
User String Displays the user that runs commands inside the container where the image is used.
Volumes Key-Value map Displays the list of volume mounts that are mounted to a container.
WorkingDir String Displays the working directory inside the container where specified commands are run.

Healthcheck field details

Table 5. Available fields and data types in Healthcheck
Field Type Description
Interval Integer (64 bit) Displays the time to wait between two health checks in nanoseconds.
Retries Integer Displays the number of consecutive failures that are needed to consider a container as not working correctly.
Test Array of strings

Displays how to run the health check test. The following options are available.

  • {} inherit the health check.
  • {"NONE"} the health check is disabled.
  • {"CMD", args...} exec arguments directly.
  • {"CMD-SHELL", command} run the command with the system's default shell.
Timeout Integer (64 bit) Displays the time to wait, in nanoseconds, before the health check fails.

RootFS field details

Table 6. Available fields and data types in RootFS
Option Type Description
BaseLayer String Displays the descriptor for the base layer in the image.
Layers Array of strings Displays the descriptors of each image layer.
Type String Displays the type of file system.