> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/nemo/gym/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/nemo/gym/_mcp/server.

# nemo_gym.cli.main

## Module Contents

### Classes

| Name                                                          | Description                                                                          |
| ------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| [`Command`](#nemo_gym-cli-main-Command)                       | -                                                                                    |
| [`Flag`](#nemo_gym-cli-main-Flag)                             | -                                                                                    |
| [`_GymArgumentParser`](#nemo_gym-cli-main-_GymArgumentParser) | ArgumentParser that appends a difflib "did you mean?" hint to invalid-choice errors. |

### Functions

| Name                                                                                        | Description                                                                                                      |
| ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| [`_add_leaf`](#nemo_gym-cli-main-_add_leaf)                                                 | -                                                                                                                |
| [`_asset_config_path`](#nemo_gym-cli-main-_asset_config_path)                               | Map a named asset (`name` or `name/flavor`) to its config path.                                                  |
| [`_asset_selector`](#nemo_gym-cli-main-_asset_selector)                                     | A `--<flag> NAME` selector that resolves the named asset to a config and adds it to +config\_paths.        |
| [`_bool_flag`](#nemo_gym-cli-main-_bool_flag)                                               | A `--name` store\_true flag that maps to the Hydra override `+<hydra_key>=true` when set.                  |
| [`_dataset_download`](#nemo_gym-cli-main-_dataset_download)                                 | -                                                                                                                |
| [`_dataset_upload`](#nemo_gym-cli-main-_dataset_upload)                                     | -                                                                                                                |
| [`_env_init`](#nemo_gym-cli-main-_env_init)                                                 | -                                                                                                                |
| [`_env_test`](#nemo_gym-cli-main-_env_test)                                                 | -                                                                                                                |
| [`_eval_run`](#nemo_gym-cli-main-_eval_run)                                                 | -                                                                                                                |
| [`_eval_submit`](#nemo_gym-cli-main-_eval_submit)                                           | -                                                                                                                |
| [`_extra_roots_from_search_dir`](#nemo_gym-cli-main-_extra_roots_from_search_dir)           | Prepend `--search-dir` roots to `NEMO_GYM_EXTRA_ROOTS` for the duration of the command, then restore.            |
| [`_handle_pydantic_validation_error`](#nemo_gym-cli-main-_handle_pydantic_validation_error) | -                                                                                                                |
| [`_has_override`](#nemo_gym-cli-main-_has_override)                                         | -                                                                                                                |
| [`_list_benchmarks`](#nemo_gym-cli-main-_list_benchmarks)                                   | List the benchmark view of the unified workload catalog.                                                         |
| [`_merge_config_paths`](#nemo_gym-cli-main-_merge_config_paths)                             | Coalesce all `+config_paths=[...]` tokens (from --config and asset selectors) into one (Hydra rejects dupes).    |
| [`_parsed_onboarding_name`](#nemo_gym-cli-main-_parsed_onboarding_name)                     | -                                                                                                                |
| [`_register_init_target`](#nemo_gym-cli-main-_register_init_target)                         | -                                                                                                                |
| [`_register_reward_direction`](#nemo_gym-cli-main-_register_reward_direction)               | -                                                                                                                |
| [`_search`](#nemo_gym-cli-main-_search)                                                     | `gym search [<type>] <query>`: dispatch to the chosen type's listing command (default environments), |
| [`_translate_init_target`](#nemo_gym-cli-main-_translate_init_target)                       | -                                                                                                                |
| [`_value_flag`](#nemo_gym-cli-main-_value_flag)                                             | A `--name VALUE` flag that maps to the Hydra override `+<hydra_key>=VALUE` (omitted when unset).           |
| [`build_parser`](#nemo_gym-cli-main-build_parser)                                           | -                                                                                                                |
| [`dispatch`](#nemo_gym-cli-main-dispatch)                                                   | -                                                                                                                |
| [`main`](#nemo_gym-cli-main-main)                                                           | -                                                                                                                |

### Data

[`BENCHMARK`](#nemo_gym-cli-main-BENCHMARK)

[`CATALOG_KIND`](#nemo_gym-cli-main-CATALOG_KIND)

[`COMMANDS`](#nemo_gym-cli-main-COMMANDS)

[`CONFIG`](#nemo_gym-cli-main-CONFIG)

[`ENVIRONMENT`](#nemo_gym-cli-main-ENVIRONMENT)

[`GROUPS`](#nemo_gym-cli-main-GROUPS)

[`INIT_TARGET`](#nemo_gym-cli-main-INIT_TARGET)

[`JSON`](#nemo_gym-cli-main-JSON)

[`MODEL`](#nemo_gym-cli-main-MODEL)

[`MODEL_API_KEY`](#nemo_gym-cli-main-MODEL_API_KEY)

[`MODEL_TYPE`](#nemo_gym-cli-main-MODEL_TYPE)

[`MODEL_URL`](#nemo_gym-cli-main-MODEL_URL)

[`NAME`](#nemo_gym-cli-main-NAME)

[`ONBOARDING_NAME`](#nemo_gym-cli-main-ONBOARDING_NAME)

[`RESOURCES_SERVER`](#nemo_gym-cli-main-RESOURCES_SERVER)

[`RESOURCES_SERVER_CONFIG`](#nemo_gym-cli-main-RESOURCES_SERVER_CONFIG)

[`REWARD_DIRECTION`](#nemo_gym-cli-main-REWARD_DIRECTION)

[`REWARD_RANGE`](#nemo_gym-cli-main-REWARD_RANGE)

[`SEARCH_DIR`](#nemo_gym-cli-main-SEARCH_DIR)

[`SEARCH_TERMS`](#nemo_gym-cli-main-SEARCH_TERMS)

[`STORAGE`](#nemo_gym-cli-main-STORAGE)

[`VERSION_TARGET`](#nemo_gym-cli-main-VERSION_TARGET)

[`_ASSETS`](#nemo_gym-cli-main-_ASSETS)

[`_SEARCHABLE_TYPES`](#nemo_gym-cli-main-_SEARCHABLE_TYPES)

[`logger`](#nemo_gym-cli-main-logger)

### API

```python
class nemo_gym.cli.main.Command(
    target: str | collections.abc.Callable[[argparse.Namespace, list[str]], None],
    summary: str | None = None,
    flags: tuple[nemo_gym.cli.main.Flag, ...] = tuple()
)
```

Dataclass

**`flags`** `tuple[Flag, ...] = field(default_factory=tuple)`

---

**`summary`** `str | None = None`

---

**`target`** `str | Callable[[argparse.Namespace, list[str]], None]`

---

```python
class nemo_gym.cli.main.Flag(
    register: collections.abc.Callable[[argparse.ArgumentParser], None],
    translate_to_hydra: collections.abc.Callable[[argparse.Namespace], list[str]] = lambda args: []
)
```

Dataclass

**`register`** `Callable[[argparse.ArgumentParser], None]`

---

**`translate_to_hydra`** `Callable[[argparse.Namespace], list[str]] = lambda args: []`

---

```python
class nemo_gym.cli.main._GymArgumentParser()
```

**Bases:** `ArgumentParser`

ArgumentParser that appends a difflib "did you mean?" hint to invalid-choice errors.

Covers mistyped commands/groups and bad --flag choices (e.g. --storage), since argparse validates all of them
as choices against the registry baked into the parser.

```python
nemo_gym.cli.main._GymArgumentParser.error(
    message: str
) -> None
```

```python
nemo_gym.cli.main._add_leaf(
    subparsers: argparse._SubParsersAction,
    name: str,
    command: nemo_gym.cli.main.Command
) -> None
```

```python
nemo_gym.cli.main._asset_config_path(
    flag: str,
    value: str
) -> str
```

Map a named asset (`name` or `name/flavor`) to its config path.

Searches the roots from :func:`~nemo_gym.discovery.component_search_roots` (`NEMO_GYM_EXTRA_ROOTS` +
cwd + install root), the same helper that backs `gym list`/`gym search`, so config resolution and
discovery agree on where components live. On a name collision across roots the highest-priority root wins
(as in `gym list`), with a warning. `--search-dir` reaches here via `NEMO_GYM_EXTRA_ROOTS` (set
in `main`). Searching the install root is what lets built-ins resolve by name from an arbitrary cwd
(e.g. a wheel install), not just inside the repo checkout.

```python
nemo_gym.cli.main._asset_selector(
    flag: str
) -> nemo_gym.cli.main.Flag
```

A `--<flag> NAME` selector that resolves the named asset to a config and adds it to +config\_paths.

```python
nemo_gym.cli.main._bool_flag(
    name: str,
    hydra_key: str,
    flag_help: str
) -> nemo_gym.cli.main.Flag
```

A `--name` store\_true flag that maps to the Hydra override `+<hydra_key>=true` when set.

```python
nemo_gym.cli.main._dataset_download(
    args: argparse.Namespace,
    overrides: list[str]
) -> None
```

```python
nemo_gym.cli.main._dataset_upload(
    args: argparse.Namespace,
    overrides: list[str]
) -> None
```

```python
nemo_gym.cli.main._env_init(
    args: argparse.Namespace,
    overrides: list[str]
) -> None
```

```python
nemo_gym.cli.main._env_test(
    args: argparse.Namespace,
    overrides: list[str]
) -> None
```

```python
nemo_gym.cli.main._eval_run(
    args: argparse.Namespace,
    overrides: list[str]
) -> None
```

```python
nemo_gym.cli.main._eval_submit(
    args: argparse.Namespace,
    overrides: list[str]
) -> None
```

```python
nemo_gym.cli.main._extra_roots_from_search_dir(
    search_dirs: list[str] | None
)
```

Prepend `--search-dir` roots to `NEMO_GYM_EXTRA_ROOTS` for the duration of the command, then restore.

Setting the env var lets the roots reach every resolver (discovery, the --\<component> selectors,
deep config/prompt/rollout resolution) and inherit into spawned server subprocesses.
The original value is restored (or the var unset) on exit so main() leaves no global side effect.
(sys.path is augmented with the new roots for plugin `prepare.py` imports and left as-is on exit.)

```python
nemo_gym.cli.main._handle_pydantic_validation_error(
    exc,
    parser: argparse.ArgumentParser
) -> None
```

```python
nemo_gym.cli.main._has_override(
    overrides: list[str],
    key: str
) -> bool
```

```python
nemo_gym.cli.main._list_benchmarks(
    _args: argparse.Namespace,
    overrides: list[str]
) -> None
```

List the benchmark view of the unified workload catalog.

```python
nemo_gym.cli.main._merge_config_paths(
    overrides: list[str]
) -> list[str]
```

Coalesce all `+config_paths=[...]` tokens (from --config and asset selectors) into one (Hydra rejects dupes).

```python
nemo_gym.cli.main._parsed_onboarding_name(
    args: argparse.Namespace
) -> str | None
```

```python
nemo_gym.cli.main._register_init_target(
    parser: argparse.ArgumentParser
) -> None
```

```python
nemo_gym.cli.main._register_reward_direction(
    parser: argparse.ArgumentParser
) -> None
```

```python
nemo_gym.cli.main._search(
    args: argparse.Namespace,
    overrides: list[str]
) -> None
```

`gym search [&lt;type&gt;] &lt;query&gt;`: dispatch to the chosen type's listing command (default environments),
which filters itself to the `query` config key already in `overrides`.

```python
nemo_gym.cli.main._translate_init_target(
    args: argparse.Namespace
) -> list[str]
```

```python
nemo_gym.cli.main._value_flag(
    name: str,
    hydra_key: str,
    flag_help: str,
    aliases: tuple[str, ...] = (),
    choices: tuple[str, ...] | None = None,
    quote: bool = False
) -> nemo_gym.cli.main.Flag
```

A `--name VALUE` flag that maps to the Hydra override `+&lt;hydra_key&gt;=VALUE` (omitted when unset).

```python
nemo_gym.cli.main.build_parser() -> argparse.ArgumentParser
```

```python
nemo_gym.cli.main.dispatch(
    target: str,
    overrides: list[str]
) -> None
```

```python
nemo_gym.cli.main.main() -> None
```

```python
nemo_gym.cli.main.BENCHMARK = _asset_selector('benchmark')
```

```python
nemo_gym.cli.main.CATALOG_KIND = _value_flag('kind', 'catalog_kind', 'Workload kind.', choices=('environment', 'b...
```

```python
nemo_gym.cli.main.COMMANDS = {'list benchmarks': Command(target=_list_benchmarks, summary='List or inspect av...
```

```python
nemo_gym.cli.main.CONFIG = Flag(register=(lambda p: p.add_argument('--config', action='append', metavar='PA...
```

```python
nemo_gym.cli.main.ENVIRONMENT = _asset_selector('environment')
```

```python
nemo_gym.cli.main.GROUPS = {'list': 'List available components (benchmarks, environments, agents, models, r...
```

```python
nemo_gym.cli.main.INIT_TARGET = Flag(register=_register_init_target, translate_to_hydra=_translate_init_target)
```

```python
nemo_gym.cli.main.JSON = _bool_flag('json', 'json', 'Output as machine-readable JSON.')
```

```python
nemo_gym.cli.main.MODEL = _value_flag('model', 'policy_model_name', 'Model name, HF id, or local checkpoin...
```

```python
nemo_gym.cli.main.MODEL_API_KEY = _value_flag('model-api-key', 'policy_api_key', 'Model server API key.')
```

```python
nemo_gym.cli.main.MODEL_TYPE = _asset_selector('model-type')
```

```python
nemo_gym.cli.main.MODEL_URL = _value_flag('model-url', 'policy_base_url', 'Model server base URL.')
```

```python
nemo_gym.cli.main.NAME = Flag(register=(lambda p: p.add_argument('name', nargs='?', metavar='NAME', help=...
```

```python
nemo_gym.cli.main.ONBOARDING_NAME = Flag(register=(lambda p: p.add_argument('onboarding_name', nargs='?', metavar='N...
```

```python
nemo_gym.cli.main.RESOURCES_SERVER = Flag(register=(lambda p: p.add_argument('--resources-server', metavar='NAME', he...
```

```python
nemo_gym.cli.main.RESOURCES_SERVER_CONFIG = _asset_selector('resources-server')
```

```python
nemo_gym.cli.main.REWARD_DIRECTION = Flag(register=_register_reward_direction, translate_to_hydra=(lambda args: [f'+h...
```

```python
nemo_gym.cli.main.REWARD_RANGE = Flag(register=(lambda p: p.add_argument('--reward-range', nargs=2, type=float, m...
```

```python
nemo_gym.cli.main.SEARCH_DIR = Flag(register=(lambda p: p.add_argument('--search-dir', action='append', metavar...
```

```python
nemo_gym.cli.main.SEARCH_TERMS = Flag(register=(lambda p: (p.add_argument('component_type', nargs='?', choices=(l...
```

```python
nemo_gym.cli.main.STORAGE = Flag(register=(lambda p: p.add_argument('--storage', choices=('hf', 'gitlab'), d...
```

```python
nemo_gym.cli.main.VERSION_TARGET = 'nemo_gym.cli.general:version'
```

```python
nemo_gym.cli.main._ASSETS = {'benchmark': ('benchmarks', '', 'config'), 'environment': ('environments', '', ...
```

```python
nemo_gym.cli.main._SEARCHABLE_TYPES = {'benchmarks': 'nemo_gym.cli.eval:list_benchmarks', 'environments': 'nemo_gym.cl...
```

```python
nemo_gym.cli.main.logger = logging.getLogger(__name__)
```