Holoscan CLI

The Holoscan CLI is the shared command engine behind metadata-driven Holoscan source-project repositories. It discovers projects from metadata.json, builds and runs them in development containers, runs tests, and provides diagnostics.

Most users should not invoke the generic holoscan command directly. Use the repository wrapper instead. For Holohub, that wrapper is ./holohub. Other wrapper-based source-project repositories can provide their own entry point while reusing the same backend.

Prerequisites

Use wrapper-based CLI workflows on a platform supported by the Holoscan SDK, such as an x86_64 Ubuntu workstation with an NVIDIA GPU or a supported NVIDIA ARM developer kit. See SDK Installation for Holoscan SDK platform and runtime prerequisites.

Container workflows also require Docker, the Docker buildx plugin, and the NVIDIA Container Toolkit. Host builds with --local additionally require the build tools and SDK installation expected by the source project you are building. For most source-project workflows, use the containerized default and avoid --local.

Use Repository Wrappers

For Holohub and other Holoscan ecosystem repositories, start with the repository’s own documentation and invoke the CLI through its wrapper script. For Holohub, see the Holohub documentation and use ./holohub from that checkout.

A wrapper script typically provides per-project configuration details before calling Holoscan CLI entrypoints. Most projects will not call the holoscan entrypoint directly. Some generic help text and dry-run output can still show holoscan because the wrapper delegates to the shared backend. Use the wrapper name, project names, and examples documented by the source-project repository; those details are maintained with that repository.

Common Workflows

The shared CLI backend supports project discovery, project lifecycle actions, development containers, diagnostics, and workspace maintenance. Not every source-project repository exposes every command, project type, or mode. Run command-specific help through the repository wrapper, for example <repository-wrapper> <command> --help.

Execution Model

The lifecycle commands build, run, install, and test are container-first by default. On the host, the CLI builds or reuses a Docker image, starts a container with the repository mounted at /workspace/<name>, and then re-runs the command inside that container with local execution enabled.

This means the normal command:

<repository-wrapper> run <project_name>

builds a suitable container, builds the selected project inside that container, and runs the command declared by the project’s metadata.json. Use --local only when you intentionally want to bypass Docker and run CMake, Python, or application commands directly on the host.

Repository Wrappers

Repository wrappers are the recommended interface for source-project repositories. They keep the user-facing command stable while configuring the generic CLI for the current source tree.

A wrapper can configure:

Repositories can use this pattern with their own wrapper name, search paths, workspace names, and container image naming rules.

Project Discovery

The CLI discovers source projects by scanning configured search paths for metadata.json files. Project metadata describes the project type, language, build/run configuration, modes, dependencies, Dockerfile selection, and paths used by CLI commands.

The most common discovery and wrapper configuration variables are:

Use <repository-wrapper> env-info to list the HOLOSCAN_CLI_* variables read in the current shell.

Container Image Selection

A repository wrapper can provide a default SDK container version, and you can override it per command:

<repository-wrapper> build-container --base-img nvcr.io/nvidia/clara-holoscan/holoscan:v5.0.0-cuda13 <project_name>

You can also configure the base repository and SDK version separately:

export HOLOSCAN_CLI_BASE_IMAGE=nvcr.io/nvidia/clara-holoscan/holoscan
export HOLOSCAN_CLI_BASE_SDK_VERSION=5.0.0
<repository-wrapper> build-container <project_name>

With the default CUDA selection, the second form derives a full base image tag such as nvcr.io/nvidia/clara-holoscan/holoscan:v5.0.0-cuda13.

If no base image tag or SDK version is configured, the CLI asks you to provide one instead of inferring it from the holoscan-cli package version.

Standalone CLI

The standalone holoscan command is mainly for holoscan-cli development, wrapper integration, and backend inspection. A wrapper script typically provides per-project configuration details before calling Holoscan CLI entrypoints. Most projects will not call the holoscan entrypoint directly.

For example, after installing the package, these backend inspection commands work without a source-project wrapper:

python3 -m pip install holoscan-cli
holoscan --help
holoscan version

To use holoscan create outside a repository wrapper, install the optional project-creation dependencies:

python3 -m pip install 'holoscan-cli[create]'

Project lifecycle commands holoscan build, holoscan run, or holoscan test each depend on source-project configurations, normally supplied by a repository wrapper script. Run those workflows through the source-project repository wrapper, and use that repository’s docs for supported project names, modes, and examples.

Command Groups

Run these commands as <repository-wrapper> <command> in a wrapped source-project repository. Not every command applies to every project type; check the project’s README and metadata.json for supported build, run, test, and package workflows.

Versioning and Legacy Commands

holoscan-cli release versions are aligned with Holoscan SDK release versions when the CLI is released with an SDK version. For example, a CLI release published with Holoscan SDK 5.0.0 is published as holoscan-cli==5.0.0. CLI-only fixes between SDK releases use the patch component for that release line.

Version alignment does not mean the CLI selects, installs, or requires a matching Holoscan SDK runtime. Use the base-image configuration described above when a container workflow should use a specific SDK version.

More Information

• Holohub documentation
• Holohub repository
• Holoscan CLI repository
• Holoscan CLI package on PyPI