docs(cli): enrich describe/invoke help text with routing examples

CHANGELOG.md

@@ -5,26 +5,6 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
-
-### Added
-- N/A
-
-### Changed
-- N/A
-
-### Deprecated
-- N/A
-
-### Removed
-- N/A
-
-### Fixed
-- N/A
-
-### Security
-- N/A
-
 ## [27.1.0] - 2026-08-14
 
 ### Added
@@ -215,7 +195,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Initial version aligned with Moldflow Synergy 2026.0.1
 - Python 3.10-3.13 compatibility
 
-[Unreleased]: https://github.com/Autodesk/moldflow-api/compare/v27.1.0...HEAD
 [27.1.0]: https://github.com/Autodesk/moldflow-api/compare/v27.0.1...v27.1.0
 [27.0.1]: https://github.com/Autodesk/moldflow-api/releases/tag/v27.0.1
 [27.0.0]: https://github.com/Autodesk/moldflow-api/releases/tag/v27.0.0

src/moldflow_cli/commands.py

@@ -634,12 +634,22 @@ def _cli_callback(
 	)
 	app.command(
 		"describe",
-		help=_T("Inspect a target's signature, docs, examples, and structured invoke template."),
+		help=_T(
+			"Inspect a target's signature, docs, examples, and structured invoke template. "
+			"One or more dotted targets, for example synergy.new_project."
+		),
 	)(describe_cmd)
 	app.command(
 		"invoke",
 		help=_T(
-			"Run a Moldflow target with named parameters or JSON input. Bare targets are treated as synergy.<target>."
+			"Run a Moldflow target with named parameters or JSON input. Bare targets are treated as synergy.<target>.\n\n"
+			"Dotted path to a method or function, optionally chained, for example "
+			"'synergy.new_project' or 'synergy.plot_manager.find_plot_by_name'.\n\n"
+			"Duplicate/conflicting paths are rejected. Arguments are passed as key=value or "
+			"param.attr=value. For chained targets, prefix the parameter with the method name, "
+			"e.g. find_plot_by_name.plot_name=\"My Plot\". Nested routing uses step.param.attr=value "
+			"(param=1 conflicts with param.attr=2). Methods with positional-only parameters are "
+			"not supported by named CLI routing."
 		),
 	)(invoke_cmd)
 

tests/api/unit_tests/test_cli_describe.py

@@ -16,8 +16,10 @@
 from typer.testing import CliRunner
 import moldflow
 
+from moldflow.localization import set_language
 from moldflow_cli.commands import build_cli_app
 from moldflow_cli import target_resolution
+from tests.api.unit_tests.conftest import strip_ansi
 
 runner = CliRunner()
 
@@ -90,13 +92,18 @@ def test_describe_multi_step_signature_rendering():
 
 @pytest.mark.cli
 @pytest.mark.unit
-def test_help_and_describe_show_snake_case_targets():
+def test_help_and_describe_show_snake_case_targets(_):
     """Ensure help for `describe` shows snake_case example targets."""
+    # Other tests (e.g. test_localization.py) install non-English locales via the
+    # real gettext machinery and leave builtins._ set process-wide with no teardown;
+    # force English here so this assertion is independent of pytest run order.
+    set_language(locale="enu")
     app = build_cli_app()
-    result = runner.invoke(app, ["describe", "--help"])
+    result = runner.invoke(app, ["--no-color", "describe", "--help"], env={"COLUMNS": "300"})
     assert result.exit_code == 0
-    assert "synergy.new_project" in result.stdout
-    lowered = result.stdout.lower()
+    help_text = strip_ansi(result.stdout)
+    assert "synergy.new_project" in help_text
+    lowered = help_text.lower()
     assert "structured invoke template" in lowered or "examples" in lowered
 
 

tests/api/unit_tests/test_cli_invoke_parse.py

@@ -16,6 +16,7 @@
 from typer.testing import CliRunner
 import moldflow
 from moldflow.cli_input_metadata import cli_input_adapter
+from moldflow.localization import set_language
 
 from moldflow_cli.commands import build_cli_app
 from moldflow_cli.invoke_binding import _bucket_items_by_step, _coerce_final_value
@@ -1854,10 +1855,14 @@ def open_project(self, path: int):
 
 @pytest.mark.cli
 @pytest.mark.unit
-def test_invoke_help_shows_arg_syntax():
+def test_invoke_help_shows_arg_syntax(_):
     """Invoke --help should demonstrate the step.param.attr=value routing syntax."""
+    # Other tests (e.g. test_localization.py) install non-English locales via the
+    # real gettext machinery and leave builtins._ set process-wide with no teardown;
+    # force English here so this assertion is independent of pytest run order.
+    set_language(locale="enu")
     app = build_cli_app()
-    result = runner.invoke(app, ["--no-color", "invoke", "--help"])
+    result = runner.invoke(app, ["--no-color", "invoke", "--help"], env={"COLUMNS": "300"})
     help_text = strip_ansi(result.stdout).lower()
     assert result.exit_code == 0
     assert "find_plot_by_name.plot_name" in help_text or "step.param.attr" in help_text