pyaedt-cli

name pyaedt-cli description Use when interacting with ANSYS AEDT through the current PyAEDT CLI. Triggers on requests to start or inspect AEDT sessions, manage projects, create designs, run scripts, export screenshots or configurations, or use the PyAEDT command line from the workspace virtual environment. PyAEDT CLI skill You have access to the pyaedt CLI to interact with ANSYS Electronics Desktop (AEDT). This skill teaches you how to use it effectively. Pre-flight check (run first) Before any CLI command, verify pyaedt is installed: pyaedt --json version If the command fails, stop, and instruct the user to install it first using the all installation target to enable full capabilities. pip install pyaedt[all] Invoking the CLI Before running any command, resolve the pyaedt binary once: Try pyaedt directly. If it is on the system PATH, use it as-is. If not found, fall back to the venv-local binary in the current working directory: Windows: .venv\Scripts\pyaedt Linux/macOS: .venv/bin/pyaedt All examples use pyaedt for brevity. Replace it with the resolved path if needed. Working directory for generated artifacts Use temporary directories for all exports and generated files unless the user specifies otherwise. Rules: Create a task-specific subdirectory under the OS temp directory Use tempfile.mkdtemp(prefix="pyaedt-skill-") (Python), $env:TEMP (Windows), or ${TMPDIR:-/tmp} (Linux/macOS) Do not write to the repository or arbitrary folders unless explicitly requested Move artifacts from temp only after successful export if the user wants to keep them Quick reference: import tempfile temp_dir = tempfile.mkdtemp(prefix= "pyaedt-skill-" ) Pass this path to --path or --output in export commands. Use --json for non-interactive commands Use --json for every non-interactive command so output stays structured and machine-parseable. JSON output returns: {"status": "ok", "data": {...}} or {"status": "error", "error": "message"} Always parse the status field before using data . Never rely on human-readable output. Exceptions: session attach launches an interactive console, so human mode is acceptable. doc commands open browser pages and are not usually consumed as structured automation output. Current CLI shape Commands are organized as: pyaedt [--json] <group> < command > [options] Available groups in the current CLI: session project script export test-config panels doc Top-level commands: version aedt-versions Do not invent other command groups or commands that do not exist in the current CLI. If a required operation is not supported by the CLI, report that to the user instead of trying to work around it. Port-based model The current CLI is primarily port-based. session start launches a new AEDT instance and returns its gRPC port. session list discovers running AEDT instances. Most operational commands require --port explicitly. session attach can also be used to select an existing AEDT session, including by --project or --design , so not every workflow starts from a known port. There is no persisted session connect state to reuse later. Practical implication: # Discover or start AEDT pyaedt --json session list pyaedt --json session start --version 2026.1 --non-graphical # Then pass --port to the command you want pyaedt --json project list --port 50051 pyaedt --json run my_script.py --port 50051 Project and design resolution rules Design-scoped commands use one shared resolution rule set. This is important and should be applied consistently in guidance and examples. Commands affected: export screenshot export config session attach when used with --project or --design Resolution rules: If both --project and --design are provided, use them directly. If only --project is provided, that project must contain exactly one design. If only --design is provided, exactly one project must be open. If neither is provided, there must be exactly one open project and exactly one design in it. If the selection is ambiguous, the command fails and the missing selector must be provided. When helping a user, do not describe this behavior as "active project" or "active design" fallback unless the command actually uses that behavior. The intended behavior is uniqueness-based resolution. Command reference Top-level commands Command Description pyaedt --json version Display the PyAEDT version pyaedt --json aedt-versions List installed AEDT versions on the machine Session management Command Description pyaedt --json session start --version 2026.1 [--port 50051] [--non-graphical] Start a new AEDT instance pyaedt --json session list List running AEDT instances with PID, version, and port pyaedt --json session stop --port 50051 Stop a specific AEDT instance by port pyaedt --json session stop --all Close all AEDT instances. pyaedt session attach [--port 50051] [--project NAME] [--design NAME] Launch an interactive PyAEDT console attached to a running instance Notes: session attach can work interactively if --port is omitted and the user selects an instance. --project or --design with session attach only works for gRPC instances with a usable port. Project commands Port is required for all project commands to specify which AEDT instance to target. Command Description pyaedt --json project list --port 50051 List all open projects and their designs pyaedt --json project open "C:/path/to/file.aedt" --port 50051 [--non-graphical] Open an AEDT project file pyaedt --json project save --port 50051 [--path "C:/new/file.aedt"] Save the active project, optionally as a new file pyaedt --json project create --name ProjectA --port 50051 Create a project . Use --name . pyaedt --json project create --project ProjectA --design Design1 --type Hfss --port 50051 Create a design inside an existing project. Use --project + --design + --type . pyaedt --json project close --port 50051 [--project ProjectA] Close a project, or the active project if omitted project create behavior: --name is for project creation. --project + --design + --type is for design creation. Do not mix --name with --design / --type . Supported --type values: Hfss Maxwell2d Maxwell3d Q3d Q2d Icepak Circuit TwinBuilder Mechanical Emit Rmxprt Hfss3dLayout MaxwellCircuit Script commands Command Description pyaedt --json run "path/to/script.py" --port 50051 Execute a Python script inside AEDT Export commands Command Description pyaedt --json export screenshot --port 50051 [--path preview.jpg] [--project NAME] [--design NAME] Capture a screenshot for a resolved design pyaedt --json export config --port 50051 [--output config.json] [--project NAME] [--design NAME] [--overwrite] Export a design configuration JSON Both commands are design-scoped and therefore follow the shared project/design resolution rules above. Documentation Command Description pyaedt doc Open the docs home page and print help pyaedt doc examples Open the examples section pyaedt doc github Open the GitHub repository pyaedt doc user-guide Open the user guide pyaedt doc getting-started Open getting started docs pyaedt doc installation Open installation docs pyaedt doc api Open API reference pyaedt doc changelog [VERSION] Open the changelog pyaedt doc issues Open the issues page pyaedt doc search <keywords> Search the online documentation Common workflows Workflow 1: Discover or start AEDT # Check for running instances pyaedt --json session list # If none are running, start one pyaedt --json session start --version 2026.1 --non-graphical Decision rule: If session list returns no processes, start AEDT. If it returns one process, reuse that port. If it returns multiple processes, ask the user which port to use. Workflow 2: Inspect projects on a port pyaedt --json project list --port 50051 Use this first when you need to understand which project and design selectors are required. Workflow 3: Create a project or a design # Create a project. Use --name ONLY (do NOT add --design or --type) pyaedt --json project create --name "PatchAntenna" --port 50051 # Create a design in an existing project. Use --project + --design + --type ONLY (do NOT add --name) pyaedt --json project create --project "PatchAntenna" --design "HFSSDesign1" -- type Hfss --port 50051 Workflow 4: Interactive exploration with session attach Use session attach as the first choice when the user wants to explore, debug, or iterate on a design interactively. It opens an interactive Python console that is already connected to the target AEDT session. desktop is pre-injected, so PyAEDT commands can be issued one by one without writing a full script. # Attach to a running instance (port optional; prompts if omitted) pyaedt session attach --port 50051 # Inside the interactive Python console, the session is already live: # >>> import ansys.aedt.core as aedt # >>> hfss = aedt.Hfss(new_desktop=False, port=50051) # >>> box = hfss.modeler.create_box([0, 0, 0], [10, 10, 10], name="MyBox") # >>> hfss.modeler["MyBox"].color = (255, 0, 0) Sending multi-line code to the interactive Python console When the agent sends code to the interactive Python console that spans more than one line (loops, conditionals, function definitions, etc.), pasting it directly causes an IndentationError or SyntaxError because the console treats each line as a separate input. Always wrap multi-line blocks in exec() , encoding all newlines as \n inside a single string: # Fails because the console breaks on the loop body for i in range ( 3 ): print (i) # Correct: send as a single exec() call exec ( "for i in range(3):\n print(i)" ) Rules: Use exec() for any block that contains indented code (loops, if , with , function or class definitions). Single-statement lines (imports, assignments, function calls) do not need exec() . Escape all inner double-quotes as \" if the outer delimiter is " , or use concatenated string literals as shown above. Keep exec() calls as short as possible; if the block grows beyond ~10 lines prefer saving a temp script and using run instead. When to prefer session attach command over run command: Situation Preferred approach Exploring design state, unknown goal session attach Debugging a failing step interactively session attach One-off geometry / parameter tweaks session attach Iterating quickly on a few commands session attach Defined, repeatable, multi-step workflow run CI / headless / automated pipeline run Workflow has more than ~5 steps run Traceability and logging required run Prefer session attach first. Graduate to run only once the workflow is known and needs to be repeatable or automated. Working with multiple designs simultaneously When the user needs to work on more than one design at the same time , open a separate interactive Python console for each design instead of switching designs inside a single console. This keeps every design live and editable without closing or releasing any of them. # Terminal 1: console for Design A pyaedt session attach --port 50051 --project "ProjectA" --design "DesignA" # Terminal 2: console for Design B (same or different project) pyaedt session attach --port 50051 --project "ProjectA" --design "DesignB" # Terminal 3: console for a design in a different project pyaedt session attach --port 50051 --project "ProjectB" --design "DesignC" Rules: Each console holds its own PyAEDT object bound to a specific design. Closing one console does not close the others. All consoles share the same AEDT instance (same --port ), so changes made in one are visible in AEDT immediately. Do not call desktop.release_desktop() or aedt_app.release_desktop() inside any of these consoles unless you intentionally want to shut down AEDT for all open consoles. If the designs live in different AEDT instances, use the matching --port for each console. Workflow 5: Run automation pyaedt --json run "<temp-dir>/setup_antenna.py" --port 50051 Workflow 6: Generated script execution Use this workflow whenever a script has been generated and must be run automatically. # Step 1: discover instances pyaedt --json session list # Step 2: if needed, start one pyaedt --json session start --version 2026.1 --non-graphical # Step 3: run the script on the chosen port pyaedt --json run "<temp-dir>/generated_script.py" --port 50051 Rules: Always determine the target port first. If multiple instances are running, present the full list and ask which port to use. Do not tell the user to run the generated script manually if the workflow requires automatic execution. Generated scripts intended for an existing AEDT instance should use new_desktop=False . Workflow 7: Export design data # If the instance has exactly one project and one design, selectors can be omitted pyaedt --json export screenshot --port 50051 --path "<temp-dir>/preview.jpg" pyaedt --json export config --port 50051 --output "<temp-dir>/config.json" --overwrite # If ambiguous, specify the missing selector(s) pyaedt --json export screenshot --port 50051 --project "PatchAntenna" --design "HFSSDesign1" --path "<temp-dir>/preview.jpg" Error handling Always parse the status field in JSON output before using data :