NeMo Helix CLI Development
The nemo CLI host (entry point, global options, config, auth, lazy group loading) lives in
packages/nemo_helix_ext/src/nemo_helix_ext/cli/. The helpers commands are built from live in
packages/nemo_helix_plugin so core and plugin commands share them:
Module (nemo_helix_plugin.) |
Provides |
cli |
NemoCLI (plugin base class), create_typer_app, HELP_OPTION_NAMES |
cli_state |
CLIState protocol, cli_state(ctx), resolve_output_format, resolve_cli_workspace |
cli_options |
WorkspaceOption, ListOutputFormatOption, EntityOutputFormatOption, NoTruncateOption, OutputColumnsOption, StreamOutputOption, AllPagesOption, format Literals |
cli_output |
format_output (unwraps NemoResponse), Column, check_output_columns_with_format, is_tty |
cli_pagination |
collect_offset_pages, collect_cursor_pages, warn_if_more_pages, PaginationType |
cli_warnings |
collect_warnings, add_warning |
cli_error_handling |
handle_errors: typed-client errors -> messages and exit codes |
cli_input |
build_request_body, read_data_input_with_flags, read_payload, validate_required_fields |
cli_kwargs |
build_kwargs, merge_filter_dict |
cli_codegen |
handle_code_generation for --output-format code |
Every command talks to the platform through the typed clients in nemo_helix_plugin
(nemo_helix_plugin.<area>.client, or a plugin's own client.py).
Plugin and service code must not import nemo_helix_ext — plugins only depend on
nemo_helix_plugin.
Command Categories
| Category |
Location |
Description |
| Core resource groups |
commands/<group>.py (files, inference/, jobs, models, secrets, workspaces, hidden adapters, iam, projects) |
Hand-written on typed clients, registered in commands/manifest_registry.py |
| Plugin-hosted groups |
owning package, nemo.cli entry point (guardrail → plugins/nemo-guardrails, intake/experiments → services/intake, insights, agents, garak, ...) |
Appear only when the package is installed |
| Generated job/function verbs |
nemo_helix_plugin/commands.py |
submit/explain/run for every NemoJob/NemoFunction a plugin registers |
| Setup / use cases |
commands/setup.py, commands/use_cases/, commands/auth.py, commands/config.py |
Wizards and workflows (chat, wait, ...) |
| Services |
commands/services/, commands/quickstart/ |
Run the platform locally (imports server packages by design) |
Directory Structure
packages/nemo_helix_ext/src/nemo_helix_ext/cli/
├── app.py # Entry point, global options (--base-url, --context, --output-format), lazy registration
├── manifest.py # TopLevelEntry, panel order
├── core/
│ ├── context.py # CLIContext: the concrete CLIState (config, auth, typed_client(XClient))
│ ├── help_formatter.py # NhxGroup/NhxCommand: NeMo help rendering, applied to every mounted command
│ ├── lazy_load.py # Loads core and plugin groups on demand
│ └── waiters.py # --wait / --watch helpers (deployments, jobs, gateway readiness)
└── commands/
├── manifest_registry.py # TOP_LEVEL_ENTRIES: every built-in group/command
├── secrets.py # REFERENCE port for core groups
└── ...
plugins/example-plugin/src/nemo_example_plugin/cli.py # REFERENCE for plugin groups
Running the CLI During Development
uv run _nemo --help # runs from packages/nemo_helix_ext
make update-cli # regenerate the CLI reference docs
Adding or Changing a Command Group
Templates: commands/secrets.py + tests/cli/commands/test_secrets.py for core groups,
plugins/example-plugin/src/nemo_example_plugin/cli.py + its tests/test_cli.py for plugin groups.
Pattern
from __future__ import annotations
from typing import Annotated
import typer
from nemo_helix_plugin.cli import create_typer_app
from nemo_helix_plugin.cli_codegen import handle_code_generation
from nemo_helix_plugin.cli_error_handling import handle_errors
from nemo_helix_plugin.cli_options import (
AllPagesOption,
EntityOutputFormatOption,
ListOutputFormatOption,
WorkspaceOption,
)
from nemo_helix_plugin.cli_output import Column, format_output
from nemo_helix_plugin.cli_pagination import PaginationType, collect_offset_pages, warn_if_more_pages
from nemo_helix_plugin.cli_state import cli_state, resolve_cli_workspace, resolve_output_format
from nemo_helix_plugin.cli_warnings import collect_warnings
from nemo_helix_plugin.secrets.client import SecretsClient
from nemo_helix_plugin.secrets.types import ListSecretsQueryParams
app = create_typer_app(name="secrets", help="Manage secrets.")
@app.command("get")
@collect_warnings
@handle_errors
def retrieve_secrets(
ctx: typer.Context,
name: Annotated[str, typer.Argument()],
workspace: WorkspaceOption = None,
output_format: EntityOutputFormatOption = None,
) -> None:
"""Retrieve a secret by its name."""
state = cli_state(ctx)
resolved_output_format = resolve_output_format(ctx, output_format)
kwargs = {"name": name, "workspace": resolve_cli_workspace(ctx, workspace)}
if handle_code_generation(SecretsClient, "get_secret", kwargs, resolved_output_format, state):
return
format_output(state.typed_client(SecretsClient).get_secret(**kwargs), output_format=resolved_output_format)
@app.command("list")
@collect_warnings
@handle_errors
def list_secrets(
ctx: typer.Context,
workspace: WorkspaceOption = None,
all_pages: AllPagesOption = False,
output_format: ListOutputFormatOption = None,
) -> None:
state = cli_state(ctx)
resolved_output_format = resolve_output_format(ctx, output_format)
query_params: ListSecretsQueryParams = {...} # omit keys the user did not set
kwargs = {"workspace": resolve_cli_workspace(ctx, workspace), "query_params": query_params}
if handle_code_generation(
SecretsClient, "list_secrets", kwargs, resolved_output_format, state,
result="all-pages" if all_pages else "list",
):
return
items = collect_offset_pages(state.typed_client(SecretsClient).list_secrets(**kwargs), all_pages=all_pages)
format_output(items, is_list=True, output_format=resolved_output_format, output_columns=[Column("name"), ...])
if not all_pages:
warn_if_more_pages(items, PaginationType.PAGE_NUMBER)
Existing core commands still import some of these from their old nemo_helix_ext.cli.core.* paths,
which re-export them. New code imports from nemo_helix_plugin.
Conventions that keep the surface consistent:
- Client:
cli_state(ctx).typed_client(XClient) derives the service client from the CLI's shared
NemoClient (base URL, auth, token refresh). Never construct clients from config or env inside a
command, and never add a per-command --base-url or --cluster: the platform comes from the global
nemo --base-url / nemo --context.
- Groups: build every group with
create_typer_app(...), not typer.Typer(...). Under nemo the host
also renders it with NhxGroup.
- Options: use the shared aliases (
WorkspaceOption, ListOutputFormatOption, ...). Output format is
always --output-format / --output / -f; do not add other spellings or reuse -f for another
option. Resolve with resolve_output_format(ctx, output_format) and name the result
resolved_output_format (ty otherwise narrows the option Literal).
- Every
list/get command takes --output-format and prints with format_output.
- Request bodies are the typed request models from
nemo_helix_plugin.<area>.types. Build them from
user input with build_request_body(Model, data) (rejects unknown fields; only provided fields are sent),
or from only the fields the user set. Query params are the TypedDicts in types.py.
- Output: single-entity responses go straight into
format_output (it unwraps NemoResponse).
Entities parsed by typed clients keep their id/created_at/... metadata. List commands pass default
output_columns so tables are readable.
-f code: handle_code_generation(XClient, "<method>", kwargs, ..., result="entity"|"list"|"all-pages"|"none"|"binary");
pass the same kwargs you call the client with. Reject options the snippet cannot express (for example
--wait with -f code) with a usage error rather than printing a misleading snippet.
- Errors: let
nemo_helix_plugin.client.errors propagate; @handle_errors maps them (API errors,
including 404 and connection failures → exit 3; usage and client-side validation → exit 2). Raise
click.BadParameter for bad input and click.ClickException for expected failures.
- Warnings: decorate commands with
@collect_warnings so add_warning (pagination, truncation)
warnings are printed.
Register the group
Core group: add a TopLevelEntry to commands/manifest_registry.py (help must equal the Typer app's
help string; tests/cli/test_app.py::test_manifest_help_matches_loaded_manual_entry checks this).
Plugin-hosted group: subclass nemo_helix_plugin.cli.NemoCLI in the owning package and register it
under [project.entry-points."nemo.cli"] in that package's pyproject.toml (see
plugins/example-plugin). Run uv sync --frozen --all-packages so the entry point is installed. A plugin
group with the same name as a built-in core group replaces it.
Missing typed endpoint
If the typed client lacks a route, add it to nemo_helix_plugin/<area>/{endpoints,types,client}.py
(or the plugin's own types/endpoints.py + client.py) mirroring the server's FastAPI route exactly,
with tests.
Testing
Required for a new or changed group:
- Wire-level unit tests: drive the real Typer app against a typed client over
httpx.MockTransport and assert method, path, query string, exact JSON body, stdout, --all-pages,
error mapping, and that -f code sends nothing and emits typed-client code.
- Core groups (
tests/cli/commands/test_<group>.py): pass
CLIContext(_client=NemoClient(... http_client=httpx.Client(transport=httpx.MockTransport(recorder)))).
- Plugin groups: pass a stand-in
CLIState whose typed_client builds the client over the mock
transport, or mount the app under an NhxGroup root with the real CLIContext to test what users see.
- Integration tests (core,
tests/cli/integration/test_<group>.py): the runner fixture injects a
NemoClient backed by the in-process ASGI app from nhx.testing; add the service class to
create_test_client(...) in tests/cli/integration/conftest.py if it is not hosted yet.
uv run --frozen pytest packages/nemo_helix_ext/tests/cli -q
uv run --frozen pytest packages/nemo_helix_plugin/tests -q
Troubleshooting
- Group help mismatch: the manifest
help and the Typer app help must be identical.
- "Missing workspace" exit 2 when a workspace is configured: the command passed
workspace=None
to an endpoint whose path has no {workspace} default; resolve it with resolve_cli_workspace(ctx, workspace).
-f code snippet does not compile: the kwargs contain a value _render_value cannot render;
extend nemo_helix_plugin/cli_codegen.py (it handles pydantic models, RootModel, enums, SecretStr
masking, datetimes, dicts, lists) and add a compile() test in packages/nemo_helix_plugin/tests/test_cli_codegen.py.
RuntimeError: No NeMo Helix CLI state on this context: a test invoked the command without
obj=; pass a CLI state.
- Command needs a helper the typed client lacks: check
packages/filesets/src/filesets/transfer.py
(fileset upload/download/list/delete) before adding a route.
1---2name: nhx-cli3description: Use when developing the NeMo Helix CLI - adding or changing command groups, wiring a service's typed client into commands, output formatting, pagination, error mapping, or the `--output-format code` snippet generator. Covers core groups in nemo_helix_ext and plugin-hosted `nemo.cli` groups.4metadata:5 source: https://skillmd.com/skills/nvidia-nemo/nhx-cli6 author: NeMo Helix Team <nemo-helix@nvidia.com>7---89# NeMo Helix CLI Development1011The `nemo` CLI host (entry point, global options, config, auth, lazy group loading) lives in12`packages/nemo_helix_ext/src/nemo_helix_ext/cli/`. The helpers commands are built from live in13`packages/nemo_helix_plugin` so core and plugin commands share them:1415| Module (`nemo_helix_plugin.`) | Provides |16|---|---|17| `cli` | `NemoCLI` (plugin base class), `create_typer_app`, `HELP_OPTION_NAMES` |18| `cli_state` | `CLIState` protocol, `cli_state(ctx)`, `resolve_output_format`, `resolve_cli_workspace` |19| `cli_options` | `WorkspaceOption`, `ListOutputFormatOption`, `EntityOutputFormatOption`, `NoTruncateOption`, `OutputColumnsOption`, `StreamOutputOption`, `AllPagesOption`, format Literals |20| `cli_output` | `format_output` (unwraps `NemoResponse`), `Column`, `check_output_columns_with_format`, `is_tty` |21| `cli_pagination` | `collect_offset_pages`, `collect_cursor_pages`, `warn_if_more_pages`, `PaginationType` |22| `cli_warnings` | `collect_warnings`, `add_warning` |23| `cli_error_handling` | `handle_errors`: typed-client errors -> messages and exit codes |24| `cli_input` | `build_request_body`, `read_data_input_with_flags`, `read_payload`, `validate_required_fields` |25| `cli_kwargs` | `build_kwargs`, `merge_filter_dict` |26| `cli_codegen` | `handle_code_generation` for `--output-format code` |2728Every command talks to the platform through the typed clients in `nemo_helix_plugin`29(`nemo_helix_plugin.<area>.client`, or a plugin's own `client.py`).3031Plugin and service code must **not import `nemo_helix_ext`** — plugins only depend on32`nemo_helix_plugin`.3334## Command Categories3536| Category | Location | Description |37|----------|----------|-------------|38| **Core resource groups** | `commands/<group>.py` (`files`, `inference/`, `jobs`, `models`, `secrets`, `workspaces`, hidden `adapters`, `iam`, `projects`) | Hand-written on typed clients, registered in `commands/manifest_registry.py` |39| **Plugin-hosted groups** | owning package, `nemo.cli` entry point (`guardrail` → `plugins/nemo-guardrails`, `intake`/`experiments` → `services/intake`, `insights`, `agents`, `garak`, ...) | Appear only when the package is installed |40| **Generated job/function verbs** | `nemo_helix_plugin/commands.py` | `submit`/`explain`/`run` for every `NemoJob`/`NemoFunction` a plugin registers |41| **Setup / use cases** | `commands/setup.py`, `commands/use_cases/`, `commands/auth.py`, `commands/config.py` | Wizards and workflows (`chat`, `wait`, ...) |42| **Services** | `commands/services/`, `commands/quickstart/` | Run the platform locally (imports server packages by design) |4344## Directory Structure4546```47packages/nemo_helix_ext/src/nemo_helix_ext/cli/48├── app.py # Entry point, global options (--base-url, --context, --output-format), lazy registration49├── manifest.py # TopLevelEntry, panel order50├── core/51│ ├── context.py # CLIContext: the concrete CLIState (config, auth, typed_client(XClient))52│ ├── help_formatter.py # NhxGroup/NhxCommand: NeMo help rendering, applied to every mounted command53│ ├── lazy_load.py # Loads core and plugin groups on demand54│ └── waiters.py # --wait / --watch helpers (deployments, jobs, gateway readiness)55└── commands/56 ├── manifest_registry.py # TOP_LEVEL_ENTRIES: every built-in group/command57 ├── secrets.py # REFERENCE port for core groups58 └── ...5960plugins/example-plugin/src/nemo_example_plugin/cli.py # REFERENCE for plugin groups61```6263## Running the CLI During Development6465```bash66uv run _nemo --help # runs from packages/nemo_helix_ext67make update-cli # regenerate the CLI reference docs68```6970## Adding or Changing a Command Group7172Templates: `commands/secrets.py` + `tests/cli/commands/test_secrets.py` for core groups,73`plugins/example-plugin/src/nemo_example_plugin/cli.py` + its `tests/test_cli.py` for plugin groups.7475### Pattern7677```python78from __future__ import annotations7980from typing import Annotated8182import typer83from nemo_helix_plugin.cli import create_typer_app84from nemo_helix_plugin.cli_codegen import handle_code_generation85from nemo_helix_plugin.cli_error_handling import handle_errors86from nemo_helix_plugin.cli_options import (87 AllPagesOption,88 EntityOutputFormatOption,89 ListOutputFormatOption,90 WorkspaceOption,91)92from nemo_helix_plugin.cli_output import Column, format_output93from nemo_helix_plugin.cli_pagination import PaginationType, collect_offset_pages, warn_if_more_pages94from nemo_helix_plugin.cli_state import cli_state, resolve_cli_workspace, resolve_output_format95from nemo_helix_plugin.cli_warnings import collect_warnings96from nemo_helix_plugin.secrets.client import SecretsClient97from nemo_helix_plugin.secrets.types import ListSecretsQueryParams9899app = create_typer_app(name="secrets", help="Manage secrets.")100101102@app.command("get")103@collect_warnings104@handle_errors105def retrieve_secrets(106 ctx: typer.Context,107 name: Annotated[str, typer.Argument()],108 workspace: WorkspaceOption = None,109 output_format: EntityOutputFormatOption = None,110) -> None:111 """Retrieve a secret by its name."""112 state = cli_state(ctx)113 resolved_output_format = resolve_output_format(ctx, output_format)114115 kwargs = {"name": name, "workspace": resolve_cli_workspace(ctx, workspace)}116 if handle_code_generation(SecretsClient, "get_secret", kwargs, resolved_output_format, state):117 return118119 format_output(state.typed_client(SecretsClient).get_secret(**kwargs), output_format=resolved_output_format)120121122@app.command("list")123@collect_warnings124@handle_errors125def list_secrets(126 ctx: typer.Context,127 workspace: WorkspaceOption = None,128 all_pages: AllPagesOption = False,129 output_format: ListOutputFormatOption = None,130) -> None:131 state = cli_state(ctx)132 resolved_output_format = resolve_output_format(ctx, output_format)133 query_params: ListSecretsQueryParams = {...} # omit keys the user did not set134 kwargs = {"workspace": resolve_cli_workspace(ctx, workspace), "query_params": query_params}135 if handle_code_generation(136 SecretsClient, "list_secrets", kwargs, resolved_output_format, state,137 result="all-pages" if all_pages else "list",138 ):139 return140 items = collect_offset_pages(state.typed_client(SecretsClient).list_secrets(**kwargs), all_pages=all_pages)141 format_output(items, is_list=True, output_format=resolved_output_format, output_columns=[Column("name"), ...])142 if not all_pages:143 warn_if_more_pages(items, PaginationType.PAGE_NUMBER)144```145146Existing core commands still import some of these from their old `nemo_helix_ext.cli.core.*` paths,147which re-export them. New code imports from `nemo_helix_plugin`.148149Conventions that keep the surface consistent:150- **Client**: `cli_state(ctx).typed_client(XClient)` derives the service client from the CLI's shared151 `NemoClient` (base URL, auth, token refresh). Never construct clients from config or env inside a152 command, and never add a per-command `--base-url` or `--cluster`: the platform comes from the global153 `nemo --base-url` / `nemo --context`.154- **Groups**: build every group with `create_typer_app(...)`, not `typer.Typer(...)`. Under `nemo` the host155 also renders it with `NhxGroup`.156- **Options**: use the shared aliases (`WorkspaceOption`, `ListOutputFormatOption`, ...). Output format is157 always `--output-format` / `--output` / `-f`; do not add other spellings or reuse `-f` for another158 option. Resolve with `resolve_output_format(ctx, output_format)` and name the result159 `resolved_output_format` (ty otherwise narrows the option Literal).160- **Every `list`/`get` command** takes `--output-format` and prints with `format_output`.161- **Request bodies** are the typed request models from `nemo_helix_plugin.<area>.types`. Build them from162 user input with `build_request_body(Model, data)` (rejects unknown fields; only provided fields are sent),163 or from only the fields the user set. Query params are the `TypedDict`s in `types.py`.164- **Output**: single-entity responses go straight into `format_output` (it unwraps `NemoResponse`).165 Entities parsed by typed clients keep their `id`/`created_at`/... metadata. List commands pass default166 `output_columns` so tables are readable.167- **`-f code`**: `handle_code_generation(XClient, "<method>", kwargs, ..., result="entity"|"list"|"all-pages"|"none"|"binary")`;168 pass the same kwargs you call the client with. Reject options the snippet cannot express (for example169 `--wait` with `-f code`) with a usage error rather than printing a misleading snippet.170- **Errors**: let `nemo_helix_plugin.client.errors` propagate; `@handle_errors` maps them (API errors,171 including 404 and connection failures → exit 3; usage and client-side validation → exit 2). Raise172 `click.BadParameter` for bad input and `click.ClickException` for expected failures.173- **Warnings**: decorate commands with `@collect_warnings` so `add_warning` (pagination, truncation)174 warnings are printed.175176### Register the group177178Core group: add a `TopLevelEntry` to `commands/manifest_registry.py` (`help` must equal the Typer app's179help string; `tests/cli/test_app.py::test_manifest_help_matches_loaded_manual_entry` checks this).180181Plugin-hosted group: subclass `nemo_helix_plugin.cli.NemoCLI` in the owning package and register it182under `[project.entry-points."nemo.cli"]` in that package's `pyproject.toml` (see183`plugins/example-plugin`). Run `uv sync --frozen --all-packages` so the entry point is installed. A plugin184group with the same name as a built-in core group replaces it.185186### Missing typed endpoint187188If the typed client lacks a route, add it to `nemo_helix_plugin/<area>/{endpoints,types,client}.py`189(or the plugin's own `types/endpoints.py` + `client.py`) mirroring the server's FastAPI route exactly,190with tests.191192## Testing193194Required for a new or changed group:1951961. **Wire-level unit tests**: drive the real Typer app against a typed client over197 `httpx.MockTransport` and assert method, path, query string, exact JSON body, stdout, `--all-pages`,198 error mapping, and that `-f code` sends nothing and emits typed-client code.199 - Core groups (`tests/cli/commands/test_<group>.py`): pass200 `CLIContext(_client=NemoClient(... http_client=httpx.Client(transport=httpx.MockTransport(recorder))))`.201 - Plugin groups: pass a stand-in `CLIState` whose `typed_client` builds the client over the mock202 transport, or mount the app under an `NhxGroup` root with the real `CLIContext` to test what users see.2032. **Integration tests** (core, `tests/cli/integration/test_<group>.py`): the `runner` fixture injects a204 `NemoClient` backed by the in-process ASGI app from `nhx.testing`; add the service class to205 `create_test_client(...)` in `tests/cli/integration/conftest.py` if it is not hosted yet.206207```bash208uv run --frozen pytest packages/nemo_helix_ext/tests/cli -q209uv run --frozen pytest packages/nemo_helix_plugin/tests -q210```211212## Troubleshooting213214- **Group help mismatch**: the manifest `help` and the Typer app `help` must be identical.215- **"Missing workspace" exit 2 when a workspace is configured**: the command passed `workspace=None`216 to an endpoint whose path has no `{workspace}` default; resolve it with `resolve_cli_workspace(ctx, workspace)`.217- **`-f code` snippet does not compile**: the kwargs contain a value `_render_value` cannot render;218 extend `nemo_helix_plugin/cli_codegen.py` (it handles pydantic models, `RootModel`, enums, `SecretStr`219 masking, datetimes, dicts, lists) and add a `compile()` test in `packages/nemo_helix_plugin/tests/test_cli_codegen.py`.220- **`RuntimeError: No NeMo Helix CLI state on this context`**: a test invoked the command without221 `obj=`; pass a CLI state.222- **Command needs a helper the typed client lacks**: check `packages/filesets/src/filesets/transfer.py`223 (fileset upload/download/list/delete) before adding a route.