AI Workbench Command Line Interface (CLI) Reference

Overview

Run nvwb <command> --help for the full syntax and flags of any command.

The built-in help is the authoritative reference for command syntax, required arguments and available options. This page covers what --help cannot: how commands are organized, behavioral notes, output formats and internal commands.

The CLI provides the same capabilities as the Desktop App.

You can manage locations, projects, environments, applications and git operations from a terminal. See Using the CLI for how-to guides on interactive use, scripting and agent integration.

The nvwb command is a shell wrapper around the nvwb-cli binary.

The binary lives at ~/.nvwb/bin/nvwb-cli. The wrapper is a bash function defined in ~/.local/share/nvwb/nvwb-wrapper.sh and sourced into your shell through .bashrc. It handles four session-state commands (activate, deactivate, open, close) by eval-ing the binary’s output to set environment variables in your live shell. All other commands pass straight through to the binary.

Scripts and agents should call the binary directly.

The shell wrapper is only available in interactive shells that have sourced .bashrc. Call ~/.nvwb/bin/nvwb-cli directly in scripts and agent tools. See Using the CLI Binary for Scripts and Agents for the full calling convention.

Command Index

Use nvwb <command> --help for full syntax and options.

The tables below organize every command by category.

Context Management

Command	Description
activate	Activate a context (location) for the current shell session. Starts the AI Workbench service if not running.
deactivate	Deactivate the current context. Optionally shut down the service with `--shutdown`.

Project Workflow

Command	Description
open	Open a project in the current shell session. Accepts a project name, absolute path, or `.` for the current directory.
close	Close the currently open project. Use `--force` to stop running apps first.
status	Show project state: build state, run state, applications, git info and warnings.
build	Build the project container. Use `--full-build` to force a complete rebuild or `--stop` to cancel.
start	Start an application (and the container if not running). Use `--container` to start only the container.
stop	Stop an application. Use `--container` to stop the container even if other apps are running.
attach	Open an interactive shell in the running project container. Use `--host` for the host machine instead.

Git Operations

Command	Description
clone project	Clone a git repository and manage it as an AI Workbench project.
publish	Publish a project to a remote git server for the first time.
pull	Pull latest commits from the remote. Use `--reset-to-remote` to hard reset to remote.
push	Push local commits to the remote repository.
fetch	Fetch changes from the remote without merging.
commit	Stage all changes and create a commit. Use `-m` for non-interactive mode, `--undo` to undo the last commit.
history	List commit history. Use `-n` to limit the number of commits.
discard	Discard uncommitted and untracked changes. Optionally specify individual files.
merge	Merge commits from a branch into the current branch. Supports `remote/branch` syntax.
switch-branch	Switch to a different git branch.
create branch	Create and switch to a new branch. Use `--carry` to bring uncommitted changes.
delete branch	Delete a local branch. Use `--force` for unmerged branches.
list branches	List all git branches in the project repository.

Compose (Docker / Podman)

Compose commands require Docker.

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

Command	Description
compose up	Start compose services. Use `--profile` to activate specific profiles.
compose down	Stop compose services.
compose status	Show status of compose services.
compose logs	Show combined log output from compose services.

Listing Resources

Command	Description
list projects	List all projects in the current or specified context.
list contexts	List configured contexts and their running status.
list bases	List available base environments from NGC. Use `-o json` to get IDs for scripting.
list integrations	List configured third-party integrations.
list mounts	List mounts defined for the current project.
list resources	List host resources (GPUs, shared memory) requested by the project.
list environment-variables	List environment variables for the current project.
list apps	List applications defined in the current project.
list built-in-apps	List all supported built-in application types.
list packages	List packages per package manager. Use `-m` to filter by package manager.
list secrets	List secret variables for the current project.
list branches	List all git branches in the project repository.
list brev instances	List all Brev compute instances.
list brev orgs	List all Brev organizations.

Creating Resources

Command	Description
create project	Create a new project. Requires `--base-environment-id` or `--base-url`.
create context	Create a new context (location). Use `localhost` for local, or provide a hostname and SSH options for remote.
create integration	Add a third-party integration. Interactive only via CLI.
create mount	Define a new mount. Types: `PROJECT`, `HOST`, `VOLUME`, `TMP`.
create environment-variable	Create an environment variable. Pass `-` as the value to read from stdin. Use `--is-sensitive` to mask the value.
create secret	Create a secret variable. Use `configure secrets` to set its value.
create app	Add an application to the project. Use a built-in type or `custom` with `--app-class`.
create share-url	Create a shareable URL for a running web app. Valid for 48 hours.
create branch	Create and switch to a new branch.

Updating Resources

Command	Description
update integration	Update an existing integration. Interactive only via CLI.
update resources	Update GPU and shared memory allocations for the project.
update context	Update settings for an existing context. Context must not be running.
update base	Update the project’s base environment to the latest available tag.
update environment-variable	Update the value of an existing environment variable. Pass `-` to read from stdin.
update script	Open a build script in an editor (deprecated; use `edit script` instead).

Deleting Resources

Command	Description
delete project	Delete a project locally. Does not remove the remote git repository.
delete context	Delete a context configuration.
delete integration	Remove a configured integration.
delete mount	Remove a mount definition. Volume data is deleted with the mount.
delete environment-variable	Delete an environment variable.
delete secret	Delete a secret variable.
delete app	Delete an application from the project.
delete branch	Delete a local git branch.

Configuring Resources

Command	Description
configure mounts	Map host directories to mount targets for the current context.
configure secrets	Set values for existing secret variables.
configure brev org	Set the active Brev organization.

Package Management

Command	Description
add package	Add packages to the project. Installs immediately if the container is running.
remove package	Remove packages from the project.

Editing Files

Command	Description
edit script	Open a project environment script (`preBuild.bash`, `preLanguage.bash`, `postBuild.bash`, or `onStart.bash`) in an editor.
edit file	Open a project file for editing. Use `--vs-code`, `--cursor`, or `--gui` to choose an editor.

Validation

Command	Description
validate project-spec	Validate the project spec file (`.project/spec.yaml`).

Integrations

Command	Description
connect integration	Authorize AI Workbench to call an integration on your behalf. Supports OAuth2, token, or stdin.
disconnect integration	Revoke authorization for an integration.

Installation

Command	Description
install	Install AI Workbench and dependencies. Run with `sudo -E`.
uninstall	Uninstall AI Workbench and managed dependencies. Run with `sudo`.

Support and Diagnostics

Command	Description
version	Print CLI and service version information.
support create-bundle	Create a zip archive of logs, configs and version info for debugging.

Shell Completion

Command	Description
completion	Generate shell autocompletion scripts for bash, zsh, fish or powershell.

Global Options

These options are available on every command.

Option	Description	Type	Default
`-c`, `--context`	Override the active context for this command. The context must already be running (this flag does not start the service). Required for scripting when you have not run `activate`.	String	—
`-p`, `--project`	Override the open project for this command. Must be an absolute path. Always use the path, not the project name, for scripting (see Use the Project Path, Not the Name).	String	—
`-o`, `--output`	Output format. `default` produces a styled table if the terminal has TTY support. `json` returns structured JSON. `jsonl` returns JSON Lines. See Output Formats.	String	`default`
`--debug`	Enable debug logging.	—	—
`--workbench-dir`	Path to the AI Workbench internal data directory.	String	`~/.nvwb`

Output Formats

The CLI does not change its output format when piped.

TTY and non-TTY output are identical — same table format and styling regardless. Use -o json for any command whose output you want to parse.

JSON responses follow one of four shapes.

{"result": [...]} — List and query commands. Access items with .result[] in jq.

{"result": {...}} — Singular commands like status. Access fields with .result.FieldName.

{"messages": [...]} — create project and clone project on success. The project path is embedded in the message string, not a dedicated field.

{"error": "...", "detail": "..."} — All failures, all commands. Exit code 1.

Exit codes are meaningful.

Exit code 0 means success. Exit code 1 means error.

`-o jsonl` is not streaming.

`-o jsonl` outputs a single minified line containing all records.
It is not one-record-per-line streaming.

Behavioral Notes

This section covers behaviors that --help does not explain.

Use the Project Path, Not the Name

The registered project name comes from spec.yaml inside the repository, not from the directory name.

Cloning a project into --projectPath .../my-dir may register it under a completely different name. Always use absolute paths with -p for scripting. The name is for display; the path is stable and unambiguous.

Project State Machine

Many commands fail if the project is in the wrong state.

Check status -o json before running commands that have preconditions.

Build states (result.Environment.BuildState):

NO_BUILD — Build has never run or was reset.

BUILDING — Build is in progress.

BUILD_COMPLETE — Built and the project container is available.

BUILD_ERROR — Last build failed.

Run states (result.Environment.RunState):

CONTAINER_NOT_CREATED — The project container does not exist.

RUNNING — The project container is running.

STOPPED — The project container exists but is stopped.

Preconditions by operation:

Operation	Required State
`build`	Any build state (re-runs if already built)
`start <app>`	Build state must be `BUILD_COMPLETE`. All sensitive environment variables must be configured.
`stop <app>`	Run state must be `RUNNING`
`add/remove` environment variables, mounts, secrets	Run state must be `CONTAINER_NOT_CREATED` or `STOPPED`
`delete project`	Run state must be `CONTAINER_NOT_CREATED` or `STOPPED`

Useful Status Fields

The status -o json command returns detailed project information.

result.Path                           Absolute path (use with -p)
result.Name                           Registered name (from spec.yaml)
result.Environment.BuildState         See build states above
result.Environment.RunState           See run states above
result.ContainerName                  Container runtime name
result.Applications[].name            Application name for start/stop
result.Applications[].info.runState   NOT_RUNNING or RUNNING
result.Applications[].info.url        null when stopped, URL when running
result.RepoState.CommitsAhead         Integer
result.RepoState.CommitsBehind        Integer
result.CurrentGitBranch.Name          Current branch name
result.Resources.GPUsRequested        Integer

Session State Commands

The activate, deactivate, open and close commands manage shell session state.

They use eval to set environment variables in your live shell session. After you activate a context, (nvwb:<context>) appears in your prompt and all subsequent commands target that context. After you open a project, commands like build and start target that project.

These commands are only meaningful in an interactive terminal.

In scripts and agent tools, each command runs in its own process with no shared session. Use -c and -p instead. See Using the CLI Binary for Scripts and Agents for the scripting calling convention.

Stdin Value Ingestion

Some commands accept - as a value to read from stdin.

create environment-variable <name> - — reads the value from stdin

update environment-variable <name> - — reads the value from stdin

connect integration <name> - — reads the token from stdin
# Set a secret from a vault or environment variable
echo "$SECRET_VALUE" | nvwb create environment-variable API_KEY - --is-sensitive

Compose Notes

Compose commands require Docker as the container runtime.

They are not supported with Podman.

Compose file search order (relative to project root):

compose.yaml, compose.yml, docker-compose.yml, docker-compose.yaml, deploy/compose.yaml, deploy/compose.yml, deploy/docker-compose.yml, deploy/docker-compose.yaml

Shell Completion

Generate autocompletion scripts with nvwb completion <shell>.

Supported shells: bash, zsh, fish, powershell. All variants support --no-descriptions to omit completion descriptions.

# Bash — load for current session
source <(nvwb completion bash)
# Bash — load permanently (Linux)
nvwb completion bash > /etc/bash_completion.d/nvwb
# Zsh — load for current session
source <(nvwb completion zsh)
# Fish — load permanently
nvwb completion fish > ~/.config/fish/completions/nvwb.fish

Internal Commands

These commands are intended for power users, tooling integrations and the Desktop App GUI.

They are not shown in the main --help output. Run nvwb internal <subcommand> --help for syntax and options.

Build Assistant

The build assistant analyzes failed container builds and proposes fixes using an AI inference backend.

See How to Use the AI Workbench Build Assistant for the full how-to guide.

Command	Description
`nvwb internal build-assistant config`	View or update build assistant configuration (`--enabled`, `--base-url`, `--model`).
`nvwb internal build-assistant start`	Start the build assistant to analyze a failed build. Streams status until `SUCCEEDED`, `FAILED` or `STOPPED`.
`nvwb internal build-assistant stop`	Stop a running build assistant session.
`nvwb internal build-assistant status`	Show current build assistant status for the project.
`nvwb internal build-assistant gate`	Check whether unacknowledged changes block `nvwb build`.
`nvwb internal build-assistant acknowledge`	Acknowledge changes made by the build assistant, clearing the build gate.
`nvwb internal build-assistant models`	List available inference models.

Context Lifecycle

Command	Description
`nvwb internal ensure-context-ready <context>`	Start the AI Workbench service and container runtime for a context if not already running. Used internally by `activate`.
`nvwb internal shutdown-context <context>`	Stop the AI Workbench service and container runtime for a context.
`nvwb internal open-tunnels <context>`	Open and maintain SSH tunnels for a remote context.

Container Lifecycle

Command	Description
`nvwb internal start-container`	Start the project container directly (lower-level than `nvwb start`).
`nvwb internal stop-container`	Stop the project container directly.

Git Author Configuration

Command	Description
`nvwb internal get-git-author-config`	Get the global git author name and email.
`nvwb internal set-git-author-config`	Set the global git author name and email. Also syncs to running remote contexts. Use `--name`/`--email` or `--auto-set`.

Shell and UI Helpers

Command	Description
`nvwb internal install-hook <username> <uid> <gid>`	Install the shell hook that enables `activate`/`deactivate` to modify the current shell session.
`nvwb internal select-project-helper`	Interactively prompt to select a project. Used internally by `nvwb open`.
`nvwb internal verify-credential <type> <subtype> <url>`	Verify a credential before use. Pushes refreshed credentials to active contexts.

System and Migration

Command	Description
`nvwb internal init-ca`	Assemble host-trusted CA certificates into a bundle in the AI Workbench directory.
`nvwb internal migrate-ssh-keys`	Migrate SSH keys from symlink to copy-on-create (Windows/WSL only).
`nvwb internal migrate-config`	Migrate CLI config files from Windows to WSL.

Reference Labels

The following labels are preserved for cross-reference compatibility.

They point to the relevant section in this page or to the command index above. Run nvwb <command> --help for complete syntax.

Using the CLI - How to use the CLI (interactive, scripting, agents)
Basic Quickstart (CLI) - CLI quickstart tutorial
Release Notes - CLI version history

Overview

Command Index

Context Management

Project Workflow

Git Operations

Compose (Docker / Podman)

Listing Resources

Creating Resources

Updating Resources

Deleting Resources

Configuring Resources

Package Management

Editing Files

Validation

Integrations

Installation

Support and Diagnostics

Shell Completion

Global Options

Output Formats

Behavioral Notes

Use the Project Path, Not the Name

Project State Machine

Useful Status Fields

Session State Commands

Stdin Value Ingestion

Compose Notes

Shell Completion

Internal Commands

Build Assistant

Context Lifecycle

Container Lifecycle

Git Author Configuration

Shell and UI Helpers

System and Migration

Reference Labels

Related Topics