> 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.env

## Module Contents

### Classes

| Name                                               | Description                                                                                       |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| [`PipListConfig`](#nemo_gym-cli-env-PipListConfig) | -                                                                                                 |
| [`RunConfig`](#nemo_gym-cli-env-RunConfig)         | Start NeMo Gym servers for agents, models, and resources.                                         |
| [`RunHelper`](#nemo_gym-cli-env-RunHelper)         | -                                                                                                 |
| [`TestAllConfig`](#nemo_gym-cli-env-TestAllConfig) | Run tests for all server modules in the project.                                                  |
| [`TestConfig`](#nemo_gym-cli-env-TestConfig)       | Test a specific server module by running its pytest suite and optionally validating example data. |

### Functions

| Name                                                                             | Description                                                                                |
| -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| [`_display_list_of_paths`](#nemo_gym-cli-env-_display_list_of_paths)             | -                                                                                          |
| [`_format_pct`](#nemo_gym-cli-env-_format_pct)                                   | -                                                                                          |
| [`_resolve_server_dir`](#nemo_gym-cli-env-_resolve_server_dir)                   | Resolve a relative server dir (e.g. `resources_servers/<name>`) to an absolute path. |
| [`_select_shard`](#nemo_gym-cli-env-_select_shard)                               | Deterministically select this shard's subset of modules.                                   |
| [`_test_single`](#nemo_gym-cli-env-_test_single)                                 | -                                                                                          |
| [`_validate_data_single`](#nemo_gym-cli-env-_validate_data_single)               | -                                                                                          |
| [`dump_config`](#nemo_gym-cli-env-dump_config)                                   | Display the resolved Hydra configuration for debugging purposes.                           |
| [`exit_cleanly_on_config_error`](#nemo_gym-cli-env-exit_cleanly_on_config_error) | Decorator: turn user-facing ConfigError into a clean message + non-zero exit.              |
| [`init_resources_server`](#nemo_gym-cli-env-init_resources_server)               | Initialize a new resources server with template files and directory structure.             |
| [`list_environments`](#nemo_gym-cli-env-list_environments)                       | List the environments available under environments/, by short name.                        |
| [`pip_list`](#nemo_gym-cli-env-pip_list)                                         | List packages installed in a server's virtual environment.                                 |
| [`run`](#nemo_gym-cli-env-run)                                                   | Start NeMo Gym servers for agents, models, and resources.                                  |
| [`status`](#nemo_gym-cli-env-status)                                             | -                                                                                          |
| [`test`](#nemo_gym-cli-env-test)                                                 | -                                                                                          |
| [`test_all`](#nemo_gym-cli-env-test_all)                                         | -                                                                                          |
| [`validate`](#nemo_gym-cli-env-validate)                                         | Validate a config without starting Ray or any server subprocess.                           |

### Data

[`_FORCE_KILL_REAP_TIMEOUT_SEC`](#nemo_gym-cli-env-_FORCE_KILL_REAP_TIMEOUT_SEC)

[`_GRACEFUL_SHUTDOWN_TIMEOUT_SEC`](#nemo_gym-cli-env-_GRACEFUL_SHUTDOWN_TIMEOUT_SEC)

### API

```python
class nemo_gym.cli.env.PipListConfig()
```

**Bases:** [RunConfig](#nemo_gym-cli-env-RunConfig)

```python
class nemo_gym.cli.env.RunConfig()
```

**Bases:** [BaseNeMoGymCLIConfig](/nemo-gym/nemo_gym/config_types#nemo_gym-config_types-BaseNeMoGymCLIConfig)

Start NeMo Gym servers for agents, models, and resources.

Examples:

```python
config_paths="resources_servers/example_single_tool_call/configs/example_single_tool_call.yaml,\
responses_api_models/openai_model/configs/openai_model.yaml"
gym env start "+config_paths=[${config_paths}]"
```

```python
class nemo_gym.cli.env.RunHelper()
```

```python
nemo_gym.cli.env.RunHelper.check_http_server_statuses(
    successful_servers: typing.List[str]
) -> typing.List[typing.Tuple[str, nemo_gym.server_utils.ServerStatus]]
```

```python
nemo_gym.cli.env.RunHelper.display_server_instance_info() -> None
```

```python
nemo_gym.cli.env.RunHelper.poll() -> None
```

```python
nemo_gym.cli.env.RunHelper.run_forever() -> None
```

```python
nemo_gym.cli.env.RunHelper.shutdown() -> None
```

```python
nemo_gym.cli.env.RunHelper.start(
    global_config_dict_parser_config: nemo_gym.global_config.GlobalConfigDictParserConfig
) -> None
```

```python
nemo_gym.cli.env.RunHelper.wait_for_dry_run_spinup() -> None
```

```python
nemo_gym.cli.env.RunHelper.wait_for_spinup() -> None
```

```python
class nemo_gym.cli.env.TestAllConfig()
```

**Bases:** [BaseNeMoGymCLIConfig](/nemo-gym/nemo_gym/config_types#nemo_gym-config_types-BaseNeMoGymCLIConfig)

Run tests for all server modules in the project.

Examples:

```python
gym env test
```

```python
class nemo_gym.cli.env.TestConfig()
```

**Bases:** [RunConfig](#nemo_gym-cli-env-RunConfig)

Test a specific server module by running its pytest suite and optionally validating example data.

Examples:

```python
gym env test +entrypoint=resources_servers/example_single_tool_call
```

Absolute server dir resolved against the cwd, then the Gym install root.

Use this for filesystem access (reading data, running the suite); use `dir_path` (the
relative entrypoint) for display and example commands shown to the user.

```python
nemo_gym.cli.env.TestConfig.model_post_init(
    context
)
```

```python
nemo_gym.cli.env._display_list_of_paths(
    paths: typing.List[pathlib.Path]
) -> str
```

```python
nemo_gym.cli.env._format_pct(
    count: int,
    total: int
) -> str
```

```python
nemo_gym.cli.env._resolve_server_dir(
    rel_path: pathlib.Path
) -> pathlib.Path
```

Resolve a relative server dir (e.g. `resources_servers/<name>`) to an absolute path.

Checks the current working directory first (a user's local server), then falls back to the Gym
install root (`PARENT_DIR`) where built-in servers live in both editable and wheel installs.
This lets `gym env test` find and run built-in servers from any cwd, not just a repo checkout.

```python
nemo_gym.cli.env._select_shard(
    dir_paths: typing.List[pathlib.Path],
    shard_index: int,
    num_shards: int
) -> typing.List[pathlib.Path]
```

Deterministically select this shard's subset of modules.

Round-robin (stride) over a sorted list spreads heavy modules across shards more evenly than
contiguous chunks, which balances wall-time when the suite is parallelized across CI runners.

```python
nemo_gym.cli.env._test_single(
    test_config: nemo_gym.cli.env.TestConfig,
    global_config_dict: omegaconf.DictConfig
) -> subprocess.Popen
```

```python
nemo_gym.cli.env._validate_data_single(
    test_config: nemo_gym.cli.env.TestConfig
) -> None
```

```python
nemo_gym.cli.env.dump_config()
```

Display the resolved Hydra configuration for debugging purposes.

Examples:

```python
gym env resolve "+config_paths=[<config1>,<config2>]"
```

```python
nemo_gym.cli.env.exit_cleanly_on_config_error(
    fn
)
```

Decorator: turn user-facing ConfigError into a clean message + non-zero exit.

Config mistakes (missing/typo'd config\_paths, malformed config\_paths, nothing configured to
run) should fail fast with an actionable message, not a Python traceback. Unexpected errors
still propagate normally.

```python
nemo_gym.cli.env.init_resources_server()
```

Initialize a new resources server with template files and directory structure.

Examples:

```python
gym env init --resources-server my_server
```

```python
nemo_gym.cli.env.list_environments() -> None
```

List the environments available under environments/, by short name.

Examples:

```python
gym list environments
gym list environments --json
```

```python
nemo_gym.cli.env.pip_list()
```

List packages installed in a server's virtual environment.

```python
nemo_gym.cli.env.run(
    global_config_dict_parser_config: typing.Optional[nemo_gym.global_config.GlobalConfigDictParserConfig] = None
)
```

Start NeMo Gym servers for agents, models, and resources.

This command reads configuration from YAML files specified via `+config_paths` and starts all configured servers.
The configuration files should define server instances with their entrypoints and settings.

Examples:

```python
# Start servers with specific configs
config_paths="resources_servers/example_single_tool_call/configs/example_single_tool_call.yaml,\
responses_api_models/openai_model/configs/openai_model.yaml"
gym env start "+config_paths=[${config_paths}]"
```

```python
nemo_gym.cli.env.status()
```

```python
nemo_gym.cli.env.test()
```

```python
nemo_gym.cli.env.test_all()
```

```python
nemo_gym.cli.env.validate()
```

Validate a config without starting Ray or any server subprocess.

Runs the full config parse — config\_paths resolution (missing/malformed), server cross-reference
validation, mandatory `???` values, and schema — then exits 0 (valid) or, via
`exit_cleanly_on_config_error`, 1 with a clean traceback-free message. No Ray, no servers, so it
returns in well under a second instead of after Ray bootstrap.

No model config is required: a dummy `policy_model` is injected (the `NO_MODEL` parser config, as
in `gym list` / `env compose`) so model interpolations (e.g. `$&#123;policy_base_url&#125;`) resolve —
validation is about config well-formedness, not the model. Pass a model config / `--model-type`
as well if you want it validated too.

Examples:

```python
gym env validate --environment <env>
gym env validate --benchmark <benchmark>
# or by explicit config path(s):
gym env validate --config resources_servers/<env>/configs/<env>.yaml
```

```python
nemo_gym.cli.env._FORCE_KILL_REAP_TIMEOUT_SEC: int = 2
```

```python
nemo_gym.cli.env._GRACEFUL_SHUTDOWN_TIMEOUT_SEC: int = 1
```