Pymapdl CLI
Apps & Automationpymapdl-cliPymapdl CLI is an Agent Skill for apps & automation published in the ansys/pymapdl repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
How to use the PyMAPDL command-line interface to start, stop, list, and execute commands on MAPDL instances from a terminal. Use this skill whenever the user wants to control MAPDL from the command line, run APDL commands via the shell, manage running MAPDL processes, script MAPDL workflows without writing Python, or pipe APDL into a running solver — even if they don't explicitly say "CLI".
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/ansys/pymapdl/blob/HEAD/src/ansys/mapdl/core/skills/pymapdl-cli/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/pymapdl-cli, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
PyMAPDL CLI
The pymapdl CLI lets you manage MAPDL instances and execute APDL commands
directly from the terminal. It is installed automatically with the
ansys-mapdl-core Python package and requires the click dependency (included
by default).
A typical session looks like this:
pymapdl start # launch a solver instance
pymapdl exec -c /prep7 -c "K,1,0,0,0" # send commands to it
pymapdl exec --file model.inp # or send a whole script
pymapdl stop # shut it down
All commands print human-readable output to stdout and errors to stderr. Exit code is 0 on success, 1 on failure.
Commands at a glance
| Command | Purpose |
|---|---|
pymapdl start | Launch a new local MAPDL instance |
pymapdl stop | Kill one or all running instances |
pymapdl list | Show running MAPDL processes |
pymapdl exec | Send APDL commands to a running instance |
pymapdl convert | Translate an APDL script to Python |
pymapdl start
Launch a new MAPDL gRPC server. Prints the IP, port, and PID on success.
pymapdl start [OPTIONS]
Key options
| Option | Default | Description |
|---|---|---|
--port | 50052 (or PYMAPDL_PORT) | gRPC port; first available port at or after this value |
--exec_file | auto-detected | Path to the MAPDL executable |
--run_location | temp dir | Working directory for the MAPDL process |
--jobname | file | MAPDL jobname |
--nproc | 2 | Number of processors |
--ram | all available | Fixed memory in MB |
--override | off | Delete stale lock files before starting |
--additional_switches | none | Extra MAPDL command-line switches (e.g. aa_r for academic license) |
--start_timeout | 45 | Seconds to wait for the server to become ready |
--license_type | none | License name (e.g. meba, ansys) or description (e.g. enterprise) |
--version | latest | MAPDL version to launch (e.g. 241, 24.1) |
Example — start on a custom port with 4 CPUs:
pymapdl start --port 50055 --nproc 4
# Success: Launched an MAPDL instance (PID=12345) at 127.0.0.1:50055
pymapdl stop
Stop running MAPDL instances. By default targets port 50052.
pymapdl stop [OPTIONS]
Options
| Option | Description |
|---|---|
--port PORT | Stop instances listening on this port |
--pid PID | Stop the process (and its children) with this PID |
--all | Stop every MAPDL instance on the machine |
Examples:
pymapdl stop # stop instance on default port 50052
pymapdl stop --port 50055 # stop instance on port 50055
pymapdl stop --pid 12345 # stop a specific process tree
pymapdl stop --all # stop all MAPDL processes
pymapdl list
List MAPDL processes currently running on the machine.
pymapdl list [OPTIONS]
Options
| Option | Short | Description |
|---|---|---|
--instances | -i | Show only parent instances (hide child processes) |
--long | -l | Show all columns (command line + working directory) |
--cmd | -c | Include the command-line column |
--location | -cwd | Include the working-directory column |
Example:
pymapdl list -i
# Name Status gRPC port PID
# ANSYS241.exe running 50052 41644
pymapdl exec
Send APDL commands to an already running MAPDL instance and print the
solver output. This command never starts a new instance — use pymapdl start
first.
pymapdl exec [OPTIONS] [-]
Three input modes (mutually exclusive)
-
Repeated
-c/--command(recommended for scripting and LLM use):pymapdl exec -c /prep7 -c "BLOCK,0,1,0,1,0,1" -c SAVEEach
-cvalue is one APDL command. They are joined with newlines and sent as a singleinput_strings()block for maximum performance. -
File with
--file/-f:pymapdl exec --file model.inp -
Stdin by passing
-as a positional argument:# Linux / macOS cat model.inp | pymapdl exec - # Windows PowerShell Get-Content model.inp | pymapdl exec -
Options
| Option | Short | Default | Description |
|---|---|---|---|
--command | -c | — | APDL command (repeatable) |
--file | -f | — | Path to an APDL script file |
--port | — | 50052 (or PYMAPDL_PORT) | gRPC port of the target instance |
--ip | — | 127.0.0.1 (or PYMAPDL_IP) | IP of the target instance |
--timeout | — | 10 | Connection timeout in seconds |
--clear-on-connect | — | off | Clear MAPDL database before sending commands |
Behavior notes
- Successive calls share state. Because
--clear-on-connectis off by default, you can split a workflow across multiplepymapdl execinvocations and the model/mesh/results persist between them. - Output goes to stdout, errors to stderr — ideal for piping, logging, or LLM consumption.
- Windows paths are safe. Backslash sequences like
C:\new\fileare preserved verbatim; no mangling occurs.
pymapdl convert
Convert an APDL script to a PyMAPDL Python script.
pymapdl convert [OPTIONS]
Key options
| Option | Short | Default | Description |
|---|---|---|---|
--file | -f | stdin | APDL input file |
--output | -o | stdout | Output Python file |
--macros_as_functions | -mf | True | Convert macros to Python functions |
--use_function_names | -fn | True | Use method names (mapdl.k) instead of mapdl.run('K') |
--only_commands | -oc | off | Emit only MAPDL calls (no imports/header/exit) |
--add_imports | -ai | True | Add launch_mapdl() boilerplate |
--comment_solve | -cs | off | Comment out SOLVE / /EOF lines |
Example:
pymapdl convert -f model.inp -o model.py
Environment variables
| Variable | Used by | Purpose |
|---|---|---|
PYMAPDL_PORT | start, exec | Default gRPC port when --port is omitted |
PYMAPDL_IP | exec | Default IP when --ip is omitted |
PYMAPDL_MAPDL_EXEC | start | Path to MAPDL executable |
Common workflows
Interactive modeling session
pymapdl start --port 50055
pymapdl exec --port 50055 -c /prep7
pymapdl exec --port 50055 -c "ET,1,186" -c "BLOCK,0,1,0,1,0,1" -c "VMESH,ALL"
pymapdl exec --port 50055 --file boundary_conditions.inp
pymapdl exec --port 50055 -c /solu -c SOLVE
pymapdl stop --port 50055
Run a full script in one shot
pymapdl start
pymapdl exec --file full_model.inp
pymapdl stop
Pipe commands from another tool
# Generate APDL dynamically and pipe it in
python generate_mesh.py | pymapdl exec -
Fresh database each time
pymapdl exec --clear-on-connect -c /prep7 -c "K,1,0,0,0"