Holoscan CLI

Command-line tool for discovering, building, running, testing, and linting HoloHub-style Holoscan source projects. Published as the holoscan-cli PyPI package and installs the holoscan console script.

Overview

The CLI presents a single command surface for the source-project development lifecycle:

• Project lifecycle: build, run, test, install, package
• Container: build-container, run-container
• Discovery / diagnostics: list, modes, status, env-info, env-check, autocompletion_list, version
• Workspace: lint, setup, clear-cache, create

Run holoscan <command> --help for per-command flags.

Per-repo wrappers install this package and delegate to holoscan, layering on their own configuration via HOLOSCAN_CLI_* environment variables:

Common env vars: HOLOSCAN_CLI_ROOT (repo root), HOLOSCAN_CLI_SEARCH_PATH (subdirs to scan for metadata.json), HOLOSCAN_CLI_PATH_PREFIX (placeholder prefix in metadata templates), HOLOSCAN_CLI_REPO_PREFIX (container image name prefix). The legacy HOLOHUB_* spelling is no longer honored since holoscan v4.3.0 — set the HOLOSCAN_CLI_* names directly. holoscan env-info lists every env var the CLI reads in the current shell.

Project trust model

Holoscan source projects are executable code, not passive data. In particular, metadata.json can define a run.command (directly or through a mode), and holoscan run executes that project-defined command. Build files, Dockerfiles, setup scripts, and test configuration can execute project code as well. Review the source and metadata before building or running a repository you do not trust.

For a plain run.command string, the CLI expands Holoscan placeholders, parses the result into an argument vector, and launches it without an implicit shell. A project can still request a shell explicitly (for example, bash -c ...) or name any other executable. Local execution runs with the invoking user's permissions; elevation happens only when the user explicitly passes --as-root.

Use holoscan run <project> --dryrun --local --verbose to inspect the resolved local build and run commands without executing them. A dry run helps with review, but it is not a sandbox and does not make untrusted project code safe.

JSON output

list, modes, status, env-info, env-check, and version accept --json and print a single machine-readable document instead of prose.

Every payload starts with a schema_version field, currently 1. Within a version the payloads change additively: new keys may appear, existing keys are not removed or renamed. Consumers should ignore keys they do not recognize; a removal or rename bumps schema_version.

env-info --json reports host state, so the values vary by machine — the docker, cuda_gpu, and git sections are null when unavailable.

Source layout

src/holoscan_cli/
  cli.py              top-level argparse + dispatch (HoloscanCLI)
  commands/           one file per subcommand + a central registry
  container/          HoloscanContainer + docker arg helpers + parser builders
  utils/              io.py, text.py, sdk.py, docker.py, host_setup.py,
                      env_info.py, holohub.py
  setup_scripts/      bundled bash scripts backing `setup --scripts` and
                      `build-container --extra-scripts`
  metadata/           project metadata JSON schemas
  testing/            CTest helpers shipped in the wheel

Prerequisites

A platform supported by the NVIDIA Holoscan SDK: an x64 PC with Ubuntu and an NVIDIA GPU, or a supported NVIDIA ARM development kit.

Installation

pip install holoscan-cli
holoscan --help

For transient use without keeping an installed environment, package-name based tool runners can use the compatibility alias:

uvx holoscan-cli --help
pipx run holoscan-cli --help

The primary CLI command remains holoscan. Explicit package/command forms also work when you want the canonical command name from a transient runner:

uvx --from holoscan-cli holoscan --help
pipx run --spec holoscan-cli holoscan --help

Versioning

holoscan-cli release versions are aligned with Holoscan SDK GA release versions. For example, the CLI released with Holoscan SDK 4.4.0 is published as holoscan-cli==4.4.0; the CLI released with Holoscan SDK 4.5.0 is published as holoscan-cli==4.5.0.

CLI-only fixes between SDK releases use the patch component for the current SDK release line, for example holoscan-cli==4.4.1 before the next SDK-aligned 4.5.0 release.

Version alignment does not imply that the CLI selects, installs, or requires a matching Holoscan SDK runtime or container base image. For container builds, the base image can be set with the CLI when your component's Dockerfile is configured with FROM ${BASE_IMAGE}, using any of the methods below:

1. Pass the image to the --base-img flag:

   holoscan build-container my_app --base-img nvcr.io/nvidia/clara-holoscan/holoscan:v4.4.0-cuda13
   

2. Set the HOLOSCAN_CLI_BASE_IMAGE environment variable to a fully qualified image path:

   export HOLOSCAN_CLI_BASE_IMAGE=nvcr.io/nvidia/clara-holoscan/holoscan:v4.4.0-cuda13
   holoscan build-container my_app
   

3. Set HOLOSCAN_CLI_BASE_IMAGE to an image repository (no tag) and HOLOSCAN_CLI_BASE_SDK_VERSION to a Holoscan semantic version. The base image then resolves to $HOLOSCAN_CLI_BASE_IMAGE:v$HOLOSCAN_CLI_BASE_SDK_VERSION-$CUDA_TAG, with the CUDA tag chosen dynamically from your host environment:

   export HOLOSCAN_CLI_BASE_IMAGE=nvcr.io/nvidia/clara-holoscan/holoscan
   export HOLOSCAN_CLI_BASE_SDK_VERSION=4.4.0
   # Resolves to nvcr.io/nvidia/clara-holoscan/holoscan:v4.4.0-cuda13 on hosts with NVIDIA drivers >= 580
   holoscan build-container my_app
   

If none of these is configured, the CLI asks for a base image instead of inferring one from its own package version.

Build from source

Python 3.10+ and Poetry 2.0+ required.

# Create + activate a virtual environment
poetry env use python3.12
eval $(poetry env activate)

# Install dependencies + dev tooling
poetry install --with test
pre-commit install

# Run the test suite
poetry run pytest

# Build sdist + wheel
poetry build

Testing against an in-tree source-project fixture

The repo ships a minimal HoloHub-style fixture at tests/fixtures/holohub_smoke/ (one application with a metadata.json that validates against the application schema). Point the CLI at it without needing a HoloHub / I4H checkout:

HOLOSCAN_CLI_ROOT=tests/fixtures/holohub_smoke holoscan list
HOLOSCAN_CLI_ROOT=tests/fixtures/holohub_smoke holoscan modes smoke_app

The same fixture is what .github/scripts/smoke_test.sh exercises against the installed wheel on every CI run, so a passing fixture run locally is a strong proxy for the smoke-test job passing on push.

Testing against the downstream wrappers

Each consuming repo (HoloHub / I4H Workflows) carries a test_holoscan_cli_consolidation.py that exercises the unified holoscan CLI against its project tree. Point the wrapper at a local checkout via HOLOSCAN_CLI_SOURCE:

cd /path/to/holohub
HOLOSCAN_CLI_SOURCE=/path/to/holoscan-cli \
  python -m pytest -q -o addopts='' utilities/cli/tests/test_holoscan_cli_consolidation.py

The wrapper prepends <HOLOSCAN_CLI_SOURCE>/src to PYTHONPATH, so an in-progress branch can be exercised end-to-end without publishing a wheel first.

Contributing

See CONTRIBUTING.md for details. .github/CI.md covers the CI/release pipelines that back the workflow badges at the top of this page.

Deprecations

HAP/MAP application packaging

Application packaging (HAP/MAP) is no longer part of this CLI: holoscan nics and the monai-deploy console script are intentionally not provided. The current holoscan package command is for building Holoscan Module distribution artifacts; it is not the legacy HAP/MAP application packager. Before holoscan v4.3.0, holoscan run was the HAP/MAP packaged-image runner; since v4.3.0 the same name now drives the HoloHub-style source-project runner, so it no longer launches packaged images. Developers that still rely on HAP/MAP packaging should pin both holoscan-cli<=4.2.0, the last CLI release that shipped that interface, and holoscan<=4.2.0, because the legacy package command depends on the artifacts JSON manifest and was only tested with those SDK versions. Otherwise, migrate to the Holoscan SDK packaging workflows directly. See issue #164 for the deprecation timeline.