NGC Catalog CLI

Documentation for the NGC Catalog CLI that explains how to use the CLI.

Introduction

The NVIDIA® GPU Cloud (NGC) Catalog CLI is a command-line interface for managing content within the NGC Registry. The CLI operates within a shell and lets you use scripts to automate commands.

With NGC Catalog CLI, you can
  • View a list of GPU-accelerated Docker container images, pre-trained deep-learning models, and scripts for creating deep-learning models.
  • Download models and model-scripts.
    Note: Currently, the NGC Catalog CLI doesn't not provide the ability to download container images. To download container images, use the docker pull command from the Docker command line.

This document provides an introduction to using the NGC Catalog CLI. For a complete list of commands and options, use the -h option as explained in Using NGC CLI.

Guest Users and Community Users

The content within the NGC registry is either locked or unlocked. Unlocked content is freely available for download by guest users. To download locked content you must sign up for an NGC community user account.

Guest Users

Guest users can access the NGC website without having to log in. From the website, guest users can download the NGC Catalog CLI and start using it to view content and download unlocked content.

Community Users

To be a community user and download locked NGC content, you must sign up for an NGC account, sign into the NGC website with your account, and then generate an API key. See the NVIDIA GPU Cloud Getting Started Guide for instructions.

Installing NGC Catalog CLI

To install NGC Catalog CLI,

  1. Enter the NGC website (https://ngc.nvidia.com) as a guest user, or log in to your individual NGC account as a community user.
  2. Click SETUP from the side menu, then click Downloads under Install NGC CLI from the Setup page.
  3. From the CLI Install page, click the Windows, Linux, or MacOS tab, according to the platform from which you will be running NGC Catalog CLI.
  4. Follow the instructions to install the CLI.
  5. Verify the installation by entering ngc -v. The output should be “NGC Catalog CLI x.y.z” where x.y.z indicates the version.

Using NGC Catalog CLI

To run an NGC CLI command, enter “ngc” followed by the appropriate options.

To see a description of available options and command descriptions, use the option -h after any command or option.

Example 1: To view a list of all the available options for ngc, enter

C:\>ngc -h

Example 2: To view a description of the registry image command and options, enter

C:\>ngc registry image -h

​Example 3: To view a description of the registry image info command and options, enter

C:\>ngc registry image info -h 

Preparing to Download Locked Content

If you plan to download locked content, be sure you have registered for an NGC account and have generated an API key, then issue the following and enter your API key at the prompt.

ngc config set 
Enter API key [no-apikey]. Choices: [<VALID_APIKEY>, 'no-apikey']: <your-api-key>

Accessing the Container Registry

The ngc registry image commands let you access ready-to-use GPU-accelerated container images from the registry.

Viewing Container Image Information

There are several commands for viewing information about available container images.

To list container images:

C:\>ngc registry image list

Example output

+-----------+----------------+------------+------------+--------------+------------+
| Name      | Repository     | Latest Tag | Image Size | Updated Date | Permission |
+-----------+----------------+------------+------------+--------------+------------+
| caffe     | nvidia/caffe   | 19.05-py2  | 1.81 GB    | May 09, 2019 | unlocked   |
| caffe     | nvidia/caffe2  | 18.08-py3  | 1.3 GB     | Apr 17, 2019 | locked     |
| cntk      | nvidia/cntk    | 18.08-py3  | 2.4 GB     | Aug 03, 2018 | locked     |
 ...|

To view detailed information about a specific image, specify the image and the tag.

Example:

C:\>ngc registry image info nvidia/caffe:19.02-py2
--------------------------------------------------
 Image Information
 Name: nvidia/caffe:19.02-py2
 Architecture: amd64
 Schema Version: 1
--------------------------------------------------

Accessing the Model Registry

The ngc registry model commands let you access ready-to-use deep learning models from the registry.

Viewing Model Information

There are several commands for viewing information about available models.

To see a list of models that are provided by NVIDIA:

C:\>ngc registry model list

Example output

+--------------+--------------+---------+--------------+-----------+-----------+--------------+------------+
| Name         | Repository   | Latest  | Application  | Framework | Precision | Last         | Permission |
|              |              | Version |              |           |           | Modified     |            |
+--------------+--------------+---------+--------------+-----------+-----------+--------------+------------+
| ONNX         | nvidia/trt_  | 1       | Classificati | TensorRT  | FP16      | May 14, 2019 | unlocked   |
| InceptionV1  | onnx_incepti |         | on           |           |           |              |            |
| TensorRT     | onv1_t4_fp16 |         |              |           |           |              |            |
| 5.0.2 T4     |              |         |              |           |           |              |            |
| FP16         |              |         |              |           |           |              |            |
| ONNX         | nvidia/trt_  | 1       | Classificati | TensorRT  | FP32      | May 14, 2019 | unlocked   |
| InceptionV1  | onnx_incepti |         | on           |           |           |              |            |
| TensorRT     | onv1_t4_fp32 |         |              |           |           |              |            |
| 5.0.2 T4     |              |         |              |           |           |              |            |
| FP32         |              |         |              |           |           |              |            |
...

To view all versions of a model, use the wildcard *.

c:\>ngc registry model list nvidia/<model_name>:*

To view detailed information about a model, you can specify

the model

C:\>ngc registry model info nvidia/<model_name>

or the model version.

C:\>ngc registry model info nvidia/<model_name>:<version>

Downloading a Model

To download a model from the registry to your local disk, specify the model name and version.

C:\>ngc registry model download-version nvidia/<model-name:version>

Example: Downloading a model to the current directory.

C:\>ngc registry model download-version nvidia/trt_onnx_vgg16_v100_16g_int8:1

The following is an example showing the output confirming completion of the download:

Downloaded 230.92 MB in 38s, Download speed: 6.07 MB/s
----------------------------------------------------
Transfer id: trt_onnx_vgg16_v100_16g_int8_v1 Download status: Completed.
Downloaded local path: C:\trt_onnx_vgg16_v100_16g_int8_v1
Total files downloaded: 3
Total downloaded size: 230.92 MB
Started at: 2019-03-18 14:09:31.664000
Completed at: 2019-03-18 14:10:09.712000
Duration taken: 38s seconds
----------------------------------------------------

The model is downloaded to a folder that corresponds to the model name in the current directory. You can specify another path using the -d . option.

Example: Downloading a model to a specific directory (/models).

C:\>ngc registry model download-version nvidia/trt_onnx_vgg16_v100_16g_int8:1 -d ./models
Downloaded 230.92 MB in 38s, Download speed: 6.07 MB/s
----------------------------------------------------
Transfer id: trt_onnx_vgg16_v100_16g_int8_v1 Download status: Completed.
Downloaded local path: C:\models\trt_onnx_vgg16_v100_16g_int8_v1
Total files downloaded: 3
Total downloaded size: 230.92 MB
Started at: 2019-03-18 14:09:31.664000
Completed at: 2019-03-18 14:10:09.712000
Duration taken: 38s seconds
----------------------------------------------------

Viewing Model-script Information

There are several commands for viewing information about available model-scripts.

To see a list of model-scripts that are provided by NVIDIA:

C:\>ngc registry model-script list

To view detailed information about a model-script, you can specify

the model-script

C:\>ngc registry model-script info <org>/<model_script_name>

or the model-script version.

C:\>ngc registry model-script info <org>/<model_script_name>:<version>

Downloading a Model-script

To download a model-script from the registry to your local disk, specify the model-script name and version.

C:\>ngc registry model-script download-version nvidia/<model-script-name:version>

Example: Downloading a model to the current directory.

C:\>ngc registry model-script download-version nvidia/gnmt_v2_for_tensorflow:1  

The following is an example showing the output confirming completion of the download:

Downloaded 130.6 KB in 1s, Download speed: 130.6 KB/s
----------------------------------------------------
Transfer id: gnmt_v2_for_tensorflow_v1 Download status: Completed.
Downloaded local path: C:\gnmt_v2_for_tensorflow_v1
Total files downloaded: 35
Total downloaded size: 130.6 KB
Started at: 2019-03-20 11:24:00.168000
Completed at: 2019-03-20 11:24:01.176000
Duration taken: 1s seconds
----------------------------------------------------

The model is downloaded to a folder that corresponds to the model name in the current directory. You can specify another path using the -d . option.

Example: Downloading a mode-script to a specific directory (/model-scripts).

C:\>ngc registry model download-version nvidia/gnmt_v2_for_tensorflow:1 -d ./model-scripts
Downloaded 130.6 KB in 1s, Download speed: 130.6 KB/s
----------------------------------------------------
Transfer id: gnmt_v2_for_tensorflow_v1 Download status: Completed.
Downloaded local path: C:\model-scripts\gnmt_v2_for_tensorflow_v1
Total files downloaded: 35
Total downloaded size: 130.6 KB
Started at: 2019-03-20 11:24:00.168000
Completed at: 2019-03-20 11:24:01.176000
Duration taken: 1s seconds
----------------------------------------------------

Notices

Notice

THE INFORMATION IN THIS GUIDE AND ALL OTHER INFORMATION CONTAINED IN NVIDIA DOCUMENTATION REFERENCED IN THIS GUIDE IS PROVIDED “AS IS.” NVIDIA MAKES NO WARRANTIES, EXPRESSED, IMPLIED, STATUTORY, OR OTHERWISE WITH RESPECT TO THE INFORMATION FOR THE PRODUCT, AND EXPRESSLY DISCLAIMS ALL IMPLIED WARRANTIES OF NONINFRINGEMENT, MERCHANTABILITY, AND FITNESS FOR A PARTICULAR PURPOSE. Notwithstanding any damages that customer might incur for any reason whatsoever, NVIDIA’s aggregate and cumulative liability towards customer for the product described in this guide shall be limited in accordance with the NVIDIA terms and conditions of sale for the product.

THE NVIDIA PRODUCT DESCRIBED IN THIS GUIDE IS NOT FAULT TOLERANT AND IS NOT DESIGNED, MANUFACTURED OR INTENDED FOR USE IN CONNECTION WITH THE DESIGN, CONSTRUCTION, MAINTENANCE, AND/OR OPERATION OF ANY SYSTEM WHERE THE USE OR A FAILURE OF SUCH SYSTEM COULD RESULT IN A SITUATION THAT THREATENS THE SAFETY OF HUMAN LIFE OR SEVERE PHYSICAL HARM OR PROPERTY DAMAGE (INCLUDING, FOR EXAMPLE, USE IN CONNECTION WITH ANY NUCLEAR, AVIONICS, LIFE SUPPORT OR OTHER LIFE CRITICAL APPLICATION). NVIDIA EXPRESSLY DISCLAIMS ANY EXPRESS OR IMPLIED WARRANTY OF FITNESS FOR SUCH HIGH RISK USES. NVIDIA SHALL NOT BE LIABLE TO CUSTOMER OR ANY THIRD PARTY, IN WHOLE OR IN PART, FOR ANY CLAIMS OR DAMAGES ARISING FROM SUCH HIGH RISK USES.

NVIDIA makes no representation or warranty that the product described in this guide will be suitable for any specified use without further testing or modification. Testing of all parameters of each product is not necessarily performed by NVIDIA. It is customer’s sole responsibility to ensure the product is suitable and fit for the application planned by customer and to do the necessary testing for the application in order to avoid a default of the application or the product. Weaknesses in customer’s product designs may affect the quality and reliability of the NVIDIA product and may result in additional or different conditions and/or requirements beyond those contained in this guide. NVIDIA does not accept any liability related to any default, damage, costs or problem which may be based on or attributable to: (i) the use of the NVIDIA product in any manner that is contrary to this guide, or (ii) customer product designs.

Other than the right for customer to use the information in this guide with the product, no other license, either expressed or implied, is hereby granted by NVIDIA under this guide. Reproduction of information in this guide is permissible only if reproduction is approved by NVIDIA in writing, is reproduced without alteration, and is accompanied by all associated conditions, limitations, and notices.

Trademarks

NVIDIA, the NVIDIA logo, and Volta are trademarks and/or registered trademarks of NVIDIA Corporation in the Unites States and other countries.

Docker and the Docker logo are trademarks or registered trademarks of Docker, Inc. in the United States and/or other countries.

Other company and product names may be trademarks of the respective companies with which they are associated.