NGC CATALOG CLI

DU-09434-001 _v04 | November 2019

User Guide

www.nvidia.comNGC Catalog CLI DU-09434-001 _v04 | ii

TABLE OF CONTENTS

Chapter 1.  Introduction.........................................................................................1Chapter 2. Guest Users and Community Users............................................................ 2Chapter 3. Installing NGC Catalog CLI....................................................................... 3Chapter 4. Using NGC Catalog CLI............................................................................ 4Chapter 5. Running the Diagnostics..........................................................................5Chapter 6. Accessing the Container Registry.............................................................. 6

6.1. Viewing Container Image Information.................................................................66.2. Pulling a Container Image...............................................................................7

Chapter 7. Accessing the Model Registry................................................................... 87.1. Viewing Model Information..............................................................................87.2. Downloading a Model.................................................................................... 97.3. Viewing Model-script Information.................................................................... 107.4. Downloading a Model-script........................................................................... 10

www.nvidia.comNGC Catalog CLI DU-09434-001 _v04 | 1

Chapter 1.INTRODUCTION

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

With NGC Catalog CLI, you can

‣ View a list of GPU-accelerated Docker container images, pre-trained deep-learningmodels, and scripts for creating deep-learning models.

‣ Download container images, models, and model-scripts.

If you will be pulling containers from the registry, you will need Docker installedon your local machine. To install Docker on your client machine, follow one of theseinstructions:

‣ For Ubuntu Linux:

https://docs.docker.com/engine/installation/linux/ubuntulinux/‣ For Windows:

https://docs.docker.com/engine/installation/windows/#/docker-for-windows‣ For MacOS X:

https://docs.docker.com/engine/installation/mac/

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

www.nvidia.comNGC Catalog CLI DU-09434-001 _v04 | 2

Chapter 2.GUEST USERS AND COMMUNITY USERS

The content within the NGC registry is either locked or unlocked. Unlocked content isfreely available for download by guest users. To download locked content you must signup 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 anddownload unlocked content.

Community Users

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

www.nvidia.comNGC Catalog CLI DU-09434-001 _v04 | 3

Chapter 3.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 yourindividual NGC account as a community user.

2. Click SETUP from the side menu, then click Downloads under Install NGC CLIfrom the Setup page.

3. From the CLI Install page, click the Windows, Linux, or MacOS tab, according to theplatform 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 theversion.

www.nvidia.comNGC Catalog CLI DU-09434-001 _v04 | 4

Chapter 4.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 -hafter 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

Configuring NGC Catalog CLI for Your Use

While there are options you can use for each command to specify the output type anddebug mode, you can use the ngc config set command to establish these settings upfront.

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

ngc config set Enter API key [no-apikey]. Choices: [<VALID_APIKEY>, 'no-apikey']: <your-api-key>Enter the CLI output format type. Choices: [ascii, csv, json]: <your-output-format-type>

www.nvidia.comNGC Catalog CLI DU-09434-001 _v04 | 5

Chapter 5.RUNNING THE DIAGNOSTICS

You can view the following diagnostic information for the NGC CLI user:

‣ Current time‣ Operating system‣ Disk usage‣ Current directory size‣ Memory usage‣ NGC CLI environment variables set‣ API gateway connectivity‣ API connectivity to the container registry‣ API connectivity to the model registry‣ External IP‣ NGC CLI configuration values‣ User information (ID, name, and email)‣ User org roles‣ User team roles

Syntax

ngc diag [all,client,install,server,user}

whereall

Produces the maximum amount of diagnostic outputclient

Produces diagnostic output only for the client machine.install

Produces diagnostic output only for the local installation.server

Produces diagnostic output only for the remote server.user

Produces diagnostic output only for the user configuration.

www.nvidia.comNGC Catalog CLI DU-09434-001 _v04 | 6

Chapter 6.ACCESSING THE CONTAINER REGISTRY

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

6.1. Viewing Container Image InformationThere 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 Container Registry

www.nvidia.comNGC Catalog CLI DU-09434-001 _v04 | 7

6.2. Pulling a Container ImageWith the NGC Registry CLI you can pull (download) images to your registry space.

To pull an image to your registry space, specify the image and, optionally, the tag.

C:\>ngc registry image pull <image-name>[:<tag>]

If a tag is not specified, then the tag 'latest' will be used.

www.nvidia.comNGC Catalog CLI DU-09434-001 _v04 | 8

Chapter 7.ACCESSING THE MODEL REGISTRY

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

7.1. Viewing Model InformationThere 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 | | | | | | | |...

Accessing the Model Registry

www.nvidia.comNGC Catalog CLI DU-09434-001 _v04 | 9

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>

7.2. Downloading a ModelTo download a model from the registry to your local disk, specify the model name andversion.

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 thedownload:

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_v1Total files downloaded: 3Total downloaded size: 230.92 MBStarted at: 2019-03-18 14:09:31.664000Completed at: 2019-03-18 14:10:09.712000Duration taken: 38s seconds----------------------------------------------------

The model is downloaded to a folder that corresponds to the model name in the currentdirectory. 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_v1Total files downloaded: 3Total downloaded size: 230.92 MBStarted at: 2019-03-18 14:09:31.664000Completed at: 2019-03-18 14:10:09.712000Duration taken: 38s seconds----------------------------------------------------

Accessing the Model Registry

www.nvidia.comNGC Catalog CLI DU-09434-001 _v04 | 10

7.3. Viewing Model-script InformationThere 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>

7.4. Downloading a Model-scriptTo download a model-script from the registry to your local disk, specify the model-scriptname 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 thedownload:

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_v1Total files downloaded: 35Total downloaded size: 130.6 KBStarted at: 2019-03-20 11:24:00.168000Completed at: 2019-03-20 11:24:01.176000Duration taken: 1s seconds----------------------------------------------------

The model is downloaded to a folder that corresponds to the model name in the currentdirectory. 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.

Accessing the Model Registry

www.nvidia.comNGC Catalog CLI DU-09434-001 _v04 | 11

Downloaded local path: C:\model-scripts\gnmt_v2_for_tensorflow_v1Total files downloaded: 35Total downloaded size: 130.6 KBStarted at: 2019-03-20 11:24:00.168000Completed at: 2019-03-20 11:24:01.176000Duration taken: 1s seconds----------------------------------------------------

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.

Copyright

© 2019 NVIDIA Corporation. All rights reserved.www.nvidia.com