Contribute to Holoscan CLI

May 22, 2026 · View on GitHub

Welcome to Holoscan CLI! We're glad that you're considering contributing to the platform.

Holoscan CLI is released on GitHub as open source software to better support the community and facilitate feedback.

Reporting Feedback

Community feedback helps us improve the Holoscan CLI to better meet user needs. We use GitHub Issues to track feedback and problems over time, as well as to provide limited support to Holoscan CLI users.

Consider reviewing existing issues or opening a new issue if you:

  • Have a question about using a Holoscan CLI feature
  • Notice errors or unexpected behavior coming from Holoscan CLI
  • Have an idea for a change that might benefit other users

When reporting an error, please include relevant details that will help our team investigate the issue. Details might include:

  • A summary of the problem
  • The behavior you have observed
  • The behavior you expected
  • Details about your PC, including the architecture (x86_64 or arm64) and GPU
  • The version of Holoscan CLI where you observed the problem
  • Any relevant logs or images to help investigate the issue

You can also refer to the Discussions section for support questions and community discussions.

For Holoscan SDK related issues, visit NVIDIA Developer Forums for support questions and community discussions.

Suggesting Changes

Users are welcome to suggest code changes to Holoscan CLI in the form of Issues or Pull Requests.

Issues

Please open a new issue if you'd like to request a new feature or propose a feature design. You can tag a specific community maintainer in your post with "@", or we'll update when we've had a chance to review your post.

Pull Requests

While we primarily develop Holoscan CLI internally, we also accept external contributions that help move the platform forward. We typically favor contributions that aim to fix an existing issue or improve documentation, but we'll also integrate new features and enhancements when they're aligned with the Holoscan CLI vision. Please check in with the development team to propose your idea before spending time working on new features. This will help prevent duplicate effort and avoid spending time on features that would be unlikely to be merged.

You might contribute to Holoscan CLI to help us address fixes earlier in our development cycle, or to suggest improvements to Holoscan CLI that you believe would broadly benefit the Holoscan community.

Holoscan CLI follows a monthly release process that includes internal quality assurance. To add a fix or feature, we request that you fork Holoscan CLI, develop in a branch, and submit your change as a pull request against the latest Holoscan CLI release commit. If we accept your submission after external discussion, we will integrate those changes within our internal development and credit you in Git commit history. Any changes that we accept from community contributions will undergo quality assurance testing before they are included in the next Holoscan CLI release.

Note: We recommend that new GitHub users read GitHub's Getting Started guide before opening their first pull request.

Local development

Verifying changes locally before pushing keeps the CI feedback loop short and avoids tying up shared runners.

Set up the development environment

Python 3.10+ and Poetry 2.0+ are required. From a fresh clone:

poetry install --with test
pre-commit install                         # installs the local Git hooks

poetry install --with test mirrors the exact dependency set the Code Check workflow installs, so passing locally is a strong signal.

Run the same checks CI runs

pre-commit run --all-files                 # ruff + black + isort + markdownlint
                                           # + codespell + yaml/json/toml linters
                                           # + cmakelint. Catches every lint
                                           # failure `Code Check` would catch.
poetry run pytest -q                       # run the unit test suite.

If pre-commit run --all-files passes locally, Code Check's pre-commit job will pass on push. If poetry run pytest passes, the test matrix will pass on the same Python version locally (CI also runs 3.10 / 3.11 / 3.12 / 3.13; for full matrix coverage either use the Python you don't normally use, or rely on CI).

Smoke-test the installed wheel

The smoke-test job in Code Check rebuilds the wheel, installs it into a fresh venv, and runs .github/scripts/smoke_test.sh. To reproduce locally:

poetry build                                          # writes dist/*.whl, dist/*.tar.gz
python -m venv /tmp/holoscan-cli-smoke
/tmp/holoscan-cli-smoke/bin/pip install dist/*.whl
.github/scripts/smoke_test.sh /tmp/holoscan-cli-smoke/bin

The script exercises --help, the version/lint/list/modes surfaces against the in-tree smoke fixture at tests/fixtures/holohub_smoke/, and the negative surface (removed commands, legacy console scripts). See the README for how to point the CLI at the fixture directly from your shell.

Test against the downstream wrappers

The HoloHub / I4H wrapper repos each carry a test_holoscan_cli_consolidation.py that exercises the unified holoscan CLI against their respective project trees. Point them at a local checkout with 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

When HOLOSCAN_CLI_SOURCE is set, the wrapper prepends that checkout's src/ to PYTHONPATH so the in-progress branch is exercised end-to-end without publishing a wheel first.

Triggering CI

  • Every push to any branch runs Code Check (.github/workflows/main.yaml) — pre-commit, the pytest matrix, wheel/sdist build, wheel-content asserts, and the installed-wheel smoke test.

  • Pull requests additionally run CodeQL Advanced (.github/workflows/codeql.yaml) and Dependency review (.github/workflows/dependency-review.yml).

  • Manual TestPyPI release is the Release workflow (.github/workflows/release.yaml). Dispatch it via the CLI:

    gh workflow run release.yaml --ref <branch> \
  -f version=vX.Y.Z \
  -f rc=<optional-rc-number> \
  -f ga=false                                   # true only for an official GA

    The dispatch creates refs/tags/vX.Y.Z at the dispatch SHA, builds, smokes, publishes to TestPyPI, re-installs from test.pypi.org/simple/ and re-smokes, and deletes the tag when ga=false (so RC dispatches leave no stray refs). See .github/CI.md for the full pipeline.

If you need to introduce or bump a third-party Action, see .github/CI.md — the repo's org-level Actions allowlist gates which references are usable.

Tracking Development

We take all community feedback into consideration. If we don't believe a proposed change aligns with our direction for Holoscan CLI, or if we don't expect we can prioritize a task within a reasonable time frame, we'll let you know by appropriately labeling or closing the issue or pull request with an explanatory comment.

For items that we do plan to pursue or integrate, we use GitHub Milestones to communicate our release planning. We will add community issues and pull requests to the approximate monthly release milestone when we expect to pursue that development. Issues that we mark as "needs triage" are not part of a milestone and will be revisited once each month to determine our priorities.

Additional Information

Please refer to the project README document for additional developer information. Happy coding!