27.1.0 package release

.coverage-config-cli

@@ -0,0 +1,17 @@
+[run]
+branch = True
+source_pkgs =
+    moldflow_cli
+
+[paths]
+source =
+    src/moldflow_cli
+    */site-packages/moldflow_cli
+
+[report]
+fail_under = 80
+show_missing = True
+precision = 2
+
+[html]
+title = Moldflow CLI Unit Test Coverage

.gitignore

@@ -180,3 +180,4 @@ Thumbs.db
 
 # Internal Autodesk directories
 .adsk/
+demo_models

CHANGELOG.md

@@ -25,6 +25,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Security
 - N/A
 
+## [27.1.0] - 2026-08-14
+
+### Added
+- Added `transparent_background` property to `ImageExportOptions` — when set to `True` with a `.png` output path, the exported image uses a transparent background instead of the renderer's opaque fill colour. Defaults to `False`; silently ignored for non-PNG formats.
+- Added a Moldflow CLI with `list`, `describe`, and `invoke` commands.
+- Added an interactive REPL for the Moldflow CLI.
+- Added invoke planning and automation support, including dry-run plans, trace output, and batch execution.
+- Added machine-readable `describe` schema output and updated CLI documentation and examples.
+- Added CLI regression tests covering chaining, argument routing, and edge-case input handling.
+
+### Changed
+- N/A
+
+### Deprecated
+- N/A
+
+### Removed
+- N/A
+
+### Fixed
+- N/A
+
+### Security
+- N/A
+
 ## [27.0.1] - 2026-04-18
 
 ### Added
@@ -190,7 +215,8 @@ 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.0.1...HEAD
+[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
 [26.0.5]: https://github.com/Autodesk/moldflow-api/releases/tag/v26.0.5

README.md

@@ -19,6 +19,16 @@ Before you begin, ensure you have:
 python -m pip install moldflow
 ```
 
+### Install with CLI support
+
+To install the package together with the optional command-line interface:
+
+```sh
+python -m pip install "moldflow[cli]"
+```
+
+After installation a `moldflow` command will be available on your `PATH`.
+
 ## Quick Start
 
 ```python
@@ -34,6 +44,265 @@ print(f"Moldflow Synergy version: {version}")
 
 See the [full documentation](https://autodesk.github.io/moldflow-api) for more in-depth examples.
 
+## Command Line Interface (CLI)
+
+The optional CLI provides a `moldflow` command for driving Synergy operations from a shell.
+
+### Basic usage
+
+```sh
+moldflow --help
+moldflow list
+moldflow list --json --with-describe --max-results 25
+moldflow describe synergy.open_project
+moldflow describe synergy.new_project synergy.open_project
+moldflow list --filter new_proj --filter "*_diag"
+```
+
+The top-level help now guides first-time users through the intended workflow:
+start with `list` to discover targets, use `describe <target>` to inspect
+usage, then run `invoke <target> ...`.
+
+`describe` now shows the preferred and minimal `invoke` forms, plus the
+corresponding `--params-json` shapes when the target is invokable, so discovery
+and execution use the same examples without leaking Python-only `self`/`cls`
+receiver details.
+
+`describe` also accepts multiple targets in one command. In human mode it renders
+one block per target; in structured `--json`, `--yaml`, and `--schema` modes it
+returns a single object for one target or a list for multiple targets.
+
+`list` now includes readable properties and read/write properties as well as methods,
+so property targets are discoverable from the main index too. In human mode it also
+surfaces each target's kind and a sensible next step. When the CLI can map a
+wrapper back to a Synergy property or `create_*` factory, the listed target is
+shown in the same Synergy-rooted form that `invoke` accepts.
+
+`list --filter` can be repeated, and repeated filters are additive: a target is
+included when it matches any provided filter value.
+
+In structured mode, `list --json` and `list --yaml` are described as scripting
+and agent-oriented outputs. `list --with-describe` embeds the structured
+`describe` payload for each listed target, and `--max-results` lets callers cap
+the result set after filtering.
+
+### Interactive REPL
+
+Start an interactive shell session with tab completion and built-in session
+commands:
+
+```sh
+moldflow repl
+```
+
+Inside the REPL you can run any CLI command without the `moldflow` prefix:
+
+```
+moldflow> list
+moldflow> describe synergy.open_project
+moldflow> invoke synergy.new_project name="My Project" path="C:/mf/MyProject.mfproj"
+```
+
+Built-in session commands:
+
+| Command          | Description                               |
+|------------------|-------------------------------------------|
+| `help`           | Show available commands                   |
+| `help <command>` | Show detailed help for a specific command |
+| `clear`          | Clear the screen                          |
+| `reset`          | Reset the Synergy session                 |
+| `exit` / `quit`  | Exit the REPL (Ctrl+D also works)         |
+
+Tab completion is available for all commands and for invokable targets when
+using `describe` or `invoke`. Pass `--debug` to show full tracebacks on errors:
+
+```sh
+moldflow repl --debug
+```
+
+### Invoking methods
+
+You can invoke methods directly:
+
+```sh
+moldflow invoke synergy.new_project name="My Project" path="C:/mf/MyProject.mfproj"
+moldflow invoke synergy.import_file file="C:/models/part.iges" show_logs=true
+```
+
+Non-primitive parameters (such as `ImportOptions`) can be configured using dotted arguments:
+
+```sh
+moldflow invoke synergy.import_file \
+  file="C:/models/part.iges" \
+  import_options.use_mdl=true \
+  import_options.units=Millimeter
+```
+
+For more complex operations you can chain calls through the object model, for example:
+
+```sh
+moldflow invoke synergy.plot_manager.find_plot_by_name.get_probe_plot_probe_line \
+  find_plot_by_name.plot_name="My Plot" \
+  get_probe_plot_probe_line.index=0 \
+  get_probe_plot_probe_line.start_pt.x=0 \
+  get_probe_plot_probe_line.start_pt.y=0 \
+  get_probe_plot_probe_line.start_pt.z=0 \
+  get_probe_plot_probe_line.end_pt.x=10 \
+  get_probe_plot_probe_line.end_pt.y=0 \
+  get_probe_plot_probe_line.end_pt.z=0
+```
+
+For automation or LLM-based tooling, you can request JSON output with `--json`:
+
+```sh
+moldflow invoke synergy.boundary_conditions.create_ndbc ... --json
+```
+
+You can provide parameters as JSON using `--params-json` or `--params-json-file` (`-J`).
+For chained targets, group parameters by step name. For single-step targets, either
+top-level parameters or an optional step-name wrapper object are accepted:
+
+```sh
+moldflow invoke synergy.plot_manager.find_plot_by_name --params-json \
+  '{"find_plot_by_name":{"plot_name":"My Plot"}}'
+```
+
+For wrapper parameters, prefer the direct parameter form in non-JSON mode. For a
+real public target such as `synergy.boundary_conditions.create_edge_loads`, that means:
+
+```sh
+moldflow invoke synergy.boundary_conditions.create_edge_loads \
+  nodes=N1,N2 \
+  force=0,0,-100
+```
+
+The JSON form uses the wrapper-native fields shown by `describe`:
+
+```json
+{
+  "nodes": {"entity_string": "N1,N2"},
+  "force": {"xyz": [0.0, 0.0, -100.0]}
+}
+```
+
+Array-like wrappers follow the same pattern, for example
+`{"value": {"values": [1.0, 2.5]}}` when a target has
+a `DoubleArray` parameter named `value`, or `{"points": {"xyz": [[0, 0, 0], [1, 0, 0]]}}`
+for a `VectorArray` parameter named `points`.
+
+The direct `param=value` form is the preferred non-JSON syntax. The explicit dotted
+form is mostly an escape hatch for tooling or debugging; when you need it, use the
+wrapper-native field name shown by `describe`, for example `nodes.entity_string=...`
+or `force.xyz=...`. List-backed wrappers now also accept shorthand such as
+`levels=1.0,2.5`, and vector-array wrappers accept `points="0,0,0;1,0,0"`.
+If shorthand input becomes ambiguous or hard to escape, prefer `--params-json`.
+
+Advanced fallback only: tagged objects with `__type__` are still accepted for generic
+or annotation-free JSON payloads, but they are intentionally not part of the normal
+customer-facing path for annotated parameters. If the CLI already has wrapper context,
+such as a typed parameter or an existing nested wrapper-valued property, the untagged
+wrapper-native JSON form is preferred.
+
+Advanced invoke modes:
+
+- `--dry-run`: parse/validate/build a call plan without executing invoke steps.
+- `--trace`: emit JSON trace events for planning/runtime deferred binding.
+- `--batch-file`: execute multiple invoke calls from a JSON array file.
+
+For terminal users, `describe`, `--dry-run`, and `--batch-file` now render
+human-readable summaries by default. Add `--json` when you want the structured
+machine contract on stdout. `--json-file-output` writes the JSON contract to a
+file without changing stdout mode, so terminal users can keep the human summary
+unless they also ask for `--json`. Human-mode output also confirms where the
+structured payload was written.
+
+`--trace` emits line-delimited JSON to stderr, one object per event, with
+`schema_version`, `sequence`, `event`, `target`, and `payload`, plus `step` or
+`property` when relevant.
+Result and error events are emitted explicitly, and batch runs add `batch_index`
+so trace consumers can correlate per-item activity without inferring it from order.
+
+Batch file shape example:
+
+```json
+[
+  {"target": "synergy.open_project", "args": ["path=C:/tmp/a.mfproj"]},
+  {"target": "synergy.import_file", "params_json": {"file": "C:/tmp/part.iges"}}
+]
+```
+
+Run:
+
+```sh
+moldflow invoke --batch-file C:/tmp/invoke_batch.json
+```
+
+To persist machine-readable output, use `--json-file-output`. Add `--json` as well
+when you also want the structured payload on stdout.
+
+Batch output now includes a `summary` block and each `batch_results` entry echoes a
+normalized `request` payload plus an `error_type` when validation or business logic fails.
+
+`workflow_examples` now carries both fuller `preferred_*` examples and leaner
+`minimal_*` examples so tooling and humans can choose between a representative
+workflow call and the smallest valid call shape. Human template and dry-run
+summaries surface the preferred and minimal `params-json` examples too, not just
+the command lines.
+
+Common wrapper types such as `EntList`, `Vector`, `DoubleArray`, `IntegerArray`,
+`StringArray`, `VectorArray`, and `Property` are converted to structured JSON
+objects describing their contents. Structured object-like JSON responses include
+`schema_version` to make automation parsing contracts explicit.
+
+Input validation and escaping
+-----------------------------
+
+The CLI performs conservative validation to protect against malformed string input:
+
+- The CLI rejects null bytes and embedded control characters (newlines, tabs, carriage returns) in any string parameter.
+- Shell metacharacters are treated as normal literal characters in parameter values.
+- For JSON-derived parameters (``--params-json``/``--params-json-file``), shell metacharacter checks are not applied; only null bytes are rejected.
+- The CLI does not perform path normalization or otherwise rewrite values; valid values are passed through unchanged to the target call. If a callee requires a normalized path, normalize it before calling the CLI or perform normalization in your script.
+- JSON parameter payloads must be objects (mappings) with named arguments.
+- Methods that require positional-only parameters are not supported by CLI named-argument routing.
+- Duplicate/conflicting argument paths (for example ``param=1`` and ``param.attr=2``) are rejected.
+
+Recommended usage:
+
+- Quote or escape values containing spaces or shell characters:
+
+```sh
+moldflow invoke synergy.open_path path="C:\\path with spaces\\file.txt"
+```
+
+- For complex values or to avoid shell-escaping issues, prefer JSON input (``--params-json`` or ``--params-json-file``) and programmatic consumption of JSON output.
+
+See the [CLI documentation](https://autodesk.github.io/moldflow-api/cli.html) for more details.
+
+### Safety & testing notes
+
+The CLI performs careful introspection and validation to avoid accidental side effects:
+
+- `list` and `describe` only reflect on the Python API and do **not** start Synergy or any COM objects.
+- `invoke` validates required arguments and parses types before constructing wrapper instances, so malformed calls fail fast without launching the Synergy UI.
+
+Running the CLI tests
+
+The project includes a suite of unit tests for the CLI that mock the Synergy integration so the real application is never opened. To run the CLI tests locally:
+
+```sh
+python run.py test -m cli
+# or directly with pytest:
+python -m pytest tests/api/unit_tests -m cli -q
+```
+
+Test authors: when writing tests that might touch runtime objects or factories, always patch both:
+
+- `moldflow_cli.context.get_synergy`
+- `moldflow_cli.factories.get_synergy`
+
+This ensures neither the introspection nor the factory helpers attempt to talk to COM during tests.
+
 ## For Development
 
 ### 1. Clone the Repository

SECURITY.md

@@ -2,11 +2,14 @@
 
 ## Supported Versions
 
-We release patches for security vulnerabilities for the following versions:
-
-| Version | Supported          |
-| ------- | ------------------ |
-| 26.0.x  | :white_check_mark: |
+We release security patches for the latest major release and the immediately
+previous 3 major releases.
+
+To determine whether a release is supported, open the
+[repository releases](https://github.com/Autodesk/moldflow-api/releases) page
+and look at the release tag/version. Any release that belongs to the current
+major version or one of the previous 3 major versions is supported. Older major
+versions are no longer supported.
 
 ## Reporting a Vulnerability
 

docs/source/_static/switcher.json

@@ -1,9 +1,21 @@
 [
+  {
+    "version": "v27.1.0",
+    "name": "v27.1.0 (latest)",
+    "url": "../v27.1.0/",
+    "is_latest": true
+  },
+  {
+    "version": "v27.0.1",
+    "name": "v27.0.1",
+    "url": "../v27.0.1/",
+    "is_latest": false
+  },
   {
     "version": "v27.0.0",
-    "name": "v27.0.0 (latest)",
+    "name": "v27.0.0",
     "url": "../v27.0.0/",
-    "is_latest": true
+    "is_latest": false
   },
   {
     "version": "v26.0.5",