Skip to navigation
How To GuidesCLI

Interactive CLI Use

View as Markdown

Overview

Interactive use is done with nvwb and follows the activate/open model.

You activate a location, open a project, run commands, close that project and switch to another or deactivate the location when you are done.

This is the same workflow as the Desktop App, just in a terminal.

One terminal binds to one location and one project at a time.

Run nvwb activate <location> to attach a terminal to a location. Run nvwb open <project-name> to attach the terminal to a project within that location. All subsequent commands target that location and project until you change them.

To work on multiple projects, just use multiple terminals.

Each terminal maintains its own session state. Open a second terminal, activate the same or a different location, and open a different project.

Key Concepts

Activate / Deactivate

Binds or unbinds a terminal to a location. When a location is active, (nvwb:<location>) appears in your prompt.

Open / Close

Binds or unbinds a terminal to a project within the active location. When a project is open, commands like build, start and status target that project.

Start a Location and Open a Project

Step One: List available locations.

  1. Run the following command:

    nvwb list contexts

  2. Verify the location you want to use appears in the list

Step Two: Activate the location.

  1. Run the following command, replacing <location> with the location name:

    nvwb activate <location>

  2. Verify that (nvwb:<location>) appears in your prompt

Step Three: Open a project.

  1. List available projects:

    nvwb list projects

  2. Open the project by name or path:

    nvwb open <project-name>

    If you are already in the project directory, use . instead:

    nvwb open .

Success: Your terminal is now bound to a location and project. Commands like status, build and start target that project.

Check Project Status

Run status to see the current state of the open project.

nvwb status

The output shows the build state, run state, applications and git status.

Build and Start an Application

Step One: Build the project container.

  1. Run the following command:

    nvwb build

  2. Wait for the build to complete

To force a complete rebuild from scratch, use --full-build:

nvwb build --full-build

Step Two: Start an application.

  1. List available applications:

    nvwb list apps

  2. Start the application by name:

    nvwb start <app-name>

To prevent the browser from opening automatically, use --no-browser:

nvwb start <app-name> --no-browser

To start the project container without starting any application, use --container:

nvwb start --container

Success: The application is running and accessible at the URL shown in the output.

Attach a Shell to the Container

Use attach to open an interactive shell inside the running project container.

nvwb attach

To attach to the host machine running the AI Workbench service instead, use --host:

nvwb attach --host

Manage Packages

You can add and remove packages through the CLI.

Package changes modify the project configuration files and take effect on the next build.

# Add a pip package
nvwb add package pip numpy
# Remove a pip package
nvwb remove package pip numpy
# List installed packages
nvwb list packages

Manage Environment Variables

Set environment variables that the project container uses at runtime.

# Create a standard environment variable
nvwb create environment-variable MY_VAR "my-value"
# List all environment variables
nvwb list environment-variables
# Delete an environment variable
nvwb delete environment-variable MY_VAR

Set sensitive environment variable.

# Create a sensitive environment variable
nvwb create environment-variable MY_VAR "my-value" --is-sensitive
Environment variable changes require a container restart and sensitive variables cannot be mutated.

If the container is running, stop it first with nvwb stop <app-name> or by stopping all applications.

If a new value is needed for a sensitive environment variable, it can be deleted and created again.

Version Control

The CLI provides git operations without leaving the terminal.

# Commit all changes with a message
nvwb commit -m "update training script"
# Push to the remote
nvwb push
# Pull latest changes from the remote
nvwb pull
# View commit history
nvwb history
# Discard all uncommitted changes
nvwb discard
# Create and switch to a new branch, carrying uncommitted changes
nvwb create branch my-feature --carry
# Switch to an existing branch
nvwb switch-branch main
Connect a git integration before using git commands.

Run nvwb connect integration Github (or Gitlab) before using commands that interact with a remote repository. See Integrations and Credentials for details.

Edit Environment Scripts and Project Files

Open environment scripts directly from the CLI.

# Open preBuild.bash in the default editor
nvwb edit script preBuild.bash
# Open onStart.bash in the default editor
nvwb edit script onStart.bash

Available scripts: preBuild.bash, postBuild.bash, and onStart.bash. The first three scripts run during the container build; onStart.bash runs each time the project container starts.

Open any project file for editing.

# Open in the default terminal editor
nvwb edit file code/train.py
# Open in VS Code
nvwb edit file code/train.py --vs-code
# Open in Cursor
nvwb edit file code/train.py --cursor

Close and Deactivate

When you are done, close the project and deactivate the location.

# Close the open project
nvwb close
# Force close (stops running apps and container first)
nvwb close --force
# Deactivate the location
nvwb deactivate
# Deactivate and shut down the AI Workbench service
nvwb deactivate --shutdown