IBM Cloud Docs
IBM Cloud Container Registry CLI

IBM Cloud Container Registry CLI

You can use the IBM Cloud® Container Registry CLI, which is provided in the container-registry CLI plug-in, to manage your registryA storage and distribution service that contains public or private images that are used to create containers. and its resources for your IBM Cloud account.

Prerequisites

Before you can use the Container Registry CLI, you must complete the following prerequisites.

  1. Install the ibmcloud CLI plug-in, see Getting started with the IBM Cloud CLI.
  2. Install the container-registry CLI plug-in, see Installing the container-registry CLI plug-in.
  3. Log in to IBM Cloud with the ibmcloud login command to generate an access tokenA value used by the consumer to gain access to the protected resources on behalf of the user, instead of using the user's service provider credentials. and authenticate your session so that you can run commands in the CLI.

Notes

To find out more about how to use the Container Registry CLI, see Getting started with IBM Cloud Container Registry.

You're notified on the command line when updates to the ibmcloud CLI and container-registry CLI plug-ins are available. Ensure that you keep your CLIs up to date so that you can use all the available commands and options. If you want to view the current version of your container-registry CLI plug-in, run the ibmcloud plugin list command.

For more information about the IAM platform and service access roles that are required for some Container Registry commands, see Managing IAM access for Container Registry.

Do not put personal information in your container images, namespace names, description fields, or in any image configuration data (for example, image names or image labels).

If Container Registry commands fail with an error that says that they're not registered commands, see Why do cr commands fail saying they’re not registered? for assistance. If the commands fail saying that you're not logged in, see Why can't I log in to Container Registry? for assistance.

ibmcloud cr api

This command returns the details about the registry API endpoint that the commands are run against.

ibmcloud cr api

Prerequisites

None

ibmcloud cr exemption-add

Create an exemption for a security issue. You can create an exemption for a security issue that applies to different scopes. The scope can be the account, namespace, repository, digest, or tag.

You can identify the images in the scope by using either the tag or the digest. You can reference the image by digest <dns>/<namespace>/<repo>@<digest>, which affects the digest and all its tags in the same repository, or by tag <dns>/<namespace>/<repo>:<tag>. Where <dns> is the domain name, <namespace> is the namespace, <repo> is the repository, <digest> is the digest, and <tag> is the tag. To list all images, including untagged images, run the ibmcloud cr image-digests command.

ibmcloud cr exemption-add --scope SCOPE --issue-type ISSUE_TYPE --issue-id ISSUE_ID [--output json | -o json]

Prerequisites

To find out more about the required permissions, see Access roles for configuring Container Registry.

Command options

--scope SCOPE

To set your account as the scope, use "*" as the value.

To set a namespace, repository, digest, or tag as the scope, enter the value in one of the following formats:

  • namespace
  • namespace/repository
  • namespace/repository:tag
  • namespace/repository@digest
--issue-type ISSUE_TYPE

The type of security issue that you want to exempt. To find valid issue types, run ibmcloud cr exemption-types.

--issue-id ISSUE_ID

The ID of the security issue that you want to exempt. To find an issue ID, run ibmcloud cr va <image>, where <image> is the name of your image, and use the relevant value from either the Vulnerability ID or Configuration Issue ID column.

--output json, -o json

(Optional) Outputs the list in JSON format.

Examples

Create a CVE exemption for CVE with ID CVE-2018-17929 for all images in the us.icr.io/birds/bluebird repository.

ibmcloud cr exemption-add --scope us.icr.io/birds/bluebird --issue-type cve --issue-id CVE-2018-17929

Create an account-wide CVE exemption for CVE with ID CVE-2018-17929.

ibmcloud cr exemption-add --scope "*" --issue-type cve --issue-id CVE-2018-17929

Create a configuration issue exemption for issue application_configuration:nginx.ssl_protocols for a single image with the tag us.icr.io/birds/bluebird:1.

ibmcloud cr exemption-add --scope us.icr.io/birds/bluebird:1 --issue-type configuration --issue-id application_configuration:nginx.ssl_protocols

Create a configuration issue exemption for issue application_configuration:nginx.ssl_protocols for a single image with the digest us.icr.io/birds/bluebird@sha256:101010101010.

ibmcloud cr exemption-add --scope us.icr.io/birds/bluebird@sha256:101010101010 --issue-type configuration --issue-id application_configuration:nginx.ssl_protocols

ibmcloud cr exemption-list (ibmcloud cr exemptions)

List your exemptions for security issues.

You can identify the images in the scope by using either the tag or the digest. You can reference the image by digest <dns>/<namespace>/<repo>@<digest>, which affects the digest and all its tags in the same repository, or by tag <dns>/<namespace>/<repo>:<tag>. Where <dns> is the domain name, <namespace> is the namespace, <repo> is the repository, <digest> is the digest, and <tag> is the tag. To list all images, including untagged images, run the ibmcloud cr image-digests command.

ibmcloud cr exemption-list [--scope SCOPE] [--output json | -o json]

Prerequisites

To find out more about the required permissions, see Access roles for configuring Container Registry.

Command options

--scope SCOPE

(Optional) List only the exemptions that apply to this scope.

To set a namespace, repository, digest, or tag as the scope, enter the value in one of the following formats:

  • namespace
  • namespace/repository
  • namespace/repository:tag
  • namespace/repository@digest
--output json, -o json

(Optional) Outputs the list in JSON format.

Examples

List all your exemptions for security issues that apply to images in the birds/bluebird repository. The output includes exemptions that are account-wide, exemptions that are scoped to the birds namespace, and exemptions that are scoped to the birds/bluebird repository. The output doesn't include any exemptions that are scoped to specific tags within the birds/bluebird repository.

ibmcloud cr exemption-list --scope birds/bluebird

List all your exemptions for security issues that apply to images in the birds/bluebird@sha256:101010101010 digest. The output includes exemptions that are account-wide, exemptions that are scoped to the birds namespace, and exemptions that are scoped to the birds/bluebird repository and to the birds/bluebird@sha256:101010101010 digest. The output doesn't include any exemptions that are scoped to specific tags within the birds/bluebird repository.

ibmcloud cr exemption-list --scope birds/bluebird@sha256:101010101010

ibmcloud cr exemption-rm

Delete an exemption for a security issue. To view your existing exemptions, run ibmcloud cr exemption-list.

You can identify the images in the scope by using either the tag or the digest. You can reference the image by digest <dns>/<namespace>/<repo>@<digest>, which affects the digest and all its tags in the same repository, or by tag <dns>/<namespace>/<repo>:<tag>. Where <dns> is the domain name, <namespace> is the namespace, <repo> is the repository, <digest> is the digest, and <tag> is the tag. To list all images, including untagged images, run the ibmcloud cr image-digests command.

ibmcloud cr exemption-rm --scope SCOPE --issue-type ISSUE_TYPE --issue-id ISSUE_ID

Prerequisites

To find out more about the required permissions, see Access roles for configuring Container Registry.

Command options

--scope SCOPE

To set your account as the scope, use "*" as the value.

To set a namespace, repository, digest, or tag as the scope, enter the value in one of the following formats:

  • namespace
  • namespace/repository
  • namespace/repository:tag
  • namespace/repository@digest
--issue-type ISSUE_TYPE

The type of issue for the exemption for the security issue that you want to remove. To find the types of issue for your exemptions, run ibmcloud cr exemption-list.

--issue-id ISSUE_ID

The ID of the exemption for the security issue that you want to remove. To find the issue IDs for your exemptions, run ibmcloud cr exemption-list.

Examples

Delete a CVE exemption for CVE with ID CVE-2018-17929 for all images in the us.icr.io/birds/bluebird repository.

ibmcloud cr exemption-rm --scope us.icr.io/birds/bluebird --issue-type cve --issue-id CVE-2018-17929

Delete an account-wide CVE exemption for CVE with ID CVE-2018-17929.

ibmcloud cr exemption-rm --scope "*" --issue-type cve --issue-id CVE-2018-17929

Delete a configuration issue exemption for issue application_configuration:nginx.ssl_protocols for a single image with the tag us.icr.io/birds/bluebird:1.

ibmcloud cr exemption-rm --scope us.icr.io/birds/bluebird:1 --issue-type configuration --issue-id application_configuration:nginx.ssl_protocols

Delete a configuration issue exemption for issue application_configuration:nginx.ssl_protocols for a single image with the digest us.icr.io/birds/bluebird@sha256:101010101010.

ibmcloud cr exemption-rm --scope us.icr.io/birds/bluebird@sha256:101010101010 --issue-type configuration --issue-id application_configuration:nginx.ssl_protocols

ibmcloud cr exemption-types

Lists the types of security issues that you can exempt.

ibmcloud cr exemption-types [--output json | -o json]

Prerequisites

To find out more about the required permissions, see Access roles for configuring Container Registry.

Command options

--output json, -o json
(Optional) Outputs the list in JSON format.

ibmcloud cr iam-policies-enable

From 5 July 2022, all accounts require Cloud Identity and Access Management (IAM) access policies. If you started to use IBM Cloud Container Registry before the availability of IAM API key policies in Container Registry in February 2019, you must ensure that you are using IAM access policies to manage access to the Container Registry service. For more information, see IAM access policies are required from 5 July 2022.

If you're using IAM authentication, this command enables fine-grained authorization. For more information, see Managing IAM access for Container Registry and Defining IAM access policies.

ibmcloud cr iam-policies-enable

Prerequisites

To find out more about the required permissions, see Access roles for configuring Container Registry.

ibmcloud cr iam-policies-status

This command displays the IAM access policy status of the targeted IBM Cloud Container Registry account. For more information, see Managing IAM access for Container Registry and Defining IAM access policies.

From 5 July 2022, all accounts require IBM Cloud® Identity and Access Management (IAM) access policies. If you started to use IBM Cloud Container Registry before the availability of IAM API key policies in Container Registry in February 2019, you must ensure that you are using IAM access policies to manage access to the Container Registry service. For more information, see IAM access policies are required from 5 July 2022.

ibmcloud cr iam-policies-status

ibmcloud cr image-digests (ibmcloud cr digests)

Lists all images, including untagged images, in your IBM Cloud account. This command returns the digest in its long format. When you're using the digest to identify an image, always use the long format.

If you want to list tagged images only, run the ibmcloud cr image-list command.

You can refer to an image by using a combination of the Repository column (repository) and the Digest column (digest) separated by an at (@) symbol to create the image name in the format repository@digest. You can also refer to the image name by using a combination of the content of the Repository column (repository) and one of the tags in the Tags column (tag) separated by a colon (:) to create the image name in the format repository:tag.

Vulnerability Advisor version 3 is discontinued from 13 November 2023. For more information about how to update to version 4, see Vulnerability Advisor version 3 is being discontinued on 13 November 2023.

From 24 July 2023, the --json option is deprecated and is replaced by the --output json option.

ibmcloud cr image-digests [--format FORMAT | --quiet | -q | --output json | -o json] [--restrict RESTRICTION] [--include-ibm] [--no-va] [--va]

Prerequisites

To find out more about the required permissions, see Access roles for using Container Registry.

Command options

--format FORMAT
(Optional) Format the output elements by using a Go template. For more information, see Formatting and filtering the Container Registry CLI output.
--quiet, -q
(Optional) Each image is listed in the format: repository@digest
--output json, -o json
(Optional) Outputs the list in JSON format.
--restrict RESTRICTION
(Optional) Limit the output to display only images in the specified namespace or repository.
--include-ibm
(Optional) Includes IBM-provided public images in the output. By default only private images are listed. You can view IBM-provided images in the global registry only.
--no-va
(Optional) Excludes the Vulnerability Advisor security status results from the output. If you don't need the security status results as part of your ibmcloud cr image-digests output, you can use this option to increase performance.
--va
(Optional) Includes the Vulnerability Advisor security status results in the output. Use this option to ensure that you are ready for IBM Cloud Container Registry CLI plug-in version 1.0.0. You can use the --va option with the --restrict option to receive just the information that you require.

Example

Display all the images in the birds namespace, including untagged images, in the format repository@digest.

ibmcloud cr image-digests --restrict birds --quiet

ibmcloud cr image-inspect

Displays details about a specific image. You can reference the image that you want to inspect either by digest repository@digest, or by tag repository:tag.

ibmcloud cr image-inspect [--format FORMAT] IMAGE [IMAGE...]

Prerequisites

To find out more about the required permissions, see Access roles for using Container Registry.

Command options

--format FORMAT

(Optional) Format the output elements by using a Go template. For more information, see Formatting and filtering the Container Registry CLI output.

IMAGE

The name of the image for which you want to get a report. You can inspect multiple images by listing each image in the command with a space between each name.

You can identify images by using either the digest <dns>/<namespace>/<repo>@<digest> or by tag <dns>/<namespace>/<repo>:<tag>. Where <dns> is the domain name, <namespace> is the namespace, <repo> is the repository, <digest> is the digest, and <tag> is the tag.

To find the names of your images, run one of the following commands:

  • To identify your image by digest, run the ibmcloud cr image-digests command. Combine the content of the Repository column (repository) and the Digest column (digest) separated by an at (@) symbol to create the image name in the format repository@digest.
  • To identify your image by tag, run the ibmcloud cr image-list command. Combine the content of the Repository column (repository) and Tag column (tag) separated by a colon (:) to create the image name in the format repository:tag. If a tag is not specified in the image name, the image that is tagged latest is deleted by default.

Example

Display details about the exposed ports for the image us.icr.io/birds/bluebird:1 by using the following formatting directive.

ibmcloud cr image-inspect  --format "{{ .Config.ExposedPorts }}" us.icr.io/birds/bluebird:1

ibmcloud cr image-list (ibmcloud cr images)

Displays all tagged images in your IBM Cloud account. If you want to list all your images, including untagged images, run the ibmcloud cr image-digests command. By default, the ibmcloud cr image-list command returns the digest for the images in a truncated format. The ibmcloud cr image-digests command returns the long format of the digest.

When you're using the digest to identify an image, always use the long format.

The image name is the combination of the content of the Repository and Tag columns in the format: repository:tag

Vulnerability Advisor version 3 is discontinued from 13 November 2023. For more information about how to update to version 4, see Vulnerability Advisor version 3 is being discontinued on 13 November 2023.

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

ibmcloud cr image-list [--format FORMAT] [--quiet | -q ] [--restrict RESTRICTION] [--include-ibm] [--no-trunc] [--show-type] [--no-va] [--va] [--output json | -o json]

Prerequisites

To find out more about the required permissions, see Access roles for using Container Registry.

Command options

--format FORMAT
(Optional) Format the output elements by using a Go template. For more information, see Formatting and filtering the Container Registry CLI output.
--quiet, -q
(Optional) Each image is listed in the format: repository:tag
--restrict RESTRICTION
(Optional) Limit the output to display only images in the specified namespace or repository.
--include-ibm
(Optional) Includes IBM-provided public images in the output. By default only private images are listed. You can view IBM-provided images in the global registry only.
--no-trunc
(Optional) Returns the image digest in its long format.
--show-type
(Optional) Displays the image manifest type.
--no-va
(Optional) Excludes the Vulnerability Advisor security status results from the output. If you don't need the security status results as part of your ibmcloud cr image-list output, you can use this option to increase performance.
--va
(Optional) Includes the Vulnerability Advisor security status results in the output. Use this option to ensure that you are ready for IBM Cloud Container Registry CLI plug-in version 1.0.0. You can use the --va option with the --restrict option to receive just the information that you require.
--output json, -o json
(Optional) Outputs the list in JSON format.

Example

Display the images in the birds namespace in the format repository:tag, without truncating the image digests.

ibmcloud cr image-list --restrict birds --quiet --no-trunc

ibmcloud cr image-prune-untagged

Delete all untagged images in your IBM Cloud Container Registry account.

From 24 July 2023, the --json option is deprecated and is replaced by the --output json option.

ibmcloud cr image-prune-untagged [--force | -f [--output json | -o json]] --restrict RESTRICTION

Prerequisites

To find out more about the required permissions, see Access roles for using Container Registry.

Command options

--force, -f
(Optional) Force the command to run with no user prompts.
--output json, -o json
(Optional) Outputs JSON that contains the results of cleaning up your untagged images. This option must be used with --force.
--restrict
(Optional) Limit the clean up to only untagged images in the specified namespace or repository.

Example

Delete all untagged images that are in the birds namespace and output the results in JSON format.

ibmcloud cr image-prune-untagged [--force | -f [--json]] --restrict birds

ibmcloud cr image-restore

Restore a deleted image from the trash. You can choose to restore by tag or by digest. If you restore by digest, the digest and all its tags in the same repository are restored. To find out what is in the trash, run the ibmcloud cr trash-list command.

If you get an error when you're restoring an image that says that the tagged image exists, see Why do I get an error when I'm restoring an image? for assistance.

If you're restoring an image by digest, but some tags aren't restored, see Why aren't all the tags restored when I restore by digest? for assistance.

ibmcloud cr image-restore IMAGE

Prerequisites

To find out more about the required permissions, see Access roles for using Container Registry.

Command options

IMAGE

The name of the image that you want to restore from the trash.

To find the names of your images in the trash, run the ibmcloud cr trash-list command.

You can identify images by using either the tag or the digest. The image to restore can be referenced by digest <dns>/<namespace>/<repo>@<digest>, which restores the digest and all its tags in the same repository, or by tag <dns>/<namespace>/<repo>:<tag>. Where <dns> is the domain name, <namespace> is the namespace, <repo> is the repository, <digest> is the digest, and <tag> is the tag.

Images are stored in the trash for 30 days.

Example

To restore the image us.icr.io/birds/bluebird:1, run the following command.

ibmcloud cr image-restore us.icr.io/birds/bluebird:1

For more information about how to use the ibmcloud cr image-restore command, see Restoring images.

ibmcloud cr image-rm

Delete one or more specified images from Container Registry. You can reference the image that you want to delete either by digest repository@digest, or by tag repository:tag.

Where multiple tags exist for the same image digest within a repository, the ibmcloud cr image-rm command removes the underlying image and all its tags. If the same image exists in a different repository or namespace, then that copy of the image is not removed. If you want to remove a tag from an image and leave the underlying image and any other tags in place, use the ibmcloud cr image-untag command.

If you want to restore a deleted image, you can list the contents of the trash by running the ibmcloud cr trash-list command and restore a selected image by running the ibmcloud cr image-restore command.

ibmcloud cr image-rm IMAGE [IMAGE...]

Prerequisites

To find out more about the required permissions, see Access roles for using Container Registry.

Command options

IMAGE

The name of the image that you want to delete. You can delete multiple images at the same time by listing each image in the command with a space between each name. You can identify images by using either the digest <dns>/<namespace>/<repo>@<digest> or by tag <dns>/<namespace>/<repo>:<tag>. Where <dns> is the domain name, <namespace> is the namespace, <repo> is the repository, <digest> is the digest, and <tag> is the tag.

Images are stored in the trash for 30 days.

To find the names of your images, run one of the following commands:

  • To identify your image by digest, run the ibmcloud cr image-digests command. Combine the content of the Repository column (repository) and the Digest column (digest) separated by an at (@) symbol to create the image name in the format repository@digest.
  • To identify your image by tag, run the ibmcloud cr image-list command. Combine the content of the Repository column (repository) and Tag column (tag) separated by a colon (:) to create the image name in the format repository:tag. If a tag is not specified in the image name, the image that is tagged latest is deleted by default.

Example

Delete the image us.icr.io/birds/bluebird:1.

ibmcloud cr image-rm us.icr.io/birds/bluebird:1

ibmcloud cr image-tag

Add a tag that you specify in the command to an existing image, copy the tag to another repository, or copy the tag to a repository in a different namespace. When you copy a tag, any Red Hat® signatures for its digest are also copied. The target image TARGET_IMAGE is the new image and the source image SOURCE_IMAGE is the existing image in IBM Cloud Container Registry. The source and target images must be in the same region. You can reference the source image that you want to tag by either digest repository@digest, or by tag repository:tag. You must reference the target image by tag.

You can identify source images by using either the digest <dns>/<namespace>/<repo>@<digest> or by tag <dns>/<namespace>/<repo>:<tag>. You must reference the target image by tag <dns>/<namespace>/<repo>:<tag>. Where <dns> is the domain name, <namespace> is the namespace, <repo> is the repository, <digest> is the digest, and <tag> is the tag.

To find the names of your images, use one of the following alternatives:

  • To identify your image by digest, run the ibmcloud cr image-digests command. Combine the content of the Repository column (repository) and the Digest column (digest) separated by an at (@) symbol to create the image name in the format repository@digest.
  • To identify your image by tag, run the ibmcloud cr image-list command. Combine the content of the Repository column (repository) and Tag column (tag) separated by a colon (:) to create the image name in the format repository:tag.

If you get a manifest error when you try to tag your image, the following topics might be of assistance:

ibmcloud cr image-tag [SOURCE_IMAGE] [TARGET_IMAGE]

Prerequisites

To find out more about the required permissions, see Access roles for using Container Registry.

Command options

SOURCE_IMAGE
The name of the source image. You can identify source images by using either the digest <dns>/<namespace>/<repo>@<digest> or by tag <dns>/<namespace>/<repo>:<tag>. Where <dns> is the domain name, <namespace> is the namespace, <repo> is the repository, <digest> is the digest, and <tag> is the tag.
TARGET_IMAGE
The name of the target image. TARGET_IMAGE must be in the format repository:tag, for example, us.icr.io/namespace/image:latest.

Examples

Add another tag reference latest, to the image us.icr.io/birds/bluebird:1.

ibmcloud cr image-tag  us.icr.io/birds/bluebird:1 us.icr.io/birds/bluebird:latest

Copy the image us.icr.io/birds/bluebird:peck to another repository in the same namespace birds/pigeon.

ibmcloud cr image-tag us.icr.io/birds/bluebird:peck us.icr.io/birds/pigeon:peck

Copy the image us.icr.io/birds/bluebird:peck to another namespace animals to which you have access.

ibmcloud cr image-tag us.icr.io/birds/bluebird:peck us.icr.io/animals/dog:bark

ibmcloud cr image-untag

Remove a tag, or tags, from each specified image in IBM Cloud Container Registry.

To remove a specific tag from an image and leave the underlying image and any other tags in place, use the ibmcloud cr image-untag command. If you want to delete the underlying image, and all its tags, use the ibmcloud cr image-rm command instead.

ibmcloud cr image-untag IMAGE [IMAGE...]

Prerequisites

To find out more about the required permissions, see Access roles for using Container Registry.

Command options

IMAGE

The name of the image for which you want to remove the tag. You can delete the tag from multiple images at the same time by listing each image in the command with a space between each name. IMAGE must be in the format repository:tag, for example, us.icr.io/namespace/image:latest.

To find the names of your images, run ibmcloud cr image-list. Combine the content of the Repository column (repository) and Tag column (tag) separated by a colon (:) to create the image name in the format repository:tag. If a tag is not specified in the image name, the command fails.

Example

Remove the tag 1 from the image us.icr.io/birds/bluebird:1.

ibmcloud cr image-untag us.icr.io/birds/bluebird:1

ibmcloud cr info

Displays the name and the account of the registry that you are logged in to.

ibmcloud cr info

Prerequisites

None

ibmcloud cr login

Log the local Docker or Podman client in to IBM Cloud Container Registry.

This command is required if you want to run the push or pull commands for the registry. If you want to run other ibmcloud cr commands, you're not required to log in to Container Registry.

ibmcloud cr login [--client CLIENT]

Container Registry supports other clients as well as Docker and Podman. To log in by using other clients, see Accessing your namespaces interactively.

If you have a problem when you try to log in, see Why can't I log in to Container Registry? for assistance. macOS If you're using a Mac and you have a problem when you try to log in, see Why is Docker login on my Mac failing? for assistance.

Logging in to Container Registry by using the ibmcloud cr login command is subject to IAM login session limits. If your login expires, see Why does the Container Registry login keep expiring? for assistance.

Prerequisites

None

Command options

CLIENT
(Optional) Select the client that you want to log in. Valid values are docker and podman. If this option is not used and Docker is installed, the default is docker; if Docker is not installed, the default is podman.

Example

To log in to the registry with Podman, run the following command.

ibmcloud cr login --client podman

ibmcloud cr manifest-inspect

View the contents of the manifest for an image. You can reference the image that you want to inspect either by digest repository@digest, or by tag repository:tag.

ibmcloud cr manifest-inspect [--quiet | -q ] IMAGE

Prerequisites

To find out more about the required permissions, see Access roles for using Container Registry.

Command options

IMAGE

The name of the image for which you want to inspect the manifest. You can identify images by using either the digest <dns>/<namespace>/<repo>@<digest> or by tag <dns>/<namespace>/<repo>:<tag>. Where <dns> is the domain name, <namespace> is the namespace, <repo> is the repository, <digest> is the digest, and <tag> is the tag.

To find the names of your images, run one of the following commands:

  • To identify your image by digest, run the ibmcloud cr image-digests command. Combine the content of the Repository column (repository) and the Digest column (digest) separated by an at (@) symbol to create the image name in the format repository@digest.
  • To identify your image by tag, run the ibmcloud cr image-list command. Combine the content of the Repository column (repository) and Tag column (tag) separated by a colon (:) to create the image name in the format repository:tag.
--quiet, -q

(Optional) Reduces the output to display essential elements only.

Example

To view the contents of the manifest for the image us.icr.io/birds/bluebird:1, run the following command.

ibmcloud cr manifest-inspect us.icr.io/birds/bluebird:1

ibmcloud cr namespace-add

Choose a name for your namespaceA collection of repositories that store images in a registry. A namespace is associated with an IBM Cloud account, which can include multiple namespaces. and add it to your IBM Cloud account.

You can create a namespace in a resource groupThe environment, and constraints, in which contained resource instances adhere to. A user can be associated with a resource group to enable collaboration. of your choice by using one of the following options.

  • Before you create the namespace, run the ibmcloud target -g <resource_group> command, where <resource_group> is the resource group.
  • Specify the required resource group by using the -g option on the ibmcloud cr namespace-add command.

If you create a namespace in a resource group, you can configure access to resources within the namespace at the resource group level. However, you can still set permissions for the namespace at the account level or in the namespace itself. If you don't specify a resource group, and a resource group isn't targeted, the default resource group is used.

If you have an older namespace that is not in a resource group, you can assign it to a resource group, see ibmcloud cr namespace-assign.

Namespaces that are assigned to a resource group show in the Resource list page of the IBM Cloud console.

ibmcloud cr namespace-add [-g (RESOURCE_GROUP_NAME | RESOURCE_GROUP_ID)] NAMESPACE

For more information about resource groups, see Creating a resource group.

If you have a problem when you try to add a namespace, see Why can't I add a namespace? for assistance.

Prerequisites

To find out more about the required permissions, see Platform management roles and Access roles for configuring Container Registry.

Command options

NAMESPACE

The namespace that you want to add. The namespace must be unique across all IBM Cloud accounts in the same region. Namespaces must have 4 - 30 characters, and contain lowercase letters, numbers, hyphens (-), and underscores (_) only. Namespaces must start and end with a letter or number.

Do not put personal information in your namespace names.

-g (RESOURCE_GROUP_NAME | RESOURCE_GROUP_ID)

(Optional) Specify the name or ID of the resource group to which you want to add the namespace. If you don't set this option, the targeted resource group is used. If you don't set this option and a resource group is not targeted, the default resource group for the account is used.

Example

Create a namespace with the name birds and add it to the resource group beaks.

ibmcloud cr namespace-add -g beaks birds

ibmcloud cr namespace-assign

Namespaces created in version 0.1.484 of the Container Registry CLI or earlier, or in the IBM Cloud console before 29 July 2020 are not assigned to resource groups. You can assign an unassigned namespace to a resource group for your IBM Cloud account. If you assign a namespace to a resource group, you can configure access to resources within the namespace at the resource group level. If you don't specify a resource group, and a resource group isn't targeted, the command fails.

You can assign a namespace to a resource group only once. When a namespace is in a resource group, you can't move it to another resource group.

To find out which namespaces are assigned to resource groups and which are unassigned, run the ibmcloud cr namespace-list command with the -v option. Namespaces that are assigned to a resource group also show in the Resource list page of the IBM Cloud console.

ibmcloud cr namespace-assign -g (RESOURCE_GROUP_NAME | RESOURCE_GROUP_ID) NAMESPACE

For more information about resource groups, see Creating a resource group.

Prerequisites

To find out more about the required permissions, see Platform management roles and Access roles for configuring Container Registry.

Command options

-g (RESOURCE_GROUP_NAME | RESOURCE_GROUP_ID)
(Optional) Specify the name or ID of the resource group to which you want to assign the namespace. If you don't set this option, the targeted resource group is used.
NAMESPACE
The namespace that you want to assign to a resource group.

Example

Assign a namespace with the name birds to the resource group beaks.

ibmcloud cr namespace-assign -g beaks birds

ibmcloud cr namespace-list (ibmcloud cr namespaces)

Displays all namespaces that are owned by your IBM Cloud account. You can use this command to list your namespaces so that you can verify which namespaces are assigned to resource groups, and which namespaces are unassigned. Namespaces that are assigned to a resource group also show in the Resource list page of the IBM Cloud console.

ibmcloud cr namespace-list [--verbose | -v] [--output json | -o json]

Prerequisites

To find out more about the required permissions, see Access roles for using Container Registry.

Command options

--verbose, -v
(Optional) List all the namespaces and include information about the resource group and the creation date of the namespace.
--output json, -o json
(Optional) Outputs the list in JSON format.

Example

View a list of all your namespaces, including information about resource groups and creation dates.

ibmcloud cr namespace-list  -v

ibmcloud cr namespace-rm

Removes a namespace from your IBM Cloud account. Images in this namespace are deleted when the namespace is removed.

ibmcloud cr namespace-rm NAMESPACE  [--force | -f]

Prerequisites

To find out more about the required permissions, see Access roles for configuring Container Registry.

Command options

NAMESPACE
The namespace that you want to remove.
--force, -f
(Optional) Force the command to run with no user prompts.

Example

Remove the namespace birds.

ibmcloud cr namespace-rm birds

ibmcloud cr plan

Displays your pricing plan for the registry region that you're targeting.

ibmcloud cr plan [--output json | -o json]

Prerequisites

To find out more about the required permissions, see Access roles for configuring Container Registry.

Command options

--output json, -o json
(Optional) Outputs the list in JSON format.

ibmcloud cr plan-upgrade

Upgrades you to the standard plan for the registry region that you're targeting.

ibmcloud cr plan-upgrade [PLAN]

For more information about plans, see Registry plans.

Prerequisites

To find out more about the required permissions, see Access roles for configuring Container Registry.

Command options

PLAN
(Optional) The name of the pricing plan that you want to upgrade to. If PLAN is not specified, the default is standard.

Example

Upgrade to the standard pricing plan.

ibmcloud cr plan-upgrade standard

ibmcloud cr platform-metrics

You can use the command to enable and disable platform metrics. You can also use it to find out whether you have platform metrics set up on your account for the registry region that you're targeting.

If you want to view the platform metrics for IBM Cloud Container Registry, you must opt in by running the ibmcloud cr platform-metrics command.

You must specify one of the command options or the command fails with an error.

ibmcloud cr platform-metrics --enable | --disable | --status

For more information about the platform metrics that you can view in Container Registry, see Monitoring metrics for IBM Cloud Container Registry.

Prerequisites

Command options

--enable
(Optional) Enable the setting for your account.
--disable
(Optional) Disable the setting for your account.
--status
(Optional) Display whether the setting is enabled for your account.

Example

Enable platform metrics for your account.

ibmcloud cr platform-metrics --enable

ibmcloud cr private-only

Prevent image pulls or pushes over public network connections for your account for the registry region that you're targeting. You must specify one of the command options or the command fails with an error.

ibmcloud cr private-only --enable | --disable | --status

Prerequisites

To find out more about the required permissions, see Access roles for configuring Container Registry.

Command options

--enable
(Optional) Prevent image pulls or pushes over public network connections for your account.
--disable
(Optional) Reinstate image pulls or pushes over public network connections for your account.
--status
(Optional) Check whether the use of public connections is prevented for image pushes or pulls in your account.

Example

Prevent image pulls or pushes over public network connections for your account.

ibmcloud cr private-only --enable

ibmcloud cr quota

This command displays your current quotas for traffic and storage, and usage information against those quotas for the registry region that you're targeting.

ibmcloud cr quota [--output json | -o json]

Prerequisites

To find out more about the required permissions, see Access roles for configuring Container Registry.

Command options

--output json, -o json
(Optional) Outputs the list in JSON format.

ibmcloud cr quota-set

Modify the specified quota for the registry region that you're targeting.

ibmcloud cr quota-set [--traffic TRAFFIC] [--storage STORAGE]

Prerequisites

To find out more about the required permissions, see Access roles for configuring Container Registry.

Command options

--traffic TRAFFIC
(Optional) Changes your traffic quota to the specified value in megabytes. The operation fails if you are not authorized to set traffic, or if you set a value that exceeds your current pricing plan.
--storage STORAGE
(Optional) Changes your storage quota to the specified value in megabytes. The operation fails if you are not authorized to set storage quotas, or if you set a value that exceeds your current pricing plan.

Example

Set your quota limit for pull traffic to 7000 megabytes and storage to 600 megabytes.

ibmcloud cr quota-set --traffic 7000 --storage 600

ibmcloud cr region

Displays the targeted region and the registry.

ibmcloud cr region

For more information, see Regions.

Prerequisites

None

ibmcloud cr region-set

Set a target region for the IBM Cloud Container Registry commands. To list the available regions, run the command with no options.

ibmcloud cr region-set [REGION]

Prerequisites

None

Command options

REGION
(Optional) The name of your target region, for example us-south. For more information, see Regions.

Example

Target the US South region.

ibmcloud cr region-set us-south

ibmcloud cr retention-policy-list

List the image retention policies for your account. Image retention policies retain the specified number of images for each repository within a namespace in IBM Cloud Container Registry. All other images in the namespace are deleted. You can also see whether the option to retain all untagged images applies to the policy.

Where an image within a repository is referenced by multiple tags, that image is counted only once. Newest images are retained. Age is determined by when the image was created, not when it was pushed to the registry.

ibmcloud cr retention-policy-list [--output json | -o json]

Prerequisites

To find out more about the required permissions, see Access roles for using Container Registry.

Command options

--output json, -o json
(Optional) Outputs the list in JSON format.

Example

List the retention policies in your account.

ibmcloud cr retention-policy-list

For more information about how to use the ibmcloud cr retention-policy-list command, see Retaining images.

ibmcloud cr retention-policy-set

Set a policy to retain the specified number of images for each repository within a namespace in IBM Cloud Container Registry. All other images in the namespace are deleted. When you set a policy it runs interactively, then it runs daily. You can set only one policy in each namespace.

You can choose whether to exclude all untagged images from the total number of images that you decide to retain.

Where an image, within a repository, is referenced by multiple tags, that image is counted only once. Newest images are retained. Age is determined by when the image was created, not when it was pushed to the registry.

If a retention policy deletes an image that you want to keep, you can restore the image. To identify the image, list the contents of the trash by running the ibmcloud cr trash-list command and restore the selected image by running the ibmcloud cr image-restore command.

If you want to cancel a retention policy, see Update a retention policy to keep all your images.

ibmcloud cr retention-policy-set [--retain-untagged] [--force | -f] --images IMAGECOUNT NAMESPACE

Prerequisites

To find out more about the required permissions, see Access roles for using Container Registry.

Command options

NAMESPACE
The namespace for which you want to create a policy.
--retain-untagged
(Optional) Retain all untagged images when the retention policy is being processed. Only tagged images are analyzed and, if the images don't meet the criteria, they are deleted. If the option isn't specified, all tagged and untagged images are analyzed and, if the images don't meet the criteria, they are deleted.
--force, -f
(Optional) Force the command to run with no user prompts.
--images
Determines how many images to keep within each repository in the specified namespace. The newest images are retained. The age of images is determined by their build date. IMAGECOUNT is the number of images that you want to retain in each repository for the namespace. To return a policy to the default state that keeps all the images set IMAGECOUNT to All.

Examples

Set a policy that retains the newest 20 images within each repository in the namespace birds.

ibmcloud cr retention-policy-set --images 20 birds

Set the policy back to the default state so that you keep all your images in the namespace birds.

ibmcloud cr retention-policy-set --images All birds

For more information about how to use the ibmcloud cr retention-policy-set command, see Retaining images.

ibmcloud cr retention-run

Cleans up a namespace by retaining a specified number of images for each repository within a namespace in IBM Cloud Container Registry. All other images in the namespace are deleted.

You can choose whether to exclude all untagged images from the total number of images that you decide to retain.

Where an image, within a repository, is referenced by multiple tags, that image is counted only once. Newest images are retained. Age is determined by when the image was created, not when it was pushed to the registry.

If you want to restore a deleted image, you can list the contents of the trash by running the ibmcloud cr trash-list command and restore a selected image by running the ibmcloud cr image-restore command.

If an image that you're expecting to see doesn't show in the list that is produced, see Why doesn't the retention command show all the images? for assistance.

From 24 July 2023, the --json option is deprecated and is replaced by the --output json option.

ibmcloud cr retention-run [--force | -f [--output json | -o json]] [--retain-untagged] --images IMAGECOUNT NAMESPACE

Prerequisites

To find out more about the required permissions, see Access roles for using Container Registry.

Command options

NAMESPACE
The namespace that you want to clean up.
--force, -f
(Optional) Force the command to run with no user prompts.
--output json, -o json
(Optional) Outputs JSON that contains the results of cleaning your namespace. This option must be used with --force.
--retain-untagged
(Optional) Retain all untagged images when the retention policy is being processed. Only tagged images are analyzed and, if the images don't meet the criteria, they are deleted. If the option isn't specified, all tagged and untagged images are analyzed and, if the images don't meet the criteria, they are deleted.
--images
Determines how many images to keep within each repository in the specified namespace. The newest images are retained. The age of images is determined by their build date. IMAGECOUNT is the number of images that you want to retain in each repository for the namespace.

Example

Retain the newest 20 images within each repository, in the namespace birds.

ibmcloud cr retention-run --images 20 birds

For more information about how to use the ibmcloud cr retention-run command, see Retaining images.

ibmcloud cr trash-list

Displays all images in the trash in your IBM Cloud account. You can also see the number of days that remain until the image is removed from the trash. The number of days that remain until removal is rounded up. For example, if the time until removal is 2 hours, it shows as 1 day. Images remain in the trash for 30 days after they are deleted from your live repository.

If you want to restore an image from the trash, run the ibmcloud cr image-restore command, see Restoring images.

From 24 July 2023, the --json option is deprecated and is replaced by the --output json option.

ibmcloud cr trash-list [--restrict NAMESPACE] [--output json | -o json]

Prerequisites

To find out more about the required permissions, see Access roles for using Container Registry.

Command options

--restrict NAMESPACE
(Optional) Limit the output to display only images in the specified namespace.
--output json, -o json
(Optional) Outputs JSON that contains the details of the contents of the trash.

Example

Display the images that are in the trash in the birds namespace.

ibmcloud cr trash-list --restrict birds

ibmcloud cr va-version

Find out which version of Vulnerability Advisor you're using. Version 4 is the only valid version.

Vulnerability Advisor version 3 is discontinued from 13 November 2023. For more information about how to update to version 4, see Vulnerability Advisor version 3 is being discontinued on 13 November 2023.

ibmcloud cr va-version

Prerequisites

None.

ibmcloud cr va-version-set

Set the version of Vulnerability Advisor.

Vulnerability Advisor version 3 is discontinued from 13 November 2023. For more information about how to update to version 4, see Vulnerability Advisor version 3 is being discontinued on 13 November 2023.

If you try to set an invalid version of Vulnerability Advisor, you get en error, see Why do I get an error about an invalid version of Vulnerability Advisor being specified? for assistance.

ibmcloud cr va-version-set VERSION

Prerequisites

None.

Command options

VERSION
The version of Vulnerability Advisor that you want to use. The only valid value is v4.

Example

To set the Vulnerability version to version 4, run the following command:

ibmcloud cr va-version-set v4

ibmcloud cr vulnerability-assessment (ibmcloud cr va)

View a vulnerability assessment report for your images.

Vulnerability Advisor version 3 is discontinued from 13 November 2023. For more information about how to update to version 4, see Vulnerability Advisor version 3 is being discontinued on 13 November 2023.

ibmcloud cr vulnerability-assessment [--extended | -e] [--vulnerabilities | -v] [--configuration-issues | -c] [--output FORMAT | -o FORMAT] IMAGE [IMAGE...]

Prerequisites

To find out more about the required permissions, see Access roles for using Container Registry.

Command options

IMAGE

The name of the image for which you want to get a report. The report states whether the image has any known package vulnerabilities. You can request reports for multiple images at the same time by listing each image in the command with a space between each name.

To find the names of your images, run ibmcloud cr image-list. Combine the content of the Repository column (repository) and Tag column (tag) separated by a colon (:) to create the image name in the format repository:tag. If a tag is not specified in the image name, the report assesses the image that is tagged latest.

For more information about supported Docker base images, see Vulnerable packages.

For more information, see Managing image security with Vulnerability Advisor.

--extended, -e

(Optional) The command output shows additional information about fixes for vulnerable packages.

--vulnerabilities, -v

(Optional) The command output is restricted to show vulnerabilities only.

--configuration-issues, -c

(Optional) The command output is restricted to show configuration issues only.

--output FORMAT, -o FORMAT

(Optional) The command output is returned in the chosen format. The default format is text.

The following formats are supported:

  • text
  • json

Examples

View a standard vulnerability assessment report for your image.

ibmcloud cr vulnerability-assessment us.icr.io/birds/bluebird:1

View a vulnerability assessment report for your image us.icr.io/birds/bluebird:1 in JSON format, showing vulnerabilities only.

ibmcloud cr vulnerability-assessment --vulnerabilities  --output json us.icr.io/birds/bluebird:1