> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/ai-workbench/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/ai-workbench/_mcp/server.

> Reference documentation for the AI Workbench CLI. Command index,

# 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](/ai-workbench/how-to/cli/cli-overview) 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.

<Note title="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](/ai-workbench/how-to/cli/cli-scripting) for the full calling convention.

</Note>

## Command Index

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

The tables below organize every command by category.

### Context Management

| **Command** | **Description** |
|---|---|
| [activate](/ai-workbench/reference/user-interface/cli#context-management) | Activate a context (location) for the current shell session. Starts the AI Workbench service if not running. |
| [deactivate](/ai-workbench/reference/user-interface/cli#context-management) | Deactivate the current context. Optionally shut down the service with `--shutdown`. |

### Project Workflow

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

### Git Operations

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

### Compose (Docker / Podman)

<Note title="Compose commands require Docker.">

The `compose` commands are only supported if you are using Docker, not Podman, as your [container runtime](/ai-workbench/reference/workbench-application/runtimes).

</Note>

| **Command** | **Description** |
|---|---|
| [compose up](/ai-workbench/reference/user-interface/cli#compose-docker--podman) | Start compose services. Use `--profile` to activate specific profiles. |
| [compose down](/ai-workbench/reference/user-interface/cli#compose-docker--podman) | Stop compose services. |
| [compose status](/ai-workbench/reference/user-interface/cli#compose-docker--podman) | Show status of compose services. |
| [compose logs](/ai-workbench/reference/user-interface/cli#compose-docker--podman) | Show combined log output from compose services. |

### Listing Resources

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

### Creating Resources

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

### Updating Resources

| **Command** | **Description** |
|---|---|
| [update integration](/ai-workbench/reference/user-interface/cli#updating-resources) | Update an existing integration. Interactive only via CLI. |
| [update resources](/ai-workbench/reference/user-interface/cli#updating-resources) | Update GPU and shared memory allocations for the project. |
| [update context](/ai-workbench/reference/user-interface/cli#updating-resources) | Update settings for an existing context. Context must not be running. |
| [update base](/ai-workbench/reference/user-interface/cli#updating-resources) | Update the project's base environment to the latest available tag. |
| [update environment-variable](/ai-workbench/reference/user-interface/cli#updating-resources) | Update the value of an existing environment variable. Pass `-` to read from stdin. |
| [update script](/ai-workbench/reference/user-interface/cli#updating-resources) | Open a build script in an editor (deprecated; use `edit script` instead). |

### Deleting Resources

| **Command** | **Description** |
|---|---|
| [delete project](/ai-workbench/reference/user-interface/cli#deleting-resources) | Delete a project locally. Does not remove the remote git repository. |
| [delete context](/ai-workbench/reference/user-interface/cli#deleting-resources) | Delete a context configuration. |
| [delete integration](/ai-workbench/reference/user-interface/cli#deleting-resources) | Remove a configured integration. |
| [delete mount](/ai-workbench/reference/user-interface/cli#deleting-resources) | Remove a mount definition. Volume data is deleted with the mount. |
| [delete environment-variable](/ai-workbench/reference/user-interface/cli#deleting-resources) | Delete an environment variable. |
| [delete secret](/ai-workbench/reference/user-interface/cli#deleting-resources) | Delete a secret variable. |
| [delete app](/ai-workbench/reference/user-interface/cli#deleting-resources) | Delete an application from the project. |
| [delete branch](/ai-workbench/reference/user-interface/cli#deleting-resources) | Delete a local git branch. |

### Configuring Resources

| **Command** | **Description** |
|---|---|
| [configure mounts](/ai-workbench/reference/user-interface/cli#configuring-resources) | Map host directories to mount targets for the current context. |
| [configure secrets](/ai-workbench/reference/user-interface/cli#configuring-resources) | Set values for existing secret variables. |
| [configure brev org](/ai-workbench/reference/user-interface/cli#configuring-resources) | Set the active Brev organization. |

### Package Management

| **Command** | **Description** |
|---|---|
| [add package](/ai-workbench/reference/user-interface/cli#package-management) | Add packages to the project. Installs immediately if the container is running. |
| [remove package](/ai-workbench/reference/user-interface/cli#package-management) | Remove packages from the project. |

### Editing Files

| **Command** | **Description** |
|---|---|
| [edit script](/ai-workbench/reference/user-interface/cli#editing-files) | Open a project environment script (`preBuild.bash`, `preLanguage.bash`, `postBuild.bash`, or `onStart.bash`) in an editor. |
| [edit file](/ai-workbench/reference/user-interface/cli#editing-files) | Open a project file for editing. Use `--vs-code`, `--cursor`, or `--gui` to choose an editor. |

### Validation

| **Command** | **Description** |
|---|---|
| [validate project-spec](/ai-workbench/reference/user-interface/cli#validation) | Validate the project spec file (`.project/spec.yaml`). |

### Integrations

| **Command** | **Description** |
|---|---|
| [connect integration](/ai-workbench/reference/user-interface/cli#integrations) | Authorize AI Workbench to call an integration on your behalf. Supports OAuth2, token, or stdin. |
| [disconnect integration](/ai-workbench/reference/user-interface/cli#integrations) | Revoke authorization for an integration. |

### Installation

| **Command** | **Description** |
|---|---|
| [install](/ai-workbench/reference/user-interface/cli#installation) | Install AI Workbench and dependencies. Run with `sudo -E`. |
| [uninstall](/ai-workbench/reference/user-interface/cli#installation) | Uninstall AI Workbench and managed dependencies. Run with `sudo`. |

### Support and Diagnostics

| **Command** | **Description** |
|---|---|
| [version](/ai-workbench/reference/user-interface/cli#support-and-diagnostics) | Print CLI and service version information. |
| [support create-bundle](/ai-workbench/reference/user-interface/cli#support-and-diagnostics) | Create a zip archive of logs, configs and version info for debugging. |

### Shell Completion

| **Command** | **Description** |
|---|---|
| [completion](/ai-workbench/reference/user-interface/cli#shell-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](/ai-workbench/reference/user-interface/cli#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](/ai-workbench/reference/user-interface/cli#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.`**

~~~\{admonition\} `-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](/ai-workbench/how-to/cli/cli-scripting) 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
>
> ```bash
> # 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
# 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](/ai-workbench/how-to/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.

## Related Topics

- [Using the CLI](/ai-workbench/how-to/cli/cli-overview) - How to use the CLI (interactive, scripting, agents)
- [Basic Quickstart (CLI)](/ai-workbench/quickstart/quickstart-cli) - CLI quickstart tutorial
- [Release Notes](/ai-workbench/release-notes) - CLI version history