Installing and configuring 19
The command reference carries no version number of its own; the NGC catalog listed 4.36.6 as the newest NGC CLI release on the day these rows were checked.
| Command | What it does |
|---|---|
ngc config set | Save the CLI configurationPrompts for the API key, the output format and the default org, then writes them to the settings file. |
ngc config set --format_type json | Save JSON as default formatA global argument given together with config set is stored, so later commands print JSON without the flag. |
ngc config set --org ORG-NAME --team TEAM-NAME | Switch default org and teamNeeded before working with resources or registry spaces of another organization or team you belong to. |
ngc config current | Show the active configurationUse it to confirm which org and team your commands currently act on. |
ngc config current --show-auth-token | Show the Docker login tokenAdds the password used for Docker login to the output; --yes skips the confirmation. |
ngc config clear | Clear the saved configurationDeletes what ngc config set stored for your user. |
ngc config clear-cache | Clear cached values |
ngc --version | Show the CLI versionPrints NGC CLI and the version number; NVIDIA uses it to verify a fresh installation. |
ngc version list | List CLI releasesShows the newest releases so you can compare them with the installed one. |
ngc version upgrade | Upgrade the CLIMoves the installed CLI to the newest release; NVIDIA advises always running the latest version. |
ngc -h | Show top-level helpLists the global options and the top-level command groups. |
ngc config -h | Show help for one commandWorks after any command or sub-command and prints its required and optional arguments. |
chmod u+x ngc-cli/ngc | Make the Linux binary executablePart of the Linux zip install, done together with adding the ngc-cli directory to PATH. |
NGC_CLI_API_KEY | API key variableSupplies the NGC access key from the environment instead of the configuration file. |
NGC_CLI_ORG | Organization variableOverrides the org from the configuration file; a global --org argument still wins. |
NGC_CLI_TEAM | Team variable |
NGC_CLI_FORMAT_TYPE | Output format variableTakes JSON, CSV or ASCII, like the --format_type argument. |
NGC_CLI_HOME | Configuration home directoryConfiguration files live in a .ngc subdirectory of this path; without it they are in ~/.ngc. |
NGC_CLI_TRACE_DISABLE | Tracing off switchSet it when tracing causes errors with a proxy or other settings. |
Container images 21
Registry targets are written org/[team/]name[:tag]. The wildcards * and ? are accepted when listing, and a pattern ending in :* lists every tag of an image.
| Command | What it does |
|---|---|
ngc registry image list | List container imagesShows the image repositories your account can reach. |
ngc registry image list '*nginx*' | Search images by nameThe quoted pattern matches every image whose name contains nginx. |
ngc registry image list --column name --column tag | Choose list columnsRepeat --column for every column wanted; writing column=header renames the heading. |
ngc registry image list --signed | List signed images only |
ngc registry image info | Show image detailsTakes a repository or one tagged image as its target. |
ngc registry image info --layers IMAGE | Show image layersNeeds a target that names a tag, not just the repository. |
ngc registry image info --scan IMAGE | Show scan detailsReports the scan of a tagged image; with no tag the most recent one is used. |
ngc registry image pull | Pull an imageDocker must be installed on the client; with no tag the CLI assumes latest. |
ngc registry image pull example_org/tensorrt:19.05 | Pull a tagged imageNGC signs in to the image registry by itself for pulls and pushes. |
ngc registry image pull --scan FILE IMAGE | Download the scan reportSaves the scan report as a CSV file and does not pull the image itself. |
ngc registry image push | Push an imageUploads a local Docker image; with no tag the CLI assumes latest. |
ngc registry image push example_org/my-image:latest | Push a tagged imageWhen the local image lacks the nvcr.io name, the CLI offers to tag it before pushing. |
ngc registry image create | Create an image repositoryMakes the top-level metadata record; description, overview, logo and labels can be given at once. |
ngc registry image update --desc "A test container image with useful tools." nvidia/testcontainer | Update the image descriptionOther metadata such as overview, logo, publisher and labels are changed with the same command. |
ngc registry image remove | Remove an image or repositoryAccepts * and ? wildcards in the target; -y answers the confirmation. |
ngc registry image remove example_org/digits:2.0 | Remove one image tagOnly that tag goes; naming the repository without a tag removes all of it. |
ngc registry image scan | Scan an imageThe target is one tagged image, written org/[team/]image:tag. |
ngc registry image set-latest | Set the latest tagMakes the named tag the one that latest points to in its repository. |
ngc registry image sign | Request an NVIDIA signatureAsks NVIDIA to sign the image cryptographically. |
ngc registry image publickey | Get the signing public keyReturns the key images are signed with, for checking signatures locally. |
docker login nvcr.io --username '$oauthtoken' | Log Docker in to nvcr.ioType $oauthtoken exactly as the user name and paste the API key at the password prompt. |
Models 20
| Command | What it does |
|---|---|
ngc registry model list | List modelsLists models, or the versions of a model when the target ends in a version pattern. |
ngc registry model list "example_org/example_team/*" | List a team's modelsMatches every model in the example_team space of that org. |
ngc registry model list "example_org/example_model_name:*" | List versions of a modelThe :* suffix switches the output from models to the versions of one model. |
ngc registry model info | Show model detailsTakes a model or, with :version added, one model version. |
ngc registry model info --files TARGET | List files of a model versionA plain flag, not a pattern; the target must include the version. |
ngc registry model download-version | Download a model versionFetches the latest version when the target names none, into the current directory. |
ngc registry model download-version --dest PATH TARGET | Download to another directory |
ngc registry model download-version --file WILDCARD TARGET | Download selected filesShell-style wildcards pick the files; quote * and ? on POSIX shells. The flag can be repeated. |
ngc registry model download-version --exclude WILDCARD TARGET | Skip files when downloadingLeaves out the files or directories that match the pattern. |
ngc registry model download-version-signature "nvidia/tao/dashcamnet:pruned_onnx_v1.0.5" | Download a model signatureGets the signature file of a signed model version, used to verify the download. |
ngc registry model create | Create a modelApplication, format, framework, precision and a short description are required arguments. |
ngc registry model upload-version | Upload a model versionSends the current directory unless --source names another directory or a single file. |
ngc registry model upload-version nvidia/hp_test:v2 --base-version v1 --source ./src | Upload on top of a base versionVersion v2 starts with every file of v1; files in ./src with the same names replace them. |
ngc registry model upload-version --dry-run TARGET | Preview a model uploadPrints the file paths, their count and the total size, and uploads nothing. |
ngc registry model upload-version --no-commit TARGET | Upload without completingLeaves the version open so that further uploads can follow. |
ngc registry model commit-version | Commit a model versionCompletes a version that was uploaded with --no-commit. |
ngc registry model update example_org/example_model_name --display-name "My Deep Model" | Change the display nameAny model attribute can be updated this way; update -h lists them all. |
ngc registry model remove example_org/example_model_name | Remove a modelAsks you to type the model name again before it deletes anything. |
ngc registry model remove example_org/example_model_name:v1 | Remove a model versionDeletes that version alone, after a yes or no question. |
ngc registry model sign | Request a model signature |
Resources 10
| Command | What it does |
|---|---|
ngc registry resource list | List resourcesCovers resources or, with a version pattern in the target, resource versions. |
ngc registry resource info example_org/example_resource | Show resource details |
ngc registry resource download-version nvidia/gnmt_v2_for_tensorflow:1 | Download a resource version |
ngc registry resource download-version --dest PATH TARGET | Download a resource elsewherePuts the files under the given path instead of the current directory. |
ngc registry resource download-version-signature "nvidia/omniverse/omni_paraview_connector:201.1.0" | Download a resource signature |
ngc registry resource create | Create a resourceApplication, format, framework, precision and short description must be given. |
ngc registry resource upload-version | Upload a resource versionEvery upload to the same resource becomes a separate version of it. |
ngc registry resource update example_org/example_resource:v2 --desc "a new description here" --batch-size 100 | Update a resource versionWith the version left off, the same command edits the metadata of the resource. |
ngc registry resource remove example_org/example_resource | Remove a resourceAsks a yes or no question before deleting. |
ngc registry resource remove example_org/example_resource:v1 | Remove a resource version |
Helm charts 12
| Command | What it does |
|---|---|
ngc registry chart list | List Helm chartsChart name and version both take * and ? wildcards; versions also take bracket expressions such as [a-z]. |
ngc registry chart info | Show chart detailsDescribes a chart or, with :version added, one chart version. |
ngc registry chart info --files TARGET | List files of a chart version |
ngc registry chart pull | Pull a chartDownloads the newest version when the target names none. |
ngc registry chart pull example_org/digits:3.0 --dest output/ | Pull a version into a directoryWithout --dest the chart package is written to the current directory. |
ngc registry chart create example_org/digits --short-desc "A Helm Chart for digits" --overview-filename overview.txt | Create the chart recordHas to exist before the first push; --short-desc is mandatory. |
ngc registry chart push | Push a chartUploads the packaged chart from the current directory unless --source points elsewhere. |
ngc registry chart push example_org/digits:1.0 | Push a chart versionThe target must carry the version, written chart_name:version. |
ngc registry chart push --dry-run TARGET | Preview a chart pushShows the files, their number and the upload size while sending nothing. |
ngc registry chart update nvidian/ngcdocstest --publisher "test account" --display-name "Helm Demo Chart" --built-by "my team" | Update chart metadata |
ngc registry chart remove example_org/digits:2.0 | Remove a chart version |
ngc registry chart remove example_org/digits | Remove a chart entirelyDeletes every version and then the chart repository itself. |
Collections 7
| Command | What it does |
|---|---|
ngc registry collection list | List collectionsOrg, team and name of the target accept the * and ? wildcards. |
ngc registry collection list "example_org/example_team/*" | List a team's collections |
ngc registry collection info | Show collection detailsPrints the metadata of one collection, addressed as org/[team/]name. |
ngc registry collection find | Find collections with an artifactGive the artifact type (MODEL, CHART, RESOURCE or IMAGE) and then its org/[team/]name. |
ngc registry collection create example_org/collectionname --short-desc "Dummy description" --category beginner --add-image orgname/imagename | Create a collectionEverything linked with the --add options must exist already; category and short description are required. |
ngc registry collection update example_org/collectionname --short-desc "New dummy description" --add-chart orgname/chartname --remove-image orgname/imagename | Update a collectionAdds and removes linked artifacts and edits the fields in one call. |
ngc registry collection remove example_org/collectionname | Remove a collection |
Organizations, teams and users 20
| Command | What it does |
|---|---|
ngc org list | List your organizations |
ngc org list-users | List users of the orgAdministrators only; --joined and --invited narrow the list. |
ngc org add-user EMAIL --role ROLE | Invite a user to the orgAdministrators only; repeat --role to grant several roles such as REGISTRY_USER. |
ngc org update-user --add-role ADD_ROLE ID | Give a user another roleKeeps the roles the user already has; --remove-role takes one away. |
ngc org update-user --role ROLE ID | Replace all roles of a userEvery role not named in the command is removed from the user. |
ngc org remove-user ID | Remove an org user |
ngc org add-team cosmos "Cosmos team" | Create a teamTakes the team name and then a description; administrators only. |
ngc org update-team cosmos "Updated description" | Change a team description |
ngc org remove-team TEAM-NAME | Remove a teamNVIDIA lists it as the last step, after the users have been removed from the team. |
ngc team list | List your teams |
ngc team list-users --team cosmos | List users of a teamWithout --team the list is for the team set in the configuration. |
ngc team add-user [email protected] --team cosmos --role REGISTRY_USER | Add a user to a teamAdds an existing org user or invites a new one; administrators only. |
ngc team remove-user [email protected] --team cosmos | Remove a user from a team |
ngc user who | Show the signed-in userPrints the user the CLI is authorized as, with org and team roles. |
ngc user info ID | Look up a user by ID |
ngc user secret create AWS_SECRET --desc "AWS secret" --pair "USERNAME:XYZ123" --pair "PASSWORD:ABC456" --pair "API_KEY:KEY_123" | Create a secret with several keysEach --pair adds one key:value entry; Base Command jobs read secrets through --secret. |
ngc user secret list | List your secrets |
ngc user secret info SECRET-NAME | Show a secretKey values stay redacted unless you ask for specific keys with --key. |
ngc user secret delete --secret SECRET-NAME | Delete a secretNames the one secret to delete; --key removes single key-value pairs and keeps the secret. |
ngc registry usage info | Show registry storage usage |
Base Command jobs 23
ngc base-command, or ngc bc for short, replaces the older ngc batch commands; NVIDIA marks ngc batch as deprecated and due to be phased out.
| Command | What it does |
|---|---|
ngc base-command -h | Show help for job commandsDescribes every base-command sub-command and option. |
ngc base-command list | List jobsDefault columns are Id, Replicas, Name, Team, Status, Duration and Status Details. |
ngc base-command list --column name --column team --column status | Choose job list columnsThe Id column is always printed and need not be requested. |
ngc base-command list --label "Pytorch" --exclude-label "bad" | Filter jobs by labelLists the jobs that carry the first label and lack the second. |
ngc base-command run -i nvidia/tensorflow:18.10-py3 -in dgx1v.16g.1.norm --ace nv-us-west-2 -n HowTo-workspace --result /result --commandline 'sleep 5h' | Submit a jobNames the image, the instance type, the ACE, the job, the result mount and the command to run. |
--datasetid 8181:/dataset --workspace ws-demo:/ws-demo:RO | Mount a dataset and a workspaceOptions of base-command run, written id:mountpoint; workspaces mount read-write unless :RO is added. |
ngc base-command run -f FILE.JSON | Submit a job from a JSON fileReads the whole job definition from the file instead of command-line flags. |
ngc base-command run -f pytorch.json --instance dgx1v.16g.2.norm | Override a field of the JSONA flag on the command line replaces the matching value in the file. |
ngc base-command run --clone JOB-ID --instance dgx1v.32g.8.norm | Clone a jobCopies the parameters of the original job; extra flags override the copied values. |
ngc base-command run ... --replicas NUM --total-runtime T --preempt RUNONCE | Submit a multi-node jobThe three arguments are required for multi-node runs; replicas counts the nodes, primary included. |
ngc base-command run .. --label LABEL_1 | Label a job at submissionRepeat --label for more labels; names starting with a double underscore are reserved for admins. |
ngc base-command run … --secret WANDB_SECRET | Pass a secret to a jobAdds every key of the named secret to the job as environment variables. |
ngc base-command info JOB-ID | Show job statusReturns the job details printed at launch with the status brought up to date. |
ngc base-command info 1070707:0 | Show one replica of a jobIn multi-node jobs the suffix after the colon picks the replica, counted from 0. |
ngc base-command attach JOB-ID | Attach to the job consoleStreams stdout and stderr of a running job. |
ngc base-command exec JOB_ID | Open a shell in a running jobIn a multi-node job it reaches the first replica unless :replica-id follows the job ID. |
ngc base-command exec --commandline "bash -c 'date; echo test'" JOB_ID | Run a command in a job |
ngc base-command kill JOB-ID | Terminate a jobSeveral jobs can be given at once as comma-separated IDs and ranges. |
ngc base-command get-json 1234567 > ./json/test-json.json | Save a job definition as JSONThe file can be edited and submitted again with run -f. |
ngc base-command preempt JOB_ID | Preempt a jobA job launched with --preempt RESUMABLE can continue where it stopped once resumed. |
ngc base-command resume JOB_ID | Resume a preempted jobThe job status history on the web application shows the preempt and resume steps. |
ngc base-command update .. --clear-label JOB-ID | Clear all labels of a jobThe same command adds, removes, locks and unlocks labels with its other label options. |
ngc ace info ACE --org ORG --format_type json | Show the limits of an ACEThe maxRuntimeSeconds field holds the longest run time the ACE allows. |
Datasets, workspaces and results 23
| Command | What it does |
|---|---|
ngc dataset list | List datasetsShows the datasets available to the configured org and team. |
ngc dataset list --owned | List your own datasets |
ngc dataset upload --source mydata/ --desc "mnist is great" mnist --share my_team1 | Upload and share a datasetCreates, uploads and shares in one step; repeat --share for more teams. |
ngc dataset share --team my_team 5586 | Share a dataset with a teamFor datasets uploaded without --share; the number is the dataset ID. |
ngc dataset share --team no-team 5586 | Share a dataset with the orgThe special team name no-team opens the dataset to the whole organization. |
ngc dataset download DATASETID | Download a datasetWrites to the current folder; the dataset ID is shown on the NGC website. |
ngc dataset download DATASETID --dest DESTPATH | Download a dataset elsewhereThe destination folder has to exist already. |
ngc dataset remove DATASETID | Delete a datasetRemoves the dataset from NGC on its ACE. |
ngc dataset convert NEW-DATASET-NAME --from-result JOB-ID | Turn job results into a datasetRemoves the original files from the /result directory and cannot be undone. |
ngc workspace create --name ws-demo | Create a named workspacePrints the new workspace ID; a workspace can be named only once. |
ngc workspace set -n ws-demo s67Bcb_GQU6g75XOglOn8g -y | Name an existing workspaceFor a workspace created without --name; the long string is its ID. |
ngc workspace list | List workspaces |
ngc workspace info ws-demo | Show workspace detailsAccepts the workspace name or its ID. |
ngc base-command workspace info X7xHfMZISZOfUbKKtGnMng --show-sftp | Show SFTP access to a workspaceAdds port, host name and token for SFTP clients, with a sample sftp command. |
ngc workspace upload --source ngc140 s67Bcb_GQU6g75XOglOn8g | Upload a directory to a workspaceBetter than mounting when many files have to be copied in one go. |
ngc workspace download --dest temp s67Bcb_GQU6g75XOglOn8g | Download a workspaceCopies the whole workspace into the local directory given with --dest. |
ngc workspace download --dir path/within/workspace WORKSPACE-ID --dest DOWNLOAD-PATH | Download part of a workspaceLimits the download to one folder inside the workspace. |
ngc workspace share --team nves -y ws-demo | Share a workspace with a teamA workspace is private to its creator until shared; afterwards all team members have the same rights in it. |
ngc workspace revoke-share --team nves -y ws-demo | Stop sharing a workspace |
ngc workspace remove ws-demo | Remove a workspaceFails for a shared workspace until the share has been revoked. |
ngc result download JOB-ID | Download job resultsIncludes joblog.log; for multi-node jobs it fetches the first replica unless :replica-id is added. |
ngc result remove JOB-ID | Delete job resultsResults count against the storage quota until they are removed. |
ngc user storage | Check your storage quota |
Global options and diagnostics 14
A global argument on the command line beats an environment variable, and an environment variable beats the value in the configuration file.
| Command | What it does |
|---|---|
--format_type json | Print output as JSONAccepted by every command; ascii is the default and json is the form to parse in scripts. |
--format_type csv | Print output as CSVWorks for commands whose output is a table; the others do not offer it. |
--org NAME | Run in another organizationOverrides the org of the configuration for this one command. |
--team NAME | Run in another teamOverrides the configured team for this one command. |
--team no-team | Run without a teamDrops the team from the context so the command acts at org level. |
--debug | Turn on debug outputAvailable on every command, for the current call only. |
ngc user --format_type json who | Place global options anywhereGives the same result as putting the option at the end: global arguments are not positional. |
-y | Answer yes to promptsFeeds a yes to every interactive question of the command. |
--dry-run | Preview without changesSupported by some commands only; -h shows whether a command has it. |
ngc diag all | Run all diagnosticsCombines the client, install, server and user reports; no private credentials are included. |
ngc diag install | Diagnose the installation |
ngc diag client | Diagnose the client machine |
ngc diag server | Diagnose the server connectionReports on the remote NGC systems rather than the local machine. |
ngc diag user | Diagnose the user configuration |
No row on this page matches that filter.
Notes
Setup is a single command: ngc config set stores your API key and default org and team, and everything after that inherits the context. The two flags worth internalizing early are --format_type json, which turns any tabular output into something scriptable, and the org/[team/]name target format with * and ? wildcards - org/image:* lists every tag of an image, and version ranges like [1-5] work on charts.
The registry family does the heavy lifting. ngc registry image pull and push assume the latest tag when none is given; info takes --layers and --history for inspecting what a tag actually contains; and pull with --scan downloads the security scan report as CSV instead of the image itself - a detail that saves a large download when the report is all you need. If you run DGX systems, this CLI pairs naturally with nvidia-smi and dcgmi on the node side.
Questions
How do I set up the NGC CLI?
Run ngc config set and supply your NGC API key, org, and team. The values are stored in the user settings file; ngc config current shows what is in effect, and ngc config clear removes it.
How do I pull a container image with the NGC CLI?
ngc registry image pull org/[team/]image:tag. If no tag is provided, latest is assumed. Use ngc registry image list org/image:* to see every available tag first.
How do I get machine-readable output from ngc commands?
Add --format_type json (or csv for tabular commands) to any command. The default is ascii tables; json is the reliable choice for scripting.
What is the difference between ngc registry image scan and pull --scan?
ngc registry image scan triggers a security scan for the targeted tag, while ngc registry image pull --scan downloads an existing scan report as a CSV file instead of pulling the image.
Sources and checks
- NVIDIA NGC CLI documentation: Getting Started with the NGC CLI First configuration, help, output formats, tracing variable
- NVIDIA NGC CLI documentation: config command reference ngc config commands
- NVIDIA NGC CLI documentation: diag command reference ngc diag commands
- NVIDIA NGC CLI documentation: org command reference ngc org commands
- NVIDIA NGC CLI documentation: registry command reference ngc registry image, model, resource, chart and collection commands
- NVIDIA NGC CLI documentation: team command reference ngc team commands
6 more source pages
- NVIDIA NGC CLI documentation: user command reference ngc user and ngc user secret commands
- NVIDIA NGC CLI documentation: Scripting Tips and Best Practices Global arguments, environment variables, precedence
- NVIDIA NGC Catalog User Guide Installation check, CLI upgrade, Docker login, download examples
- NVIDIA NGC Private Registry User Guide Upload, update and Helm chart examples
- NVIDIA Base Command Platform User Guide 1.26.7 ngc base-command, dataset, workspace and result commands
- NVIDIA NGC catalog: NGC CLI resource (release 4.36.6, setup instructions) Current release number, Linux install commands
Every row on this page was matched to a line in the documentation above on . A binding that could not be found there is not listed.
Found a wrong or missing key? Tell us and it gets checked against the source. How we verify describes the process and its limits.