feat(cli): add 'gym env validate' pre-flight config check

Ports ng_validate into the unified gym CLI (#1434): a validate() command in
cli/env.py registered as 'gym env validate' (+ ng_validate/nemo_gym_validate
deprecated shims). Runs the full parse with no Ray, exits 0/1 with a clean,
rich-escaped message. Targets martas/1434.

Epic #1205 friction #12 (no config validation tooling).

Signed-off-by: Wojciech Prazuch <wprazuch@nvidia.com>

Author: wprazuch

nemo_gym/cli/env.py

@@ -17,6 +17,7 @@
 import json
 import os
 import shlex
+import sys
 from glob import glob
 from os import makedirs
 from os.path import exists
@@ -33,6 +34,7 @@
 from devtools import pprint
 from omegaconf import DictConfig, OmegaConf
 from pydantic import Field
+from rich.markup import escape
 from rich.table import Table
 from tqdm.auto import tqdm
 
@@ -799,6 +801,34 @@ def dump_config():  # pragma: no cover
     print(OmegaConf.to_yaml(global_config_dict, resolve=True))
 
 
+def validate():
+    """
+    Validate a NeMo Gym configuration without starting any servers.
+
+    Runs the full config parse and validation pipeline — config_paths loading, key resolution,
+    cross-reference checks, and per-server validation — with no Ray initialization and no server
+    subprocesses. Exits 0 if the configuration is valid, 1 otherwise. Intended as a fast pre-flight
+    check before a run or a cluster submission.
+
+    Examples:
+
+    ```bash
+    gym env validate --config <config1> --config <config2>
+    ```
+    """
+    try:
+        global_config_dict = get_global_config_dict()
+        # Mirrors `run`/`dump_config`: handles the +h=true help path and final config validation.
+        BaseNeMoGymCLIConfig.model_validate(global_config_dict)
+    except Exception as e:
+        # escape() so '[...]' in the message (e.g. config_paths examples) isn't eaten as rich markup.
+        rich.print(f"[red]✗ Config validation failed:[/red] {escape(f'{type(e).__name__}: {e}')}")
+        sys.exit(1)
+
+    server_instances = [k for k in global_config_dict.keys() if k not in NEMO_GYM_RESERVED_TOP_LEVEL_KEYS]
+    rich.print(f"[green]✓ Config is valid[/green] — {len(server_instances)} server instance(s) configured.")
+
+
 def status():  # pragma: no cover
     global_config_dict = get_global_config_dict()
     BaseNeMoGymCLIConfig.model_validate(global_config_dict)

nemo_gym/cli/main.py

@@ -229,6 +229,11 @@ def _dataset_download(args: argparse.Namespace, overrides: list[str]) -> None:
         summary="Resolve the final config from configs, flags, and overrides.",
         flags=(CONFIG,),
     ),
+    "env validate": Command(
+        target="nemo_gym.cli.env:validate",
+        summary="Validate a config without starting servers (no Ray); exits 0 if valid, 1 if not.",
+        flags=(CONFIG,),
+    ),
     "env packages": Command(
         target="nemo_gym.cli.env:pip_list",
         summary="Print pip packages for the selected resource server.",

pyproject.toml

@@ -378,6 +378,8 @@ ng_delete_dataset_from_gitlab = "nemo_gym.cli.dataset:delete_jsonl_dataset_from_
 # Configuration utils
 nemo_gym_dump_config = "nemo_gym.cli.env:dump_config"
 ng_dump_config = "nemo_gym.cli.env:dump_config"
+nemo_gym_validate = "nemo_gym.cli.env:validate"
+ng_validate = "nemo_gym.cli.env:validate"
 
 # Display help
 nemo_gym_help = "nemo_gym.cli.general:display_help_legacy"

tests/unit_tests/test_cli.py

@@ -24,6 +24,7 @@
 from omegaconf import OmegaConf
 from pytest import MonkeyPatch, raises
 
+import nemo_gym.cli.env
 import nemo_gym.global_config
 from nemo_gym import PARENT_DIR
 from nemo_gym.cli.env import (
@@ -32,6 +33,7 @@
     RunConfig,
     RunHelper,
     init_resources_server,
+    validate,
 )
 from nemo_gym.cli.general import display_help_legacy
 from nemo_gym.config_types import ResourcesServerInstanceConfig
@@ -227,3 +229,26 @@ def test_graceful_termination_does_not_kill(self) -> None:
         assert a.wait.call_count == 1
         assert b.wait.call_count == 1
         assert runner._processes == {}
+
+
+class TestValidate:
+    """ng_validate / `gym env validate` parses + validates the config and exits 0/1 without Ray."""
+
+    def test_validate_passes_on_valid_config(self, monkeypatch: MonkeyPatch) -> None:
+        cfg = OmegaConf.create(
+            {"my_server": {"resources_servers": {"x": {"entrypoint": "app.py", "domain": "other"}}}}
+        )
+        monkeypatch.setattr(nemo_gym.cli.env, "get_global_config_dict", lambda *a, **k: cfg)
+
+        # Should return normally (no SystemExit) on a valid config.
+        validate()
+
+    def test_validate_exits_nonzero_on_invalid_config(self, monkeypatch: MonkeyPatch) -> None:
+        def boom(*a, **k):
+            raise ValueError("references resources_servers/'typo' which is not defined")
+
+        monkeypatch.setattr(nemo_gym.cli.env, "get_global_config_dict", boom)
+
+        with raises(SystemExit) as exc_info:
+            validate()
+        assert exc_info.value.code == 1

tests/unit_tests/test_cli_main.py

@@ -39,6 +39,7 @@ def fake_dispatch(target: str, overrides: list[str]) -> None:
 CONFIG_COMMANDS = [
     (["env", "run"], "nemo_gym.cli.env:run"),
     (["env", "resolve"], "nemo_gym.cli.env:dump_config"),
+    (["env", "validate"], "nemo_gym.cli.env:validate"),
     (["eval", "prepare"], "nemo_gym.cli.eval:prepare_benchmark"),
     (["eval", "aggregate"], "nemo_gym.cli.eval:aggregate_rollouts"),
     (["eval", "run"], "nemo_gym.cli.eval:e2e_rollout_collection"),