AI Workbench Command Line Interface (CLI) Reference#

NVIDIA AI Workbench is a developer toolkit for data science, machine learning, and AI project development. For users who prefer working in a terminal, AI Workbench provides a Command Line Interface (CLI). For the current and historical versions of the AI Workbench CLI, see Release Notes. For Git support in the AI Workbench application, see Git in AI Workbench.

Tip

To get started with the AI Workbench CLI, see Basic Quickstart (CLI).

AI Workbench CLI Commands#

The following are the AI Workbench CLI commands.

AI Workbench

Locations

Integrations

Applications

Projects

Project Environment

Project Variables

Git

Global Options#

The following options are available for all AI Workbench CLI commands.

Option

Description

Type

Default Value

Valid Values

--context, -c

The name of the context (location) to use when running the command. This is useful for scripting and when you don’t activate a context before you run a command.

String

—

—

--debug

Run the command with debug logging.

—

—

—

--help, -h

Provides help for the command.

—

—

—

--output, -o

Determines the format of the output from the command. Set to json for JSON. Set to default for human readable text. If your terminal has TTY support, the output is rendered with styling.

String

default

default, json

--project, -p

The absolute path to the project to use when running the command. This is useful for scripting when you are not opening a project before you run a command. If you have a project open, and you run a command with this option, this option overrides the open project.

String

—

—

--workbench-dir

The path of the AI Workbench directory. Use this option when you install AI Workbench in a directory different from the default directory.

String

~/.nvwb

—

activate#

Synopsis#

1nvwb activate <context_name> [options]

Description#

Activate the context (location) specified by context_name. context_name is required. For more information, see AI Workbench Locations.

When you activate a context, the AI Workbench service starts, and your container runtime (Docker or Podman) starts.

After you activate a context, all subsequent CLI commands use the context by default, so you don’t need to specify the --context option.

Tip

Use list contexts to see the existing contexts before you run activate.

Options#

This command accepts relevant global options, and the following additional options.

Option

Description

Type

Default Value

Valid Values

--external-access

Enable access to an application that is running on the context after you share a link with a user. For more information see Share Your Working Application.

Warning

You are responsible for implementing appropriate security controls and managing network access to your remote computer.

—

—

—

Examples#

To activate the local context (location), run the following code.

1nvwb activate local

You should see output similar to the following.

1Connecting to local
2
3│ Please wait until AI Workbench is started and ready.

In addition, your command prompt changes to add the context (location) name, similar to the following.

1workbench@computer:~$
2(nvwb:local) workbench@computer:~$

add package#

Synopsis#

1nvwb add package [package-manager] [package-reference] [options]

Description#

Add one or more packages to the currently open project, or a specified project. For more information, see Packages.

package-manager is the name of the package manager, such as apt or pip, that should add the specified package. Package managers are configured in the project’s base environment.

package-reference is the name of the package to remove, or the package name and version information. You can specify multiple packages separated by a space for the same package manager.

If you don’t specify package-manager or package-reference, an interactive prompt appears, and you can type and use the arrow keys to make your selections.

Tip

Use list packages to see the existing packages before you run add package.

Options#

This command accepts relevant global options.

Examples#

To add a package, for example NumPy, run the following code.

1nvwb add package pip numpy

You should see output similar to the following.

1Package Manager: pip
2
3  PACKAGE   | VERSION SPECIFICATION(S) | INSTALLED IN BASE
4------------|--------------------------|-------------------
5 jupyterlab | >3.0                     | false
6 numpy      |                          | false

attach#

Synopsis#

1nvwb attach [options]

Description#

Attach to the container of the currently open project, or a specified project. Use this command when you need to open a shell session in the project container, or on the host computer running the AI Workbench service.

Options#

This command accepts relevant global options, and the following additional options.

Option

Description

Type

Default Value

Valid Values

--host

Attach to the host computer running the AI Workbench service.

—

—

—

build#

Synopsis#

1nvwb build [options]

Description#

Build the container for the currently open project, or a specified project, or stop a build. For more information, see AI Workbench Projects.

Tip

Use status to see the status of the project before you run build.

Options#

This command accepts relevant global options, and the following additional options.

Option

Description

Type

Default Value

Valid Values

--full-build

Regenerate the container file and force a full build.

—

—

—

--stop

Stop the current container build.

—

—

—

Examples#

To rebuild the container for the current project, run the following code.

1nvwb build --full-build

While the build is running, you should see output similar to the following.

1⣟ Building Environment ██████████████████████████████████████████████████ 28/28

When the build completes, you should see output similar to the following.

1✓ Container build complete (22.047173156s)

clone#

Synopsis#

1nvwb clone project [remoteURL] [options]

Description#

Clone an existing Git repository into an AI Workbench project in the currently open context (location), or a specified context. For more information, see Git in AI Workbench.

remoteURL is the URL of the existing repository to clone. If you don’t specify remoteURL, an interactive prompt appears, and you can type and use the arrow keys to make your selections.

Note

Before you can use CLI commands that perform Git actions, you must connect to your Git account from AI Workbench. For more information, see connect integration or Connect to Your Git Account and Other Integrations.

Options#

This command accepts relevant global options, and the following additional options.

Option

Description

Type

Default Value

Valid Values

--projectPath

The absolute path to a directory where the project should be cloned. If not specified, the project is cloned into the default project directory.

String

—

—

Examples#

To clone a project, run the following code.

1 nvwb clone project <url of repository>

You should see output similar to the following.

1✓ Project Clone complete (4.006585582s)
2
3Cloned project 'hello-world' (/home/workbench/nvidia-workbench/project-directory)
4
5✓ Container build complete (15.070521811s)

Note

After you clone a project, the project does not open automatically. To work in your new project, close any current project and open the new project.

close#

Synopsis#

1nvwb close [options]

Description#

Close the currently open project in the current context (location). For more information, see AI Workbench Projects.

Options#

This command accepts relevant global options, and the following additional options.

Note

close does not support the global options --context or --project.

Option

Description

Type

Default Value

Valid Values

--force, -f

If apps or the project container are running, stop them first, and then close the project.

—

—

—

Examples#

To close a project, run the following code.

1nvwb close

There is no output, but your command prompt changes to remove the project name, similar to the following.

Note

Even though you close the project, the project is still the current directory in your terminal.

1(nvwb:local/hello-world) workbench@computer:~/nvidia-workbench/hello-world$
2(nvwb:local) workbench@computer:~/nvidia-workbench/hello-world$

commit#

Synopsis#

1nvwb commit [options]

Description#

Stage and commit all new, modified, and deleted files. For more information, see Git in AI Workbench.

Use the --message to specify a log message. If you don’t specify --message, AI Workbench creates a message for you, and you can edit the message interactively by using the tab keys.

Note

Before you can use CLI commands that perform Git actions, you must connect to your Git account from AI Workbench. For more information, see connect integration or Connect to Your Git Account and Other Integrations.

Options#

This command accepts relevant global options, and the following additional options.

Option

Description

Type

Default Value

Valid Values

--message, -m

A log message that describes the changes to commit. The message is limited to 50 characters.

String

—

—

--overrideWarnings

Override any warnings and suggested remediation.

—

—

—

Examples#

To commit changes in your project, run the following code.

1nvwb commit --message "Important changes"

You should see output similar to the following.

1Successfully Staged and Committed all changes in project 'hello-world'

compose down#

Synopsis#

1nvwb experimental compose down [options]

Description#

Stop the running compose services for the currently open project, or a specified project. For more information, see Multiple Container Support With Docker Compose.

Warning

The compose commands are only supported if you are using Docker, not Podman, as your container runtime.

Tip

Use compose status to see the status of the compose environment before you run compose down.

Options#

This command accepts relevant global options.

Examples#

To stop the running compose services, run the following code.

1nvwb experimental compose down

You should see output similar to the following.

1⚫ Compose services are stopped

compose logs#

Synopsis#

1nvwb experimental compose logs

Description#

Get the logs of the compose services for the currently open project. For more information, see Multiple Container Support With Docker Compose.

Warning

The compose commands are only supported if you are using Docker, not Podman, as your container runtime.

If you call nvwb experimental compose logs, the output is streamed to the terminal window.

To save the output to a file, run the following code.

1nvwb experimental compose logs > output.txt

Options#

This command accepts no options.

compose status#

Synopsis#

1nvwb experimental compose status

Description#

Get the status of the compose services for the currently open project. For more information, see Multiple Container Support With Docker Compose.

Warning

The compose commands are only supported if you are using Docker, not Podman, as your container runtime.

This command indicates whether the compose services are starting up, running, stopping, or stopped.

Options#

This command accepts no options.

Examples#

To get the current status of the compose services, run the following code.

1nvwb experimental compose status

You should see output similar to the following.

1Compose status: services not running

compose up#

Synopsis#

1nvwb experimental compose up [options]

Description#

Start the compose services defined by the compose.yaml file at the root of the currently open project, or a specified project. For more information, see Multiple Container Support With Docker Compose.

Warning

The compose commands are only supported if you are using Docker, not Podman, as your container runtime.

If the compose services are already running, they are not be restarted. If you edit the compose.yaml file, first call compose down and then compose up to restart the environment with your changes.

Tip

Use compose status to see the status of the compose environment before you run compose up.

Options#

This command accepts relevant global options, and the following additional options.

Option

Description

Type

Default Value

Valid Values

--profile

Specify the profile to start. You can use multiple instances of --profile to specify multiple profiles. For more information, see Using profiles with Compose.

—

—

—

Examples#

To start the compose services defined by the compose.yaml file at the root of the currently open project, run the following code.

1nvwb experimental compose up

You should see output similar to the following.

1✅ Compose services are running

configure mounts#

Synopsis#

1nvwb configure mounts [source1:target1] [source2:target2] [options]

Description#

Configure existing mounts for the currently open project, or a specified project. If you want to create a new mount use create mount instead. This command overrides any current configuration for a mount. For more information, see AI Workbench Mounts.

Warning

You can’t run this command while the project container is running. Use status and stop to ensure the project container is stopped before you run this command.

Specify source:target where source is the directory in the currently open context (location), or a specified context to mount into the project container, and target is the new directory in the project container.

You can specify more than one source:target separated by spaces.

If you don’t specify source:target, an interactive prompt appears, and you can type and use the arrow keys to make your selections.

Tip

Use list mounts to see the existing mounts before you run configure mounts.

Options#

This command accepts relevant global options, and the following additional options.

Option

Description

Type

Default Value

Valid Values

--wide

Include all available columns in the output.

—

—

—

configure secrets#

Synopsis#

1nvwb configure secrets [variable1:value1] [variable2:value2] [options]

Description#

Configure existing secret variables for the currently open project, or a specified project. If you want to create a new secret variable use create secret instead. This command overrides any current value for a secret variable. For more information, see Secrets (Sensitive Environment Variables).

Warning

You can’t run this command while the project container is running. Use status and stop to ensure the project container is stopped before you run this command.

Specify variable:value where variable is the name of the secret variable and value is the new value for the secret variable. You can specify more than one variable:value separated by spaces.

If you don’t specify variable:value, an interactive prompt appears, and you can type and use the arrow keys to make your selections.

Tip

Use list secrets to see the existing secrets before you run configure secrets.

Options#

This command accepts relevant global options, and the following additional options.

Option

Description

Type

Default Value

Valid Values

--wide

Include all available columns in the output.

—

—

—

Examples#

To set the value of a secret variable named test1, run the following code.

1nvwb configure secrets test1:123456789 --wide

You should see output similar to the following.

Note

The value of the secret variable appears with all but the last 3 digits hidden.

11 secrets configured
2
3 VARIABLE | DESCRIPTION | CONFIGURED | VALUE
4----------|-------------|------------|-----------
5  test1   | Test var 1  | true       | ******789

connect integration#

Synopsis#

1nvwb connect integration [integration name [token|-]]  [options]

Description#

Connect an integration, such as GitHub or GitLab, and authorizes AI Workbench to make calls on behalf of the AI Workbench user. For more information, see AI Workbench Integrations.

Valid values for integration name include NGC, Github, Gitlab, and any custom integrations that you have created.

  • If you don’t specify integration name, an interactive prompt appears, and you can type and use the arrow keys to make your selections.

  • If you only specify integration name, an OAuth2 authentication workflow starts and you log in to the integration.

  • If you specify integration token, the token is used for authentication.

  • If you specify integration -, the token is read from stdin.

Tip

Use list integrations to see the existing integrations before you run connect integration.

Options#

This command accepts relevant global options, and the following additional options.

Option

Description

Type

Default Value

Valid Values

--no-browser, -n

Do not automatically open the local web browser if doing an OAuth2 login for credentials.

—

—

—

Examples#

To connect to GitHub, run the following code.

1nvwb connect integration Github

You should see output similar to the following.

1First, copy your one-time code: ####-####
2
3Then, Open this URL in your browser: https://github.com/login/device
4
5     NAME  |  DESCRIPTION   |       CREDENTIALS       | CONNECTED
6-----------|----------------|-------------------------|-----------
7  NGC      | ngc.nvidia.com | container-registry      | false
8  Github   | Github.com     | git, container-registry | true
9  Gitlab   | Gitlab.com     | git                     | false

create app#

Synopsis#

1nvwb create app [app-name] [app-type] [options]

Description#

Create an app in the currently open project, or a specified project. For more information, see AI Workbench Applications.

Warning

You can’t run this command while the project container is running. Use status and stop to ensure the project container is stopped before you run this command.

Specify app-name to give the application a name in your project.

app-type is the type of the application. Use custom to add a custom app to your project. When you add a custom app to your project you must specify the options required to run your application.

Use vs-code jupyterlab to add a built-in app type to your project. When you add a built-in app to your project, you don’t have to specify any options.

If you don’t specify the app name, app type, or required options, an interactive prompt appears, and you can type and use the arrow keys to make your selections.

Tip

Use list apps to see the existing apps before you run create app.

Options#

This command accepts relevant global options, and the following additional options.

Option

Description

Type

Default Value

Valid Values

--app-class

The class of application, used to determine what optional configuration options are available.

String

—

process, webapp

--health-check-cmd

The shell command used to check the health or status of the application. A return of zero means the application is running and healthy. A return of non-zero means that the application is not running or unhealthy.

String

—

—

--icon-url

An optional link to the icon or image used for the application.

String

—

—

--process-wait-until-finished

Available if --app-class is process. True if the AI Workbench desktop application should wait for the application to finish; false if the desktop app should let it run in the background. If true the desktop app notifies you when the process completes. The CLI always waits.

Boolean

true

true, false

--start-cmd

The shell command used to start the application. Must not be a blocking command.

String

—

—

--stop-cmd

The shell command used to stop the application.

String

—

—

--timeout-seconds

The number of seconds that AI Workbench waits for the health_check_command to complete.

Integer

60

Greater than 0 and less than 3600

--user-msg

An optional message that appears to the user when the application is running. If --app-class is webapp, you can use the placeholder string {{URL}} in the message, and it is populated after the app starts.

String

—

—

--webapp-auto-launch

Available if --app-class is webapp. True if AI Workbench should automatically open the application URL for the user; otherwise, false.

Boolean

true

true, false

--webapp-port

Available if --app-class is webapp. The port that the application runs on.

String

—

—

--webapp-proxy-trim-prefix

Available if --app-class is webapp. True if the AI Workbench reverse proxy should remove the application-specific URL prefix before forwarding the request to the application; otherwise, false.

Boolean

false

true, false

--webapp-url

The static URI used to access a web application. If --app-class is webapp, you must specify --webapp-url or --webapp-url-cmd, but not both.

String

—

—

--webapp-url-cmd

The shell command used to get the URI for a web application. The output from this command is considered the URL. If --app-class is webapp, you must specify --webapp-url or --webapp-url-cmd, but not both.

String

—

—

Examples#

To create a new app in your project, of the built-in vs-code type, run the following code.

1nvwb create app "test app" vs-code

You should see output similar to the following.

1     NAME    |    TYPE    | CLASS  | RUN STATE
2-------------|------------|--------|-------------
3  test app   | vs-code    | native | ⚫ Stopped
4  jupyterlab | jupyterlab | webapp | ⚫ Stopped

To create a new custom app in your project, run code similar to the following.

Tip

You can find more details about this example in Walkthrough: Add a Custom Application.

1nvwb create app simple-gradio custom --app-class=webapp --health-check-cmd="curl -f http://localhost:8080/" --start-cmd="cd /project/code && PROXY_PREFIX=$PROXY_PREFIX python3 app.py" --stop-cmd="pkill -f '^python3 app.py'" --webapp-port=8080 --webapp-url="http://localhost:8080/" --webapp-auto-launch

You should see output similar to the following.

1      NAME      |    TYPE    | CLASS  | RUN STATE
2----------------|------------|--------|-------------
3  simple-gradio | custom     | webapp | ⚫ Stopped
4  jupyterlab    | jupyterlab | webapp | ⚫ Stopped

create branch#

Synopsis#

1 nvwb create branch [branch-name] [options]

Description#

Create and switch to a new git branch in the currently open project, or a specified project. For more information, see Git in AI Workbench.

branch-name is the name for the new branch.

If you don’t specify a required option, an interactive prompt appears, and you can type and use the arrow keys to make your selections.

Tip

Use list branches to see the existing branches before you run create branch.

Options#

This command accepts relevant global options, and the following additional options.

Option

Description

Type

Default Value

Valid Values

--carry

Bring any uncommitted or untracked changes in the current branch to the new branch.

—

—

—

Examples#

To create a new branch named feature-1, run the following code.

1nvwb create branch feature-1

You should see output similar to the following.

1   NAME    | BRANCH TYPE | REMOTE ALIAS | CURRENT BRANCH
2-----------|-------------|--------------|-----------------
3 feature-1 | LOCAL       |              | ✅
4 main      | LOCAL       | origin       |

create context#

Synopsis#

1nvwb create context [context_name] [hostname] [options]

Description#

Create a new context (location) to run AI Workbench projects. For more information, see AI Workbench Locations.

context_name is the name for the context. context_name is limited to 47 characters using [a-zA-Z0-9-_].

hostname is the hostname or IP address of the computer for the context. Specify localhost if the new context is the same computer that you are running the CLI on.

If you don’t specify a required option, an interactive prompt appears, and you can type and use the arrow keys to make your selections.

Tip

Use list contexts to see the existing contexts before you run create context.

Options#

This command accepts relevant global options, and the following additional options.

Option

Description

Type

Default Value

Valid Values

--accept-ssh-fingerprints

Accept the SSH fingerprints for the context (location).

—

—

—

--brev-instance-name

Configure the specified Brev instance for the context (location).

String

—

—

--context-workbench-dir

The internal workbench directory where the workbench service stores configuration and internal data. For most installations this is /home/<username>/.nvwb, which is the default directory.

String

—

—

--description, -d

A description for the context (location).

String

—

—

--ssh-key-path

The path to the SSH key to use when you connect to this context (location). For keys held by ssh-agent, provide the matching public key.

String

—

—

--ssh-port

The target SSH port to use when you connect to this context (location).

Integer

22

—

--ssh-username

The username to use when you connect to this context (location).

String

—

—

create environment-variable#

Synopsis#

1nvwb create environment-variable variable value [options]

Description#

Create an environment variable in the currently open project, or a specified project. For more information, see Environment Variables.

Warning

You can’t run this command while the project container is running. Use status and stop to ensure the project container is stopped before you run this command.

variable is the name for the environment variable. variable can contain only letters, numbers, and underscores.

value is the value for the environment variable.

If you don’t specify variable or value, an interactive prompt appears, and you can type and use the arrow keys to make your selections.

Tip

Use list environment-variables to see the existing environment-variables before you run create environment-variable.

Options#

This command accepts relevant global options, and the following additional options.

Option

Description

Type

Default Value

Valid Values

--description

The description of the environment variable.

String

—

—

Examples#

To create a new environment variable, run the following code.

1nvwb create environment-variable MyVariable 123456 --description "a test variable"

You should see output similar to the following.

1   VARIABLE  | VALUE  |   DESCRIPTION
2-------------|--------|-----------------
3  MyVariable | 123456 | a test variable

create integration#

Synopsis#

1nvwb create integration [options]

Description#

Create an integration, such as GitHub or GitLab, and authorizes AI Workbench to make calls on behalf of the AI Workbench user. For more information, see AI Workbench Integrations.

When you run this command, an interactive prompt appears, and you can type and use the arrow keys to make your selections. If you want to create an integration without using the interactive interface, add a JSON configuration file for the integration to ~/.nvwb/ or C:\Users\<username>\AppData\Local\NVIDIA Corporation\AI Workbench\.

Tip

Use list integrations to see the existing integrations before you run create integration.

Options#

This command accepts relevant global options.

Examples#

To create an integration, run the following code.

1nvwb create integration

An interactive prompt appears. When you are done creating the integration, you should see output similar to the following.

1     NAME  |  DESCRIPTION   |       CREDENTIALS       | CONNECTED
2-----------|----------------|-------------------------|-----------
3  NGC      | ngc.nvidia.com | container-registry      | false
4  Github   | Github.com     | git, container-registry | true
5  Gitlab   | Gitlab.com     | git                     | false

create mount#

Synopsis#

1nvwb create mount [type] [target] [options]

Description#

Create a new mount for the currently open project, or a specified project. For more information, see AI Workbench Mounts.

This command only creates the definition of a mount. To configure what host directories are mounted when the project starts, use configure mounts.

type is the type of the mount. The following are the valid values:

  • PROJECT — The mount that defines where the project’s directory is mounted into the project container.

  • HOST — Mount a directory from the computer where the project is located into the project container.

  • VOLUME — Create a persistent volume in a project container for storing data that is not erased when a container is rebuilt.

  • TMP — Create a temporary directory in a project container that is reset each time the project starts.

Warning

If a project is deleted, or a mount is deleted, any data stored in a volume mount is also deleted.

target is the target directory in the project container where the mount data is mounted. Each mount target is unique, and must be an absolute path (starting with a ‘/’ character).

If you don’t specify a required option, an interactive prompt appears, and you can type and use the arrow keys to make your selections.

Tip

Use list mounts to see the existing mounts before you run create mount.

Options#

This command accepts relevant global options, and the following additional options.

Option

Description

Type

Default Value

Valid Values

--description

The description of the mount.

String

—

—

--options

Additional options for the mount.

String

—

—

create project#

Synopsis#

1nvwb create project [name] [options]

Description#

Create a new project in the currently open context (location), or a specified context. For more information, see AI Workbench Projects.

name is a unique name for the project. name is limited to 47 characters using [a-zA-Z0-9-_].

If you don’t specify a required option, an interactive prompt appears, and you can type and use the arrow keys to make your selections.

Tip

Use list projects to see the existing projects before you run create project.

Options#

This command accepts relevant global options, and the following additional options.

Option

Description

Type

Default Value

Valid Values

--base-environment-id

The ID for the base environment image. Use list bases with the --wide and --output json options to see the existing bases and get the ID for the base you want. Specify --base-environment-id or --base-url, but not both.

String

—

—

--base-url

The URL for a custom base environment image. Specify the URL in the format registry-name/image-or-repository-name:tag. Provide the registry even for Docker images. Specify --base-environment-id or --base-url, but not both.

String

—

—

--description

A description for the project.

String

—

—

--projectPath

The absolute path to the directory where the project should be created. Otherwise the project is created in the default directory.

String

—

—

Examples#

To create a new project, run the following code.

1nvwb create project "My Project 1" --description "Test project 1" --base-environment-id "eyJpbWFnZS..."

You should see output similar to the following.

1Created new project 'My-Project-1' (/home/workbench/nvidia-workbench/My-Project-1)
2
3✓ Container build complete (26.074698246s)

create secret#

Synopsis#

1nvwb create secret [variable] [options]

Description#

Create a new secret variable for the currently open project, or a specified project. For more information, see Secrets (Sensitive Environment Variables).

This command only creates the definition of a secret variable. To set the value of a secret variable, use configure secrets.

Warning

You can’t run this command while the project container is running. Use status and stop to ensure the project container is stopped before you run this command.

variable is the name for the secret variable. variable can contain only letters, numbers, and underscores.

If you don’t specify variable, an interactive prompt appears, and you can type and use the arrow keys to make your selections.

Tip

Use list secrets to see the existing secrets before you run create secret.

Options#

This command accepts relevant global options, and the following additional options.

Option

Description

Type

Default Value

Valid Values

--description

The description of the secret variable.

String

—

—

Examples#

To create a secret variable named test2, run the following code.

1nvwb create secret test2 --description "Test var 2"

You should see output similar to the following.

1  VARIABLE | DESCRIPTION | CONFIGURED
2-----------|-------------|------------
3  test1    | Test var 1  | true
4  test2    | Test var 2  | false

Note

To set the value of test2, use configure secrets.

create share-url#

Synopsis#

1nvwb create share-url [app_name] [options]

Description#

Create a URL that you can use to share access to an application running on a remote context. For more information, see Share Your Working Application.

app_name is the name of the application that you want to share. If you don’t specify app_name, an interactive prompt appears, and you can type and use the arrow keys to make your selections.

The remote context must already be activated with the --external-access option, and the application must already be started.

Tip

Use list apps to see the existing apps and their status before you run create share-url.

Options#

This command accepts relevant global options.

Note

Do not use the --context option with this command.

Examples#

To create a URL to share an application named test-app-1, run the following code.

1nvwb create share-url test-app-1

You should see output similar to the following.

1Successfully generated unique sharable URL
2
3| Available at: https://address/share/ABC123

deactivate#

Synopsis#

1nvwb deactivate [options]

Description#

Deactivate the currently open context (location), or a specified context. For more information, see AI Workbench Locations.

If you don’t specify the --shutdown option, the context is no longer the default context for your terminal session, but the container runtime and AI Workbench service remain running.

If you specify the --shutdown option, the AI Workbench service also stops.

Tip

Use list contexts to see the existing contexts before you run deactivate.

Options#

This command accepts relevant global options, and the following additional options.

Option

Description

Type

Default Value

Valid Values

--force, -f

Deactivate the context even if project apps are still running.

—

—

—

--shutdown

Stop the workbench service, tunnels, and other resources for the currently open context (location), or a specified context.

—

—

—

Examples#

To deactivate the current context (location), run the following code.

1nvwb deactivate

There is no output, but your command prompt changes to remove the context (location) name, similar to the following.

1(nvwb:local) workbench@computer:~$
2workbench@computer:~$

delete app#

Synopsis#

1nvwb delete app [app-name] [options]

Description#

Delete an app from the currently open project, or a specified project. For more information, see AI Workbench Applications.

app-name is the name of the app to delete.

If you don’t specify app-name, an interactive prompt appears, and you can type and use the arrow keys to make your selections.

Tip

Use list apps to see the existing apps before you run delete app.

Options#

This command accepts relevant global options.

Examples#

To delete an app named test app from your project, run the following code.

1nvwb delete app "test app"

The output is a table of the apps that remain in the project.

delete branch#

Synopsis#

1 nvwb delete branch [branch-name] [options]

Description#

Delete a local branch in the currently open project, or a specified project. For more information, see Git in AI Workbench.

branch-name is the name of the branch to delete.

If you don’t specify a required option, an interactive prompt appears, and you can type and use the arrow keys to make your selections.

Tip

Use list branches to see the existing branches, and the current branch, before you run delete branch.

Options#

This command accepts relevant global options, and the following additional options.

Option

Description

Type

Default Value

Valid Values

--force

Delete a branch with changes that have not been merged.

—

—

—

Examples#

To delete a branch named feature-1, run the following code.

1nvwb delete branch feature-1

You should see output similar to the following.

1   NAME    | BRANCH TYPE | REMOTE ALIAS | CURRENT BRANCH
2-----------|-------------|--------------|-----------------
3 main      | LOCAL       | origin       | ✅

delete context#

Synopsis#

1nvwb delete context [context_name] [options]

Description#

Delete information about an existing context (location). For more information, see AI Workbench Locations.

Note

This command deletes information about the context that is stored by AI Workbench locally. No data or information is deleted on the context itself.

context_name is the name of the location to delete.

If you don’t specify context_name, an interactive prompt appears, and you can type and use the arrow keys to make your selections.

Tip

Use list contexts to see the existing contexts before you run delete context.

Options#

This command accepts relevant global options.

delete environment-variable#

Synopsis#

1nvwb delete environment-variable [variable] [options]

Description#

Delete an environment variable from the currently open project, or a specified project. For more information, see Environment Variables.

variable is the name of the environment variable to delete.

If you don’t specify variable, an interactive prompt appears, and you can type and use the arrow keys to make your selections.

Tip

Use list environment-variables to see the existing environment-variables before you run delete environment-variable.

Options#

This command accepts relevant global options.

Examples#

To delete an environment variable named MyVariable, run the following code.

1 nvwb delete environment-variable MyVariable

The output is a table of the environment variables that remain in the project.

delete integration#

Synopsis#

1nvwb delete integration [integration name] [options]

Description#

Delete an integration, such as GitHub or GitLab. For more information, see AI Workbench Integrations.

integration name is the name of the integration to delete.

If you don’t specify integration name, an interactive prompt appears, and you can type and use the arrow keys to make your selections.

Tip

Use list integrations to see the existing integrations before you run delete integration.

Options#

This command accepts relevant global options.

Examples#

To delete an integration named Custom Integration 1, run the following code.

1nvwb delete integration "Custom Integration 1"

The output is a table of the integrations that remain.

delete mount#

Synopsis#

1nvwb delete mount [target] [options]

Description#

Delete a mount from the currently open project, or a specified project. For more information, see AI Workbench Mounts.

Warning

You can’t run this command while the project container is running. Use status and stop to ensure the project container is stopped before you run this command.

target is the target directory in the project container where the mount data is mounted.

Warning

If a mount is deleted, any data stored in a volume mount is also deleted.

If you don’t specify target, an interactive prompt appears, and you can type and use the arrow keys to make your selections.

Tip

Use list mounts to see the existing mounts before you run delete mount.

Options#

This command accepts relevant global options.

delete project#

Synopsis#

1nvwb delete project [project_name or project_path] [options]

Description#

Delete a project from the currently open context (location), or a specified context. For more information, see AI Workbench Projects.

project_name is the name of the project to delete.

project_path is the absolute path of the project.

Note

The delete project command only deletes the copy of the project in the currently open context (location), or a specified context. This command does not delete the project from any Git servers that contain the project.

If you don’t specify a required option, an interactive prompt appears, and you can type and use the arrow keys to make your selections.

Tip

Use list projects to see the existing projects before you run delete project.

Options#

This command accepts relevant global options.

Examples#

To delete a project named hello-world, run the following code.

1nvwb delete project hello-world

The output is a table of the projects that remain.

delete secret#

Synopsis#

1nvwb delete secret [variable] [options]

Description#

Delete a secret variable from the currently open project, or a specified project. For more information, see Secrets (Sensitive Environment Variables).

Warning

You can’t run this command while the project container is running. Use status and stop to ensure the project container is stopped before you run this command.

variable is the name of the secret variable to delete.

If you don’t specify variable, an interactive prompt appears, and you can type and use the arrow keys to make your selections.

Tip

Use list secrets to see the existing secrets before you run delete secret.

Options#

This command accepts relevant global options.

Examples#

To delete a secret variable named test2, run the following code.

1nvwb delete secret test2

The output is a table of the secret variables that remain.

discard#

Synopsis#

1 nvwb discard [file-1] [file-2]... [options]

Description#

Discard uncommitted or untracked changes in the current branch of the currently open project, or a specified project. For more information, see Git in AI Workbench.

You can specify one or more files in the project repository, and only those changes are discarded. Specify files by using the relative path.

If you don’t specify any files, all uncommitted and untracked changes are discarded, and all untracked files are deleted.

Options#

This command accepts relevant global options.

Examples#

To discard all changes in the current branch, run the following code.

1nvwb nvwb discard

You should see output similar to the following.

1Successfully discarded changes in project 'test-project-1'

disconnect integration#

Synopsis#

1nvwb disconnect integration [integration name] [options]

Description#

Disconnect an integration, such as GitHub or GitLab. For more information, see AI Workbench Integrations.

Valid values for integration name include NGC, Github, Gitlab, and any custom integrations that you have created. If you don’t specify integration name, an interactive prompt appears, and you can type and use the arrow keys to make your selections.

Tip

Use list integrations to see the existing integrations before you run disconnect integration.

Options#

This command accepts relevant global options.

Examples#

To disconnect your GitHub integration, run the following code.

1nvwb disconnect integration Github

You should see output similar to the following.

1     NAME  |  DESCRIPTION   |       CREDENTIALS       | CONNECTED
2-----------|----------------|-------------------------|-----------
3  NGC      | ngc.nvidia.com | container-registry      | false
4  Github   | Github.com     | git, container-registry | false
5  Gitlab   | Gitlab.com     | git                     | false

fetch#

Synopsis#

1nvwb fetch [options]

Description#

Fetch changes from your remote Git repository. For more information, see Git in AI Workbench.

Note

Before you can use CLI commands that perform Git actions, you must connect to your Git account from AI Workbench. For more information, see connect integration or Connect to Your Git Account and Other Integrations.

Options#

This command accepts relevant global options.

Examples#

To fetch changes from your remote Git repository, run the following code.

1nvwb fetch

You should see output similar to the following.

1✓ Project fetch complete (3.009665582s)
2
3Successfully fetched project 'hello-world'

history#

Synopsis#

1nvwb history [options]

Description#

Show the commit logs for the currently open project, or a specified project. For more information, see Git in AI Workbench.

Note

Before you can use CLI commands that perform Git actions, you must connect to your Git account from AI Workbench. For more information, see connect integration or Connect to Your Git Account and Other Integrations.

Options#

This command accepts relevant global options, and the following additional options.

Option

Description

Type

Default Value

Valid Values

--number, -n

The maximum number of commits to include in the output.

Integer

—

—

Examples#

To see the most recent commit for a project, run the following code.

1nvwb history --number=1

You should see output similar to the following.

1commit 17bd1938dc0a1a369618cc7ef76f0f084cb048e1
2Author: Name <email@example.com>
3Date: 2024-09-04 12:52:46 UTC
4
5My commit message: important changes

install#

Synopsis#

See the Examples section.

Description#

Install AI Workbench and dependencies on the computer. You invoke the install command from outside the CLI. For more information, see Install, Update, and Uninstall AI Workbench.

You must run this command with admin privileges, and you can run the command in the following modes:

  • Interactive mode — Don’t specify any options. You are prompted for all options as the install occurs.

  • Non-interactive mode — Specify all required options.

If you run this command as root to install AI Workbench for another user, you must specify the --uid and --gid options.

After the installation completes, restart your shell session and then the nvwb command is available in your terminal.

Options#

This command accepts relevant global options, and the following additional options.

Option

Description

Type

Default Value

Valid Values

--noninteractive

Install AI Workbench in non-interactive mode. Required for non-interactive installation.

—

—

—

--accept, -a

Accept the End User License Agreement for NVIDIA AI Workbench. Required for non-interactive installation.

—

—

—

--drivers

Install NVIDIA GPU drivers. Required if you want to install drivers.

—

—

—

--docker

Use Docker as your container runtime. One of --docker or --podman is required for non-interactive installation.

—

—

—

--podman

Use Podman as your container runtime. Choose one of --docker or --podman. One of --docker or --podman is required for non-interactive installation.

—

—

—

--gid

The group ID of the AI Workbench user. Required when you install AI Workbench for another user.

Integer

—

—

--uid

The user ID of the AI Workbench user. Required when you install AI Workbench for another user.

Integer

—

—

Examples#

To install AI Workbench on macOS or Linux, run the following code.

1sudo -E  $HOME/.nvwb/bin/nvwb-cli install

To install AI Workbench on Windows, run the following code in Powershell or Terminal.

1wsl -d NVIDIA-Workbench -u root -- /home/workbench/.nvwb/bin/nvwb-cli install --uid 1000 --gid 1000

list apps#

Synopsis#

1nvwb list apps [options]

Description#

List the applications available in the currently open project, or a specified project. For more information, see AI Workbench Applications.

Options#

This command accepts relevant global options.

Examples#

To list the apps available the current project, run the following code.

1nvwb list apps

You should see output similar to the following.

1      NAME      |    TYPE    | CLASS  | RUN STATE
2----------------|------------|--------|-------------
3  simple-gradio | custom     | webapp | ⚫ Stopped
4  jupyterlab    | jupyterlab | webapp | ⚫ Stopped

list bases#

Synopsis#

1nvwb list bases [options]

Description#

List the available base environments. For more information, see Container Environments for AI Workbench Projects.

Options#

This command accepts relevant global options, and the following additional options.

Option

Description

Type

Default Value

Valid Values

--wide

For some list subcommands, not all data appears in the output. Use the --wide option to see all available data in the output. Include the --output json option if the output is too wide for the screen.

—

—

—

Examples#

To see the available base environments, run the following code.

1nvwb list bases --wide --output json

You should see output similar to the following.

 1{
 2   "result": [
 3      {
 4         "Id": "eyJpbWFnZSI6Im52aWRpYS9haS13b3JrYmVuY...",
 5         "SchemaVersion": "v2",
 6         "Name": "Python Basic",
 7         "Description": "A Python Base with Jupyterlab",
 8         "ImageVersion": "1.0.2",
 9         "BuildTimestamp": "20231114175838",
10         "ContainerRegistry": "nvcr.io",
11         "ContainerImage": "nvidia/ai-workbench/python-basic",
12         "ContainerImageTag": "1.0.2",
13         "CudaVersion": "",
14         "Os": "linux",
15         "OsDistro": "ubuntu",
16         "OsDistroRelease": "22.04",
17         "ProgrammingLanguages": [
18            "python3"
19         ],
20
21         ... more data ...
22
23      }
24   ]
25}

list branches#

Synopsis#

1nvwb list branches [options]

Description#

List the available branches in the currently open project, or a specified project. For more information, see Git in AI Workbench.

Options#

This command accepts relevant global options.

Examples#

To see the available branches in the current project, run the following code.

1nvwb list branches

You should see output similar to the following.

1   NAME    | BRANCH TYPE | REMOTE ALIAS | CURRENT BRANCH
2-----------|-------------|--------------|-----------------
3 feature-1 | LOCAL       |              | ✅
4 main      | LOCAL       | origin       |

list built-in-apps#

Synopsis#

1nvwb list built-in-apps [options]

Description#

List the built-in applications. For more information, see Built-in Apps.

Options#

This command accepts relevant global options.

Examples#

To list the built-in applications, run the following code.

1nvwb list built-in-apps

You should see output similar to the following.

1  BUILT IN APPLICATION | APPLICATION TYPE | APPLICATION CLASS
2-----------------------|------------------|-------------------
3  Jupyterlab           | jupyterlab       | webapp
4  Visual Studio Code   | vs-code          | native

list contexts#

Synopsis#

1nvwb list contexts [options]

Description#

List the available contexts (locations). For more information, see AI Workbench Locations.

Options#

This command accepts relevant global options, and the following additional options.

Option

Description

Type

Default Value

Valid Values

--wide

For some list subcommands, not all data appears in the output. Use the --wide option to see all available data in the output. Include the --output json option if the output is too wide for the screen.

—

—

—

Examples#

To list available contexts (locations), run the following code.

1nvwb list contexts

You should see output similar to the following.

1  NAME  |       DESCRIPTION  | HOSTNAME  |   STATUS    | EXTERNAL ACCESS
2--------|--------------------|-----------|------------ |-----------------
3  local | My Computer (name) | localhost | 🟢 Running  | ⚫ Not Enabled

list environment-variables#

Synopsis#

1nvwb list environment-variables [options]

Description#

List the environment-variables defined in the currently open project, or a specified project. For more information, see Environment Variables.

Options#

This command accepts relevant global options.

Examples#

To list the environment variables in the current project, run the following code.

1nvwb list environment-variables

You should see output similar to the following.

1   VARIABLE  | VALUE  |   DESCRIPTION
2-------------|--------|-----------------
3  MyVariable | 123456 | a test variable

list integrations#

Synopsis#

1nvwb list integrations [options]

Description#

List the available integrations. For more information, see AI Workbench Integrations.

Options#

This command accepts relevant global options, and the following additional options.

Option

Description

Type

Default Value

Valid Values

--wide

For some list subcommands, not all data appears in the output. Use the --wide option to see all available data in the output. Include the --output json option if the output is too wide for the screen.

—

—

—

Examples#

To list available integrations, run the following code.

1nvwb list integrations

You should see output similar to the following.

1     NAME  |  DESCRIPTION   |       CREDENTIALS       | CONNECTED
2-----------|----------------|-------------------------|-----------
3  NGC      | ngc.nvidia.com | container-registry      | false
4  Github   | Github.com     | git, container-registry | true
5  Gitlab   | Gitlab.com     | git                     | false

list mounts#

Synopsis#

1nvwb list mounts [options]

Description#

List the mounts defined for the currently open project, or a specified project. For more information, see AI Workbench Mounts.

Options#

This command accepts relevant global options, and the following additional options.

Option

Description

Type

Default Value

Valid Values

--wide

For some list subcommands, not all data appears in the output. Use the --wide option to see all available data in the output. Include the --output json option if the output is too wide for the screen.

—

—

—

Examples#

To see the mounts in the current project, run the following code.

1nvwb list mounts --wide

You should see output similar to the following.

1All mounts are configured
2
3   TYPE   |  TARGET   |    DESCRIPTION    | CONFIGURED |       SOURCE       | OPTIONS
4----------|-----------|-------------------|------------|--------------------|---------
5  PROJECT | /project/ | Project directory | true       | (ProjectDirectory) | rw

list packages#

Synopsis#

1nvwb list packages [options]

Description#

List the packages available in the currently open project, or a specified project. For more information, see Packages.

Options#

This command accepts relevant global options, and the following additional options.

Option

Description

Type

Default Value

Valid Values

--package-manager, -m

Filters the output to only packages managed by the specified package manager.

String

—

apt, pip

Examples#

To see available packages for the pip package manager, run the following code.

1nvwb list packages -m pip

You should see output similar to the following.

1Package Manager: pip
2
3   PACKAGE   | VERSION SPECIFICATION(S) | INSTALLED IN BASE
4-------------|--------------------------|-------------------
5  jupyterlab | >3.0                     | false
6  numpy      |                          | false

list projects#

Synopsis#

1nvwb list projects [options]

Description#

List the projects available in the currently open context (location), or a specified context. For more information, see AI Workbench Projects.

Options#

This command accepts relevant global options, and the following additional options.

Option

Description

Type

Default Value

Valid Values

--wide

For some list subcommands, not all data appears in the output. Use the --wide option to see all available data in the output. Include the --output json option if the output is too wide for the screen.

—

—

—

Examples#

To list the projects in the active context, run the following code.

1nvwb list projects

You should see output similar to the following.

1     NAME     |         DESCRIPTION          | CONTAINER   | APPS
2--------------|------------------------------|-------------|----------------
3  hello-world | A simple hello world project | ⚫ Stopped  | ⚫ jupyterlab

list resources#

Synopsis#

1nvwb list resources [options]

Description#

List the hardware resources requested by the currently open project, or a specified project. For more information, see Hardware.

Options#

This command accepts relevant global options.

Examples#

To list the hardware requested by the current project, run the following code.

1nvwb list resources

You should see output similar to the following.

1GPUs Requesed: 4
2
3Shared Memory in MB: 0

list secrets#

Synopsis#

1nvwb list secrets [options]

Description#

List the secrets in the currently open project, or a specified project. For more information, see Secrets (Sensitive Environment Variables).

Tip

For some list commands, not all data appears in the output. Use the --wide option to see all available data in the output. Use the --output json option if the output is too wide for the screen.

Options#

This command accepts relevant global options, and the following additional options.

Option

Description

Type

Default Value

Valid Values

--wide

Include all available columns in the output.

—

—

—

Examples#

To list the secrets in the current project, run the following code.

1nvwb list secrets

You should see output similar to the following.

11 secrets(s) are unconfigured
2
3  VARIABLE | DESCRIPTION | CONFIGURED
4-----------|-------------|------------
5  test1    | Test var 1  | true
6  test2    | Test var 2  | false

merge#

Synopsis#

1 nvwb merge [branch-name] [options]

Description#

Merge new commits from the specified branch into the current branch in the currently open project, or a specified project. For more information, see Git in AI Workbench.

branch-name is the name of the branch to merge from. You can specify a remote branch by including the remote alias, for example origin/feature-1.

merge only supports conflict-free merges. If merge conflicts occur, the merge is cancelled, and you must resolve conflicts manually, or in the AI Workbench desktop application.

If you don’t specify a required option, an interactive prompt appears, and you can type and use the arrow keys to make your selections.

Tip

Use list branches to see the existing branches, and the current branch, before you run merge.

Options#

This command accepts relevant global options.

Examples#

To merge branch feature-1 into main, run the following code while main is the current branch.

1nvwb merge feature-1

You should see output similar to the following.

1Successfully merged branch 'feature-1' into current branch 'main'
2
3Current Branch Details:
4
5Name: main Branch Type: LOCAL Remote Alias: origin

open#

Synopsis#

1nvwb open [project_name or project_path] [options]

Description#

Open a project in the currently open context (location), or a specified context. For more information, see AI Workbench Projects.

If you don’t specify project_name, an interactive prompt appears, and you can type and use the arrow keys to make your selections.

If you specify project_path, you must provide an absolute path.

After you open a project, all subsequent CLI commands use the project by default, so you don’t need to specify the --project option.

Tip

Use list projects to see the existing projects before you run open.

Options#

This command accepts relevant global options.

Examples#

To open a project in the current context (location), run the following code.

1nvwb open hello-world

There is no output, but your command prompt changes to include the project name, similar to the following.

1(nvwb:local) workbench@computer:~$
2(nvwb:local/hello-world) workbench@computer:~/nvidia-workbench/hello-world$

publish#

Synopsis#

1nvwb publish <remote-server-url> <namespace> <visibility> [options]

Description#

Push the currently open project, or a specified project to your Git server for the first time. After you publish successfully one time, use push in the future. For more information, see Git in AI Workbench.

remote-server-url is the Git server base URL, including the protocol, such as https://github.com.

namespace is the namespace on the Git server where the repository is created. This might be your personal account name, or an organization or team that you belong to.

visibility is the visibility setting for the repository on the Git server. Valid values are public and private. For self-hosted Git servers, internal is also valid.

If you don’t specify remote-server-url or namespace, an interactive prompt appears, and you can type and use the arrow keys to make your selections.

Note

Before you can use CLI commands that perform Git actions, you must connect to your Git account from AI Workbench. For more information, see connect integration or Connect to Your Git Account and Other Integrations.

Options#

This command accepts relevant global options.

Examples#

To publish your project to your Git server, run the following code.

1nvwb publish https://github.com <git namespace> private

You should see output similar to the following.

1Publishing project, please wait...
2
3✓ Project Push complete (4.011624462s)
4
5Successfully published project to https://github.com/namespace/hello-world.git

pull#

Synopsis#

1nvwb pull [options]

Description#

Pull changes from your remote Git repository into the currently open project, or a specified project. For more information, see Git in AI Workbench.

If you have uncommitted changes in your project, you must commit the changes before you can pull.

pull only supports conflict-free pulls. If merge conflicts occur, the pull is cancelled, and you must resolve conflicts manually, or in the AI Workbench desktop application.

Note

Before you can use CLI commands that perform Git actions, you must connect to your Git account from AI Workbench. For more information, see connect integration or Connect to Your Git Account and Other Integrations.

Options#

This command accepts relevant global options.

Examples#

To pull changes from your remote Git repository into your project, run the following code.

1nvwb pull

You should see output similar to the following.

1✓ Project Pull complete (4.005346608s)
2
3Successfully pulled project 'hello-world'

push#

Synopsis#

1nvwb push [options]

Description#

Push changes to your remote Git repository from the currently open project, or a specified project. The first time you push changes, use publish instead. For more information, see Git in AI Workbench.

Note

Before you can use CLI commands that perform Git actions, you must connect to your Git account from AI Workbench. For more information, see connect integration or Connect to Your Git Account and Other Integrations.

Options#

This command accepts relevant global options.

Examples#

To push project changes to your remote Git repository, run the following code.

1nvwb push

You should see output similar to the following.

1✓ Project Push complete (3.010268434s)
2
3Successfully Pushed project 'hello-world'

remove package#

Synopsis#

1nvwb remove package [package-manager] [package-reference] [options]

Description#

Remove one or more packages from the currently open project, or a specified project. For more information, see Packages.

package-manager is the name of the package manager, such as apt or pip, that should remove the specified package. Package managers are configured in the project’s base environment.

package-reference is the name of the package to remove, or the package name and version information. You can specify multiple packages separated by a space for the same package manager.

If you don’t specify package-manager or package-reference, an interactive prompt appears, and you can type and use the arrow keys to make your selections.

Tip

Use list packages to see the existing packages before you run remove package.

Options#

This command accepts relevant global options.

Examples#

To remove a package, for example NumPy, run the following code.

1nvwb remove package pip numpy

You should see output similar to the following.

1✓ Remove package(s) complete (6.009000228s)

start#

Synopsis#

1nvwb start [app_name] [options]

Description#

Start an application from the currently open project, or a specified project. If the project’s container is not running, it is started automatically. For more information, see AI Workbench Applications.

If you don’t specify an app name, an interactive prompt appears, and you can type and use the arrow keys to make your selections.

If the application is a web app, such as Jupyterlab, the application opens in your default web browser.

Tip

Use list apps to see the existing apps before you run start.

Options#

This command accepts relevant global options, and the following additional options.

Option

Description

Type

Default Value

Valid Values

--container

Start the project container, but do not start any apps.

—

—

—

--no-browser, -n

Starts the app, but does not open a web browser.

—

—

—

--no-gpus, -g

Start the app without GPUs. Use this option when you want to start an app that requires GPUs, and GPUs are not available on your computer.

—

—

—

--timeout

The number of seconds to wait for the application to start and become reachable before an error occurs.

Integer

5

—

Examples#

To start a specific app, for example JupyterLab run the following code.

1nvwb start jupyterlab

You should see output similar to the following.

1✅  Container is running
2✅  jupyterlab is running
3
4App successfully started and available at:
5http://localhost:10000/projects/test-1/applications/jupyterlab/?token=<token>

To start the project container, but not start any apps, run the following code.

1nvwb start --container

status#

Synopsis#

1nvwb status [options]

Description#

Get the status of the currently open project, or a specified project. Information includes the name, path, description, and status of the environment, container, apps, and Git repository. For more information, see AI Workbench Projects.

Options#

This command accepts relevant global options.

Examples#

To get the status of a project, run the following code.

1nvwb status

You should see output similar to the following.

1• Name: hello-world (/home/workbench/nvidia-workbench/hello-world)
2• Description: Test project
3• Environment: 🟢 No Build Required
4• Container: ⚫ Stopped
5• Applications:
6  • jupyterlab: ⚫ Stopped
7• Local Repository: 1 🟡 Modified
8  • Current Branch: main

stop#

Synopsis#

1nvwb stop [app_name] [options]

Description#

Stop an application running in the currently open project, or a specified project. For more information, see AI Workbench Applications.

If you don’t specify an app name, an interactive prompt appears, and you can type and use the arrow keys to make your selections.

If you don’t specify an app name, and you use the --container option, all apps and the container are stopped.

After a specified app stops, if no other apps are running, the container is also stopped. If other apps are still running, the container continues running. To force the container to stop, even if other apps are still running, use the --container option.

Tip

Use status to see the running apps before you run stop.

Options#

This command accepts relevant global options, and the following additional options.

Option

Description

Type

Default Value

Valid Values

--container

After stopping any apps, also stop the project container.

—

—

—

Examples#

To stop a specific app, for example JupyterLab run the following code.

1nvwb stop jupyterlab

To stop all apps and the container, run the following code.

1nvwb stop --container

support create-bundle#

Synopsis#

1nvwb support create-bundle [archive_name.zip] [options]

Description#

Create a zip file that contains log files, configuration information, and system state for your AI Workbench installation. For more information, see Create a Support Bundle for Troubleshooting.

If you don’t specify a name for the zip file, the default file name is ~/.nvwb/ai-workbench-support-bundle.zip.

Options#

This command accepts relevant global options.

Examples#

To create a support bundle, run the following code.

1nvwb support create-bundle

You should see output similar to the following.

1Support bundle created at '/home/workbench/.nvwb/ai-workbench-support-bundle.zip'

To create a support bundle for a different context (location), run the following code.

1nvwb support create-bundle --context <context name>

switch-branch#

Synopsis#

1nvwb switch-branch [branch-name] [options]

Description#

Switch to the specified branch in the currently open project, or a specified project. For more information, see Git in AI Workbench.

branch-name is the name of an existing branch to switch to. To create a new branch, see create branch.

If you don’t specify a branch name, an interactive prompt appears, and you can type and use the arrow keys to make your selections.

Tip

Use list branches to see the existing branches before you run switch-branch.

Options#

This command accepts relevant global options.

Examples#

To switch to an existing branch named feature-1, run the following code.

1nvwb switch-branch feature-1

You should see output similar to the following.

1Current Branch Details:
2
3Name: feature-1 Branch Type: LOCAL

uninstall#

Synopsis#

1nvwb uninstall [options]

Description#

Uninstall AI Workbench and managed dependencies from the computer. After the uninstall completes, a message appears that indicates if there are any additional steps to perform. For more information, see Install, Update, and Uninstall AI Workbench.

You must run this command with admin privileges.

If you run this command as root to uninstall AI Workbench for another user, you must specify the --uid and --gid options.

Options#

This command accepts relevant global options, and the following additional options.

Option

Description

Type

Default Value

Valid Values

--confirm

Run the command without prompting for confirmation.

—

—

—

--gid

The group ID of the AI Workbench user. Required when you uninstall AI Workbench for another user.

Integer

20

—

--uid

The user ID of the AI Workbench user. Required when you uninstall AI Workbench for another user.

Integer

502

—

Examples#

To uninstall AI Workbench on macOS or Linux, run the following code.

1sudo -E $HOME/.nvwb/bin/nvwb-cli uninstall

To uninstall AI Workbench on Windows, run the following code in Powershell or Terminal.

1wsl -d NVIDIA-Workbench -u root -- /home/workbench/.nvwb/bin/nvwb-cli uninstall --uid 1000 --gid 1000

update base#

Synopsis#

1nvwb update base [options]

Description#

Update the base environment of the currently open project, or a specified project to the latest version. For more information, see Container Environments for AI Workbench Projects.

Options#

This command accepts relevant global options, and the following additional options.

Option

Description

Type

Default Value

Valid Values

--yes, -y

Accept the update without prompting.

—

—

—

Examples#

To update the base of the open project, run the following code.

1nvwb update base

If your project base is already current, you should see output similar to the following.

1Project base environment is already at the latest tag.

update context#

Synopsis#

1nvwb update context [context_name] [options]

Description#

Update a context (location). For more information, see AI Workbench Locations.

Warning

You can’t run this command while the context is active. Use deactivate with the --shutdown option to ensure the context is stopped before you run this command.

context_name is the name of the context to update. You can’t update the name of a context. For the local context, you can only update the description.

If you don’t specify a required option, an interactive prompt appears, and you can type and use the arrow keys to make your selections.

Tip

Use list contexts to see the existing contexts before you run update context.

Options#

This command accepts relevant global options, and the following additional options.

Option

Description

Type

Default Value

Valid Values

--accept-ssh-fingerprints

Accept the SSH fingerprints for the context (location).

—

—

—

--context-workbench-dir

The internal workbench directory where the workbench service stores configuration and internal data. For most installations this is /home/<username>/.nvwb, which is the default directory.

String

—

—

--description, -d

A description for the context (location).

String

—

—

--hostname

The hostname or IP address for the context (location). You can’t change a remote context to a local context by setting the hostname to localhost. You can’t change a local context to a remote context by setting the hostname to something other than localhost.

String

—

—

--proxy-port

The port for the traffic proxy. The port can’t be assigned to an existing context.

Integer

—

1024 or greater

--service-port

The port for the workbench service proxy. The port can’t be assigned to an existing context.

Integer

—

1024 or greater

--ssh-key-path

The path to the SSH key to use when you connect to this context (location). For keys held by ssh-agent, provide the matching public key.

String

—

—

--ssh-port

The target SSH port to use when you connect to this context (location). The port can’t be assigned to an existing context.

Integer

22

—

--ssh-username

The username to use when you connect to this context (location).

String

—

—

Examples#

To update the description of the local context, run the following code.

1nvwb update context local --description "My Computer Work Laptop"

You should see output similar to the following.

 1• Name: local
 2• Description: My Computer Work Laptop
 3• Hostname: localhost
 4• Workbench Directory: /home/workbench/.nvwb
 5• SSH Key Path:
 6• SSH Username:
 7• SSH Port:
 8• SSH Fingerprint:
 9• Proxy Port: 10000
10• Service Port: 10001

update integration#

Synopsis#

1nvwb update integration [options]

Description#

Update an integration, such as GitHub or GitLab. For more information, see AI Workbench Integrations.

When you run this command, an interactive prompt appears, and you can type and use the arrow keys to make your selections. If you want to update an integration without using the interactive interface, edit the JSON configuration file for the integration at ~/.nvwb/ or C:\Users\<username>\AppData\Local\NVIDIA Corporation\AI Workbench\.

Tip

Use list integrations to see the existing integrations before you run update integration.

Options#

This command accepts relevant global options.

Examples#

To update an integration, run the following code.

1nvwb update integration

An interactive prompt appears. When you are done updating the integration, you should see output similar to the following.

1     NAME  |  DESCRIPTION   |       CREDENTIALS       | CONNECTED
2-----------|----------------|-------------------------|-----------
3  NGC      | ngc.nvidia.com | container-registry      | false
4  Github   | Github.com     | git, container-registry | true
5  Gitlab   | Gitlab.com     | git                     | false

update resources#

Synopsis#

1nvwb update resources [resource-type1:value1] [resource-type2:value2] [options]

Description#

Update the hardware resources that are requested by the currently open project, or a specified project. For more information, see Hardware.

Warning

You can’t run this command while the project container is running. Use status and stop to ensure the project container is stopped before you run this command.

Specify resource-type:value, where resource-type is the type of resource requested and value is the new value requested for the resource. Valid values for resource-type are gpus and shared-memory. You can specify more than one resource-type:value separated by spaces.

If you don’t specify resource-type:value, an interactive prompt appears, and you can type and use the arrow keys to make your selections.

Tip

Use list resources to see the existing resource requests before you run update resources.

Options#

This command accepts relevant global options.

Examples#

To request 2 GPUs for your project, run the following code.

1nvwb update resources gpus:2

You should see output similar to the following.

1Project resources updated
2
3GPUs Requesed: 2
4
5Shared Memory in MB: 0

update script#

Synopsis#

1nvwb update script [script-name] [options]

Description#

Edit a build script for the currently open project, or a specified project. For more information, see Scripts.

script-name is one of preBuild.bash, preLanguage.bash, or postBuild.bash.

If you don’t specify script-name, an interactive prompt appears, and you can type and use the arrow keys to make your selections.

Options#

This command accepts relevant global options.

Examples#

To edit the pre-build script for your project, run the following code.

1nvwb update script preBuild.bash

The editor opens and you can make changes to the file, and then save and close the file.

You should see output similar to the following.

1Successfully edited preBuild.bash

version#

Synopsis#

1nvwb version [options]

Description#

Return the version of the AI Workbench CLI installed on the computer. For more information, see Release Notes.

Options#

This command accepts relevant global options.

Examples#

To get the version of the AI Workbench CLI installed on the computer, run the following code.

1nvwb version --output json

You should see output similar to the following.

 1{
 2   "result": {
 3   "CLIVersion": "0.29.2",
 4   "Channel": "stable",
 5   "BuildTime": "Thu Aug 15 00:27:32 UTC 2024",
 6   "OS": "linux",
 7   "Arch": "amd64",
 8   "GolangVersion": "go1.21.11"
 9   }
10}
On this page