HoloHub CLI Reference Guide

September 3, 2026 · View on GitHub

⚠️ Wrapper reference. This file documents HoloHub's ./holohub wrapper usage around the standalone holoscan-cli package. For the accepted command syntax, run ./holohub --help or ./holohub <command> --help; use ./holohub env-info to inspect the effective runtime environment. The implementation lives in the holoscan-cli repository.

Quick reference for the HoloHub CLI (./holohub). For a high-level overview see the README. For implementation details and extension guide see the CLI Developer Guide.

Quick Start

Run the CLI from the repository root:

./holohub <command> [options] [arguments]

Getting help:

./holohub --help                         # List all commands
./holohub <command> --help               # Options for a specific command
./holohub run myapp --verbose --dryrun   # Debug: print without executing
./holohub list                           # List available projects

Conventions used in this guide:

<arg> means a required positional argument.
[arg] means an optional positional argument.
[options] means one or more optional flags.
-- marks the end of CLI options; anything after it is executed as a command inside the container (supported by run-container).

Command Index

Command	Description
create	Create an application or external module from a template
build-container	Build the development container image
run-container	Build and launch the development container
build	Build a project (container or local)
run	Build and run a project (container or local)
list	List all available targets (applications, operators, and so on)
modes	List available modes for an application
lint	Run linting tools
setup	Install HoloHub recommended packages for development
status	Show environment, container, and build status
env-info	Display environment debugging information
env-check	Run system health checks (GPU, CUDA, Docker, SDK, disk, display, devices)
install	Install a built project
package	Build Holoscan Module distribution artifacts
test	Run tests for a project
clear-cache	Clear cache folders (build, data, install)
version	Display the installed holoscan-cli package version
autocompletion_list	List targets for autocompletion (used internally)

Shared Options

Many commands inherit container build and/or container run options. They are listed here once; see each command section for applicability.

Preview Support

Preview mutating commands with the flags they actually support:

Commands	Preview flags
`build`, `run`, `build-container`, `run-container`, `install`, `test`, `package`	`--dryrun --verbose`
`create`, `lint`, `setup`, `clear-cache`	`--dryrun`
`list`, `modes`, `env-info`, `env-check`, `status`, `version`	Read-only; no preview flags

JSON Output

These read-only commands accept --json and print a machine-readable document instead of the prose rendering:

Command	Top-level fields (schematic)	Description
`list`	`schema_version`; `projects[]`: `name`, `project_type`, `source_folder`, `language[]`, `modes[]`	Discovered project inventory, including source locations and supported languages and modes.
`modes`	`schema_version`, `project`, `language[]`, and the resolved `modes{}` object	Mode definitions for one selected project and language implementation.
`env-info`	`schema_version`, `cli`, `system`, `python`, `source_project`, `git`, `docker`, `cuda_gpu`, `sccache`, `environment_variables`	Host, tool, source-project, and configured-environment details for diagnostics.
`env-check`	`schema_version`, `elapsed_seconds`, `checks[]`, `summary`	Environment check results, timing, and aggregate pass, warning, failure, and skip counts.
`status`	`schema_version`, `platform`, `git`, `images[]`, `builds[]`, `build_folders[]`, `data_folders[]`	Repository, container-image, build, and data status for the current source project.
`version`	`schema_version`, `package`, `version`, `executable`, `module`	Installed package version and the Python executable and module selected by the wrapper.

--json replaces the prose output rather than supplementing it, so the document can be piped straight into a parser. list --json also reports source_folder, which locates a project on disk and is not available in the prose listing. Every payload currently reports schema_version as 1; fields may be added within schema version 1, but existing fields are not removed or renamed.

Container Build Options

Used by: build-container, run-container, build, run, install, test, and package.

Option	Description
`--base-img`	Fully qualified base image name for the container build
`--docker-file`	Path to Dockerfile to use
`--img`	Fully qualified output container image name
`--no-cache`	Do not use cache when building the image
`--cuda <version>`	Override the CUDA major version (for example `12`, `13`). If omitted, select it from the driver, falling back to `13` when detection is unavailable.
`--build-args`	Extra arguments to `docker build` (for example `--build-args='--network=host'`)
`--extra-scripts <name>`	Run named setup scripts as Docker layers (search in `HOLOSCAN_CLI_SETUP_SCRIPTS_DIR`). Can be repeated. Use `./holohub setup --list-scripts` to list.

Container Run Options

Used by: run-container, build, run, install, and package.

Option	Description
`--docker-opts <opts>`	Additional options to `docker run` (for example `--docker-opts='--gpus=all'`)
`--ssh-x11`	Deprecated; display forwarding is auto-detected from `DISPLAY`
`--nsys-profile`	Support Nsight Systems profiling in container
`--local-sdk-root <path>`	Path to Holoscan SDK on host for local SDK container
`--init`	Use tini entry point
`--persistent`	Do not delete container after it exits
`--add-volume <path>`	Mount path at `/workspace/volumes`. Can be repeated
`--as-root`	`run`: app as root; other listed commands: container as root
`--nsys-location <path>`	Nsight Systems installation path on host
`--mps`	Mount CUDA MPS host directories into container (if MPS enabled on host)
`--enable-x11`	Deprecated; X11/Wayland forwarding is auto-detected

With run, the build phase remains under the invoking user and only the application runs as root. With run-container, build, install, and package, --as-root launches the development container as root.

Commands

Create

Create a HoloHub application or external Holoscan Module from a cookiecutter template.

Usage:

./holohub create <project> [options]

Arguments:

Argument	Description
`project`	Name of the project to create

Options:

Option	Default	Description
`--template <path>`	`applications/template`	Path to template directory
`--language`	`cpp`	`cpp` or `python`
`--directory <path>`	`applications`	Module templates prompt when omitted
`--context key=value`	—	Cookiecutter context; can be repeated
`-i`, `--interactive`	true	Interactive mode; use `-i False` to disable
`--dryrun`	—	Print commands without executing

Examples:

./holohub create my_new_app --language cpp
./holohub create my_new_app --language python --directory applications

Build Container

Build the development container image for a project (or the default image if no project).

Usage:

./holohub build-container [project] [mode] [options]

Arguments:

Argument	Description
`project`	(Optional) Project to build container for
`mode`	(Optional) Mode from `metadata.json`. Applies mode's `build.docker_build_args` to docker build.

Options: All container build options, plus:

Option	Description
`--language`	`cpp` or `python` (when project has multiple implementations)
`--verbose`	Print variables passed to docker build
`--dryrun`	Print commands without executing

Examples:

./holohub build-container myapp
./holohub build-container myapp aja           # Build with AJA mode's docker_build_args
./holohub build-container myapp --extra-scripts sccache --no-cache

Run Container

Build (unless skipped) and launch the development container. Trailing arguments after -- are joined into a single string and executed inside the container via bash -c.

Usage:

./holohub run-container [project] [mode] [options] [-- command...]

Arguments:

Argument	Description
`project`	(Optional) Project to run container for
`mode`	(Optional) Mode from `metadata.json`. Applies mode's `build.docker_build_args` and `run.docker_run_args` to container.

Options: All container build and container run options, plus:

Option	Description
`--no-docker-build`	Skip building the container; use existing image
`--language`	`cpp` or `python`
`--verbose`	Print variables passed to docker run
`--dryrun`	Print commands without executing

Without -- command, the container starts with the image's default entrypoint (typically an interactive shell). With -- command, the given command is executed inside the container instead.

How -- forwarding works: all arguments after -- are joined with spaces into a single string and executed via bash -c "<string>" inside the container. This means compound commands must be passed as a single shell argument (wrapped in quotes) so that argument boundaries survive the join. If you pass multiple unquoted arguments, they are concatenated with spaces which can break commands that rely on their own quoting or newlines.

Examples:

# Launch an interactive shell in the container (image default entrypoint)
./holohub run-container

# Run linting inside the container. If pre-commit is missing, it is installed first.
./holohub run-container -- ./holohub lint

# Compound command: wrap in quotes so it stays as one argument
./holohub run-container -- './holohub lint && ./holohub build myapp'

# Multi-statement Python: use semicolons and wrap in quotes
./holohub run-container myapp -- 'python3 -c "import os; print(os.environ.get(\"HOME\", \"NOT SET\"))"'

# Use a mode's docker args
./holohub run-container myapp aja

# Skip rebuilding the container image
./holohub run-container myapp --no-docker-build
./holohub run-container --local-sdk-root /path/to/holoscan-sdk --img holohub:sdk-dev-latest

Build

Build a project. By default builds inside the container; use --local to build on the host.

Usage:

./holohub build <project> [mode] [options]

Arguments:

Argument	Description
`project`	Project to build
`mode`	(Optional) Mode from `metadata.json`

Options: All container build and container run options, plus:

Option	Description
`--local`	Build locally instead of in container
`--build-type`	`debug`, `release`, or `rel-debug`. Default: `CMAKE_BUILD_TYPE` or `release`
`--build-with <list>`	Semicolon-separated operators to build with
`--configure-args <arg>`	Extra CMake options; can be repeated (for example `--configure-args='-DCUSTOM=ON'`)
`--parallel <n>`	Number of parallel build jobs
`--pkg-generator`	`DEB` (default) or other cpack generator
`--language`	`cpp` or `python`
`--benchmark`	Build for Holoscan Flow Benchmarking (applications and benchmarks)
`--no-docker-build`	Skip building the container
`--verbose`	Extra output
`--dryrun`	Print commands without executing

Examples:

./holohub build myapp --build-type debug
./holohub build myapp --local --build-with "op1;op2" --configure-args='-DCUSTOM=ON'
./holohub build myapp --benchmark

Run

Build and run a project. By default: build container (if needed), build app in container, run in container. Use --local for host build/run.

Usage:

./holohub run <project> [mode] [options]

Arguments:

Argument	Description
`project`	Project to run
`mode`	(Optional) Mode from `metadata.json` (for example `replayer`, `standalone`)

Options: All container build and container run options, plus:

Option	Description
`--local`	Run locally instead of in container
`--language`	`cpp` or `python`
`--build-type`	`debug`, `release`, or `rel-debug`
`--run-args <args>`	Arguments passed to the application (use `=` for example `--run-args="--config=config.json"`)
`--build-with <list>`	Semicolon-separated operators to build with
`--configure-args <arg>`	Extra CMake options; can be repeated
`--parallel <n>`	Parallel build jobs
`--pkg-generator`	`DEB` (default) or other
`--no-local-build`	Skip build; only run the application
`--no-docker-build`	Skip building the container
`--verbose`	Extra output
`--dryrun`	Print commands without executing

Examples:

./holohub run myapp --language cpp
./holohub run myapp --local --language cpp --build-type debug
./holohub run hardware_app --local --as-root
./holohub run myapp --language cpp --run-args="--config=config.json"
./holohub run body_pose_estimation replayer
./holohub run holochat standalone

List

List all available targets (applications, operators, packages, and so on).

Usage:

./holohub list [options]

Options:

Option	Description
`--json`	Output the project list as JSON (see JSON Output)

Examples:

./holohub list          # Human-readable listing, grouped by project type
./holohub list --json   # Machine-readable JSON, including each source_folder

Modes

List available modes for an application (from metadata.json).

Usage:

./holohub modes <project> [options]

Arguments:

Argument	Description
`project`	Project to list modes for

Options:

Option	Description
`--language`	`cpp` or `python`
`--json`	Output the modes as JSON (see JSON Output)

Examples:

./holohub modes body_pose_estimation
./holohub modes body_pose_estimation --json

Lint

Run linting tools on the codebase or a path. ./holohub lint is a thin wrapper around pre-commit and uses the hooks declared in .pre-commit-config.yaml at the project root. Downstream wrappers can intercept the lint subcommand and route it to their own tooling, or rely on this default.

Usage:

./holohub lint [path] [options]

Arguments:

path — Path to lint. Default is the project root (pre-commit run --all-files). A subpath runs pre-commit run --files <files under path>.

Options:

--fix — Compatibility alias. Pre-commit hooks already auto-fix where possible.
--install-dependencies — Install pre-commit and prefetch hook environments. It does not change git hooks.
--dryrun — Print the pre-commit command without executing.

Examples:

./holohub lint                       # all files
./holohub lint applications/foo      # only files under applications/foo
./holohub lint --install-dependencies # explicit setup/prefetch

For container linting, ./holohub lint installs pre-commit automatically if it is not already available:

./holohub run-container -- ./holohub lint

The container sets HOME to the mounted workspace, so the generated .local/ install and .cache/pre-commit/ hook environments can be reused by later disposable containers. Both directories are ignored by git. Use ./holohub lint --install-dependencies when you want to prefetch hooks or install dependencies without running lint.

If no .pre-commit-config.yaml is present at the project root, the command exits zero with a recommendation (this keeps downstream wrappers that do not yet ship a config from breaking their CI).

Setup

Install HoloHub recommended packages and run setup scripts (for example for Holoscan SDK development). May require sudo.

Usage:

./holohub setup [options]

Options:

Option	Description
`--list-scripts`	List available scripts in `HOLOSCAN_CLI_SETUP_SCRIPTS_DIR`
`--scripts <name>`	Run named script(s); can be repeated. Omit to run default recommended setup
`--dryrun`	Print commands without executing

Examples:

./holohub setup
./holohub setup --list-scripts
./holohub setup --scripts my_script

Status

Show a compact overview of the development environment: platform, git state, containers, builds, and disk usage.

Usage:

./holohub status [options]

Options:

Option	Description
`--json`	Output status as JSON (see JSON Output)

Examples:

./holohub status          # Human-readable summary
./holohub status --json   # Machine-readable JSON output

Output sections:

Platform — architecture, GPU type/name, CUDA version, Holoscan SDK version
Git — current branch, short commit hash, dirty/modified file count
Images — HoloHub-related Docker images with creation time and running status
Docker disk — disk usage summary (images, containers, build cache)
Builds — CMake build directories with OK/FAIL status and last-modified time
Build/Data folders — disk usage of build and data cache directories

Env-Info

Print environment and path information for debugging.

Usage:

./holohub env-info [options]

Options:

Option	Description
`--json`	Output the full host report as JSON (see JSON Output)

Examples:

./holohub env-info
./holohub env-info --json

Env-Check

Run quick system checks for GPU, CUDA, Docker, Holoscan SDK, disk, display, devices, and related runtime state. Each check is reported as OK, WARN, FAIL, or SKIP.

Difference from env-info:

env-info prints raw environment variables and paths for debugging.
env-check validates the host setup and reports status for each check. It exits with code 1 if any check fails.

Typical uses:

First-time device setup before building or running applications
After upgrading drivers, Docker, CUDA, or the Holoscan SDK
At CI node startup as a quick health check
During troubleshooting when a system may be misconfigured

Usage:

./holohub env-check [options]

Options:

Option	Description
`--json`	Output results as machine-readable JSON, for CI pipelines (see JSON Output)

Exit code: 0 when there are no failures, 1 if any check fails.

Examples:

# Run env-check on the host
./holohub env-check
./holohub env-check --json

# Run env-check inside the container
./holohub run-container -- ./holohub env-check
./holohub run-container -- ./holohub env-check --json

Install

Build and install a project (container or local). Installs built artifacts (for example, using cpack).

Usage:

./holohub install [project] [mode] [options]

Arguments:

Argument	Description
`project`	Project; optional with `--dev`
`mode`	(Optional) Mode from `metadata.json`

Options: All container build and container run options, plus:

Option	Description
`--local`	Install locally instead of in container
`--dev`	Install staged module development hooks
`--uninstall`	Remove installed development hooks
`--build-dir <path>`	Select staged-hook build directory
`--build-type`	`debug`, `release`, or `rel-debug`
`--build-with <list>`	Semicolon-separated operators
`--configure-args <arg>`	Extra CMake options; can be repeated
`--parallel <n>`	Parallel build jobs
`--language`	`cpp` or `python`
`--no-docker-build`	Skip building the container
`--verbose`	Extra output
`--dryrun`	Print commands without executing

Examples:

./holohub install myapp
./holohub install myapp --local --build-type release
./holohub install --dev --build-dir build/my_module

Package

Build Holoscan Module distribution artifacts. This command packages modules as DEB and/or Python wheel artifacts; it is not the legacy HAP/MAP application packager retired in holoscan-cli 4.3.0.

Usage:

./holohub package [project] [options]

When project is omitted, the command reads module metadata from ./metadata.json in the current directory.

Options: All container build and container run options, plus:

Option	Description
`--local`	Package locally instead of in a container
`--build-type`	`debug`, `release`, or `rel-debug`
`--pkg-generator <list>`	Comma-separated generators such as `DEB,WHEEL`
`--language`	`cpp` or `python`
`--no-docker-build`	Reuse an existing container image
`--verbose`	Print additional build details
`--dryrun`	Print commands without executing them

Example:

./holohub package holoscan-my-sensor --pkg-generator DEB,WHEEL

Test

Run tests for a project (for example CTest in container or locally).

Usage:

./holohub test [project] [options]

Arguments:

Argument	Description
`project`	(Optional) Project to test

Options: All container build options, plus:

Option	Description
`--local`	Test locally instead of in container
`--coverage`	Enable code coverage (adds coverage flags, runs ctest_coverage)
`--language`	`cpp` or `python`
`--clear-cache`	Clear build and install caches before running
`--ctest-script <path>`	CTest script to use
`--cmake-options <opt>`	CMake options; can be repeated
`--ctest-options <opt>`	CTest options; can be repeated
`--site-name`, `--cdash-url`, `--platform-name`	CDash/reporting options
`--no-xvfb`	Do not use xvfb
`--build-name-suffix`	Suffix for CTest build name (default: image tag)
`--no-docker-build`	Skip building the container
`--verbose`	Extra output
`--dryrun`	Print commands without executing

Examples:

./holohub test myapp
./holohub test myapp --coverage
./holohub test myapp --language python

Clear Cache

Clear cache directories (build, data, install).

Usage:

./holohub clear-cache [options]

Options:

Option	Description
`--build`	Clear build folders only
`--data`	Clear data folders only
`--install`	Clear install folders only
`--dryrun`	Print commands without executing

If none of --build, --data, --install are given, all are cleared. Use --dryrun to preview what would be deleted. The command refuses to remove /, the user's home directory, the repository root, their ancestors, or candidates outside the configured cache roots.

Examples:

./holohub clear-cache
./holohub clear-cache --build

Version

Display the installed holoscan-cli package version selected by the wrapper.

./holohub version [options]

Options:

Option	Description
`--json`	Output the version fields as JSON (see JSON Output)

Examples:

./holohub version
./holohub version --json

Autocompletion List

List targets for bash autocompletion. This command is primarily used by the autocompletion script.

Usage:

./holohub autocompletion_list

No arguments or options.

Concepts

Application modes

Applications can define modes in metadata.json: named configurations for different hardware, data sources, or deployment scenarios. When a mode is set, it supplies a default run command, build options, Docker options, and environment variables. CLI options override mode settings when provided.

Discovering and using modes:

./holohub modes <project>                  # List available modes
./holohub run <project> <mode>             # Run with a specific mode
./holohub build <project> <mode>           # Build with a specific mode
./holohub build-container <project> <mode> # Build container with mode's docker_build_args
./holohub run-container <project> <mode>   # Launch container with mode's docker args
./holohub run <project>                    # Uses default_mode if defined

CLI Parameters Override Mode Settings

When a CLI parameter is provided, it always overrides the corresponding mode setting. When a CLI parameter is not provided, the mode setting is used as the default:

Mode Field	CLI Override
`run.docker_run_args`	`--docker-opts`
`build.depends`	`--build-with`
`build.docker_build_args`	`--build-args`
`build.cmake_options`	`--configure-args`

./holohub run holochat --run-args="--debug"            # appends to default_mode.run.command
./holohub run myapp --build-with="ops"                 # overrides default_mode.build.depends
./holohub build myapp standard --build-with="ops"      # overrides standard.build.depends

Mode Structure in metadata.json

Each mode is defined under the modes key in metadata.json:

{
  "application": {
    "default_mode": "mode_name",
    "modes": {
      "mode_name": { }
    }
  }
}

default_mode (string, optional): Which mode to use when none is specified on the command line. Required only when there are two or more modes; with a single mode it is selected automatically.

Fields for each mode:

Field	Required	Description
`description`	Yes	Human-readable description
`run`	Yes	Run configuration (see below)
`requirements`	No	List of dependency IDs required for this mode
`build`	No	Build configuration (see below)
`env`	No	Environment variables applied to both build and run

Run configuration (run object):

Field	Description
`command`	Complete command to execute including arguments
`workdir`	Working directory for command execution
`docker_run_args`	Docker run arguments (string or array); applies to both build and app containers. Equivalent to `--docker-opts`
`env`	Environment variables for runtime only (local runs)

Build configuration (build object):

Field	Description
`depends`	List of operators/dependencies to build with
`docker_build_args`	Docker build arguments (string or array). Equivalent to `--build-args`
`cmake_options`	Additional CMake configure arguments
`env`	Environment variables for build operations only

Example:

{
  "application": {
    "default_mode": "standard",
    "modes": {
      "standard": {
        "description": "Standard camera input for development",
        "requirements": ["camera", "model"],
        "run": {
          "command": "python3 <holohub_app_source>/app.py --source camera",
          "workdir": "holohub_bin"
        }
      },
      "production": {
        "description": "High-performance mode with GPU acceleration",
        "env": { "BUILD_ENV": "production" },
        "build": {
          "depends": ["tensorrt_backend"],
          "docker_build_args": ["--build-arg", "TENSORRT_VERSION=8.6"],
          "cmake_options": ["-DUSE_TENSORRT=ON"]
        },
        "run": {
          "command": "python3 <holohub_app_source>/app.py --backend tensorrt",
          "docker_run_args": ["-e", "NVIDIA_VISIBLE_DEVICES=1", "--shm-size=1g"],
          "env": { "LOG_LEVEL": "info" }
        }
      }
    }
  }
}

Key points:

Mode names must match ^[a-zA-Z_][a-zA-Z0-9_]*$ (alphanumeric and underscore, cannot start with a number).
Environment variable precedence: inner scope (build.env / run.env) overrides the top-level mode env, which overrides the host shell environment.
Path placeholders such as <holohub_app_source>, <holohub_data_dir>, and <holohub_bin> are supported in command and workdir.
When --no-docker-build is specified, build.docker_build_args is ignored.

Local Versus Container

Default (build / run): use the container workflow (build image if needed, build app in container, run in container).
--local: build and/or run on the host (skip containerized app build/run steps).
--no-docker-build: use an existing container image (skip image build).
--no-local-build: (run only) skip app build and run existing binaries/artifacts.

Environment variable HOLOSCAN_CLI_BUILD_LOCAL forces local mode (same as --local).

Default behavior of ./holohub run:

Build the container image (unless skipped with --no-docker-build)
Build the application inside the container
Run the application inside the container

Dedicated commands (build, run, build-container, run-container) allow clear workflow control when the full default pipeline is not needed.

Environment Variables

The CLI respects these variables. Defaults and behavior are summarized below.

Wrapper Bootstrap

These variables are consumed by ./holohub before it delegates to holoscan-cli. See How the wrapper resolves the CLI for selection order, safety boundaries, and managed-venv maintenance.

Variable	Default / purpose
`HOLOSCAN_CLI_PYTHON_BIN`	Explicit caller-owned interpreter; highest precedence.
`VIRTUAL_ENV`	Uses the active environment's `bin/python` when no explicit interpreter is set.
`HOLOSCAN_CLI_VENV`	Wrapper-managed environment; defaults to `${XDG_DATA_HOME:-$HOME/.local/share}/holoscan-cli/venv`.
`HOLOSCAN_CLI_SOURCE`	Local holoscan-cli checkout used in preference to a package requirement.
`HOLOSCAN_CLI_INSTALL_ARGS`	Whitespace-separated pip options and optional custom requirements. HoloHub defaults to `--pre --extra-index-url https://pypi.nvidia.com` and separately adds one exact requirement for its committed pin (or `holoscan-cli>4.2.0` in floating mode). Shell quotes are not parsed.
`HOLOSCAN_CLI_PINNED_VERSION`	One exact package version to install and verify. An explicitly empty value means floating. Ignored with `HOLOSCAN_CLI_SOURCE`.
`PIP_BREAK_SYSTEM_PACKAGES`	PEP 668 pip control only; defaults to `1` after root system scope is selected and never selects that scope.

Build and Execution

Variable	Purpose
`HOLOSCAN_CLI_BUILD_LOCAL`	Force local execution (like `--local`); containers set it during CLI re-entry
`HOLOSCAN_CLI_ALWAYS_BUILD`	Defaults to `true`; `false` skips both run builds, but only image builds for other container commands
`HOLOSCAN_CLI_ENABLE_SCCACHE`	Defaults to `false`. Set to `true` to enable sccache for builds; use with `--extra-scripts sccache` in container

Paths and Directories

Variable	Default / purpose
`HOLOSCAN_CLI_ROOT`	HoloHub repo root
`HOLOSCAN_CLI_BUILD_PARENT_DIR`	`<HOLOSCAN_CLI_ROOT>/build`
`HOLOSCAN_CLI_DATA_DIR`	`<HOLOSCAN_CLI_ROOT>/data`
`HOLOSCAN_CLI_CREATE_TEMPLATE`	`applications/template`, the default template used by `./holohub create`
`HOLOSCAN_CLI_SETUP_SCRIPTS_DIR`	`<HOLOSCAN_CLI_ROOT>/utilities/setup`
`HOLOSCAN_CLI_PATH_PREFIX`	`holohub_` (prefix for path placeholders in metadata)
`HOLOSCAN_CLI_DEFAULT_HSDK_DIR`	`/opt/nvidia/holoscan`
`HOLOSCAN_SDK_ROOT`	Local Holoscan SDK path (for mounting into containers)
`HOLOSCAN_CLI_SEARCH_PATH`	Comma-separated dirs to scan for metadata (for example `applications,operators,...`)

Container and Docker

Variable	Default / purpose
`HOLOSCAN_CLI_REPO_PREFIX`	`holohub`; base for naming
`HOLOSCAN_CLI_CONTAINER_PREFIX`	Same as repo prefix; container name prefix
`HOLOSCAN_CLI_WORKSPACE_NAME`	Workspace dir name in container
`HOLOSCAN_CLI_HOSTNAME_PREFIX`	Container hostname prefix (for example for VSCode)
`HOLOSCAN_CLI_DOCKER_EXE`	`docker`
`HOLOSCAN_CLI_BASE_IMAGE`, `HOLOSCAN_CLI_BASE_SDK_VERSION`, `HOLOSCAN_CLI_BASE_IMAGE_FORMAT`	Base image for Dockerfiles
`HOLOSCAN_CLI_DEFAULT_IMAGE_FORMAT`	Default output image tag format
`HOLOSCAN_CLI_DEFAULT_DOCKER_BUILD_ARGS`	Extra default args for `docker build`
`HOLOSCAN_CLI_DEFAULT_DOCKER_RUN_ARGS`	Extra default args for `docker run`
`HOLOSCAN_CLI_DEFAULT_DOCKERFILE`	Default Dockerfile path
`HOLOSCAN_CLI_BENCHMARKING_SUBDIR`	Benchmarking subdir (for example for flow benchmarking)

Other

Variable	Purpose
`HOLOSCAN_CLI_CTEST_SCRIPT`	CTest script used by `./holohub test`
`HOLOSCAN_CLI_CMD_NAME`	Command name in help (default: `./holohub`)
`CMAKE_BUILD_TYPE`	Default CMake build type when not set on CLI
`CMAKE_BUILD_PARALLEL_LEVEL`	Default parallel build jobs

HOLOSCAN_CLI_IN_CONTAINER_CMD selects the command used when container workflows recurse into the CLI; HoloHub sets it to the mounted wrapper.

Appendix

Bash Autocompletion

./holohub setup installs the repository's Bash completion script when /etc/bash_completion.d is available. You can also install it manually.

./holohub <TAB><TAB>       # List commands
./holohub run ultra<TAB>   # Complete project name
./holohub build vid<TAB>   # Complete project name

Manual install:

sudo cp utilities/holohub_autocomplete /etc/bash_completion.d/
echo ". /etc/bash_completion.d/holohub_autocomplete" >> ~/.bashrc
source ~/.bashrc

Useful Tips

For options that look like arguments, use = to avoid ambiguity: --run-args="--verbose" instead of --run-args "--verbose".
For run-container, pass a command to execute inside the container after --: ./holohub run-container myapp -- ./holohub env-info. Compound or multi-argument commands must be quoted as a single argument: ./holohub run-container -- './holohub lint && ./holohub build myapp'. Avoid multi-line strings after --; use semicolons instead.
All CLI options use hyphens (-), not underscores (for example --base-img, not --base_img).
Don't run the wrapper with sudo. Use ./holohub run <app> --as-root: the build stays user-owned and only the application phase runs as root.
To free disk during development: docker image prune, docker buildx prune, docker system prune (see Docker docs).