Improve --help for enhanced user experience (#24903)

Signed-off-by: Harry Mellor <19981378+hmellor@users.noreply.github.com>

vllm/entrypoints/cli/benchmark/main.py

@@ -8,8 +8,7 @@ import typing
 
 from vllm.entrypoints.cli.benchmark.base import BenchmarkSubcommandBase
 from vllm.entrypoints.cli.types import CLISubcommand
-from vllm.entrypoints.utils import (VLLM_SUBCMD_PARSER_EPILOG,
-                                    show_filtered_argument_or_group_from_help)
+from vllm.entrypoints.utils import VLLM_SUBCMD_PARSER_EPILOG
 
 if typing.TYPE_CHECKING:
     from vllm.utils import FlexibleArgumentParser
@@ -33,9 +32,8 @@ class BenchmarkSubcommand(CLISubcommand):
             subparsers: argparse._SubParsersAction) -> FlexibleArgumentParser:
         bench_parser = subparsers.add_parser(
             self.name,
-            help=self.help,
             description=self.help,
-            usage="vllm bench <bench_type> [options]")
+            usage=f"vllm {self.name} <bench_type> [options]")
         bench_subparsers = bench_parser.add_subparsers(required=True,
                                                        dest="bench_type")
 
@@ -44,13 +42,12 @@ class BenchmarkSubcommand(CLISubcommand):
                 cmd_cls.name,
                 help=cmd_cls.help,
                 description=cmd_cls.help,
-                usage=f"vllm bench {cmd_cls.name} [options]",
+                usage=f"vllm {self.name} {cmd_cls.name} [options]",
             )
             cmd_subparser.set_defaults(dispatch_function=cmd_cls.cmd)
             cmd_cls.add_cli_args(cmd_subparser)
-            show_filtered_argument_or_group_from_help(cmd_subparser,
-                                                      ["bench", cmd_cls.name])
-            cmd_subparser.epilog = VLLM_SUBCMD_PARSER_EPILOG
+            cmd_subparser.epilog = VLLM_SUBCMD_PARSER_EPILOG.format(
+                subcmd=f"{self.name} {cmd_cls.name}")
         return bench_parser
 
 

vllm/entrypoints/cli/main.py

@@ -30,7 +30,7 @@ def main():
 
     parser = FlexibleArgumentParser(
         description="vLLM CLI",
-        epilog=VLLM_SUBCMD_PARSER_EPILOG,
+        epilog=VLLM_SUBCMD_PARSER_EPILOG.format(subcmd="[subcommand]"),
     )
     parser.add_argument(
         '-v',

vllm/entrypoints/cli/run_batch.py

@@ -9,8 +9,7 @@ import importlib.metadata
 import typing
 
 from vllm.entrypoints.cli.types import CLISubcommand
-from vllm.entrypoints.utils import (VLLM_SUBCMD_PARSER_EPILOG,
-                                    show_filtered_argument_or_group_from_help)
+from vllm.entrypoints.utils import VLLM_SUBCMD_PARSER_EPILOG
 from vllm.logger import init_logger
 
 if typing.TYPE_CHECKING:
@@ -50,7 +49,7 @@ class RunBatchSubcommand(CLISubcommand):
         from vllm.entrypoints.openai.run_batch import make_arg_parser
 
         run_batch_parser = subparsers.add_parser(
-            "run-batch",
+            self.name,
             help="Run batch prompts and write results to file.",
             description=(
                 "Run batch prompts using vLLM's OpenAI-compatible API.\n"
@@ -59,9 +58,8 @@ class RunBatchSubcommand(CLISubcommand):
             "vllm run-batch -i INPUT.jsonl -o OUTPUT.jsonl --model <model>",
         )
         run_batch_parser = make_arg_parser(run_batch_parser)
-        show_filtered_argument_or_group_from_help(run_batch_parser,
-                                                  ["run-batch"])
-        run_batch_parser.epilog = VLLM_SUBCMD_PARSER_EPILOG
+        run_batch_parser.epilog = VLLM_SUBCMD_PARSER_EPILOG.format(
+            subcmd=self.name)
         return run_batch_parser
 
 

vllm/entrypoints/cli/serve.py

@@ -14,8 +14,7 @@ from vllm.entrypoints.openai.api_server import (run_server, run_server_worker,
                                                 setup_server)
 from vllm.entrypoints.openai.cli_args import (make_arg_parser,
                                               validate_parsed_serve_args)
-from vllm.entrypoints.utils import (VLLM_SUBCMD_PARSER_EPILOG,
-                                    show_filtered_argument_or_group_from_help)
+from vllm.entrypoints.utils import VLLM_SUBCMD_PARSER_EPILOG
 from vllm.logger import init_logger
 from vllm.usage.usage_lib import UsageContext
 from vllm.utils import (FlexibleArgumentParser, decorate_logs, get_tcp_uri,
@@ -29,6 +28,14 @@ from vllm.v1.utils import (APIServerProcessManager,
 
 logger = init_logger(__name__)
 
+DESCRIPTION = """Launch a local OpenAI-compatible API server to serve LLM
+completions via HTTP. Defaults to Qwen/Qwen3-0.6B if no model is specified.
+
+Search by using: `--help=<ConfigGroup>` to explore options by section (e.g.,
+--help=ModelConfig, --help=Frontend)
+  Use `--help=all` to show all available flags at once.
+"""
+
 
 class ServeSubcommand(CLISubcommand):
     """The `serve` subcommand for the vLLM CLI. """
@@ -56,14 +63,13 @@ class ServeSubcommand(CLISubcommand):
             self,
             subparsers: argparse._SubParsersAction) -> FlexibleArgumentParser:
         serve_parser = subparsers.add_parser(
-            "serve",
-            help="Start the vLLM OpenAI Compatible API server.",
-            description="Start the vLLM OpenAI Compatible API server.",
+            self.name,
+            description=DESCRIPTION,
             usage="vllm serve [model_tag] [options]")
 
         serve_parser = make_arg_parser(serve_parser)
-        show_filtered_argument_or_group_from_help(serve_parser, ["serve"])
-        serve_parser.epilog = VLLM_SUBCMD_PARSER_EPILOG
+        serve_parser.epilog = VLLM_SUBCMD_PARSER_EPILOG.format(
+            subcmd=self.name)
         return serve_parser