AI agents and scripts use the same commands as you
Every change to the drawing is a named command, such as wall.room_rect. Saving and export are commands too, such as export.pdf. The same commands run in the window's command line and in pirtocad-cli scripts, and the MCP server offers them to AI agents.
# Command line in the window (F2) wall.room_rect # Script in a terminal pirtocad-cli script room.jsonl # MCP server for an agent pirtocad-cli mcp
Three routes to the same commands
The window, the pirtocad-cli command-line tool and the MCP server share one command registry, so a command has the same ID and parameters on every route. A few commands work on one route only: a 3D view image, for example, can only be saved from the window.
Command line in the window
Press F2 and type a command ID, such as revision.delete, or the command's name in the command line below the drawing area. The command line asks for the required values one at a time, and name=value sets an optional one. Enter runs the command as a single undo step.
Scripts: pirtocad-cli
pirtocad-cli script FILE.jsonl runs the commands in a file, one JSON object per line. Every line gets a reply with either "ok": true and a result or "ok": false and an error. Each run starts from an empty session: open a project with project.open or create a new one first, and save your work at the end with project.save.
Agents: pirtocad-cli mcp
pirtocad-cli mcp is an MCP server (JSON-RPC) that talks to the agent over standard input and output. It offers every command as a tool with its parameters, and an automated test checks that no command is missing from the tool list. Chapter 11 of the user guide that ships with the app shows how to register the server. AI agents already draw in PirtoCAD through pirtocad-cli. Over MCP with a desktop AI app, only connecting and fetching the tool list have been tried so far; drawing has not. The tool list is about 3 MB, so the client must load tools on demand; not every client can.
Included in the package
- In the macOS package,
pirtocad-cliandpirtocad-mcpare inPirtoCAD.app/Contents/MacOS/.pirtocad-mcpis the same MCP server aspirtocad-cli mcp, as a standalone program. - An automated test checks that every toolbar tool has a matching command that an agent can use.
- The window's own actions, such as opening panels, are not drawing commands.
Example: a room, dimensions and a PDF
Save the lines as room.jsonl, point the paths to your own folder and run the file. Dimensions are in millimetres. The last line is shortened: the real reply also carries the sheets, a storey reference (storey_ref) and a list of changes, among other things.
# room.jsonl {"command":"project.new","params":{"name":"Esimerkkitalo","paper_mm":[420,297],"scale":50}} {"command":"storey.add","params":{"where":"top","copy_walls":false,"name":"Pohjakerros"}} {"command":"wall.room_rect","params":{"p1":[3000,3000],"p2":[10000,8500],"thickness":200}} {"command":"dimension.auto_insert","params":{}} {"command":"project.save","params":{"path":"/absolute/path/Esimerkkitalo.ifc"}} {"command":"export.pdf","params":{"path":"/absolute/path/Esimerkkitalo.pdf"}} # run, and the reply to line 2 (shortened) pirtocad-cli script room.jsonl {"command":"storey.add","line":2,"ok":true,"result":{"id":"floor-1"}}
What the lines do
- Create a new project on an A3 sheet (420 × 297 mm) at 1:50.
- Add a storey named Pohjakerros (ground floor).
- Draw a rectangular room with corner points (3000, 3000) and (10000, 8500): a 7 × 5.5 m rectangle with 200 mm walls.
- Insert dimensions automatically.
- Save the project as an IFC file and export the sheet to PDF.
Open the saved project with File > Open project… to see the same room with its dimensions in the window.
The agent sees what it does
An agent can test a change before making it, and after every command it is told what changed in the drawing.
| Safeguard | What it does |
|---|---|
| Check mode | The parameter check: true runs the command in a separate session and returns would_work, which says whether the command would succeed. The drawing, view, undo history, settings and clipboard stay as they were. Commands that write files, print or handle feedback cannot be tried in check mode. |
| Refusals give the reason | A refused command's reply gives the reason, the target object and the storey. Some refusals also carry numbers: when an opening does not fit its wall, the reply gives the measured value, the required value and the nearest value that fits. |
| Change report | With every reply the agent gets a list of the objects created, changed and deleted. When there are more than 200 changes, the list is fetched page by page. |
| One undo step | Every change to the drawing is one undo step. A batch (the batch command) run in all_or_nothing mode is kept only if every command in it succeeds, and the whole batch is one step. |
| Revision check | The parameter expect_revision refuses the command before anything happens if the project has changed since the given revision. |
Ask before you act
In check mode, an agent can run any command that changes the drawing. This line reports whether drawing the room would succeed, without changing the drawing:
{"command":"wall.room_rect","params":{"p1":[0,0],"p2":[4000,3000],"thickness":200,"check":true}}
The line assumes a session that already has a project and a storey, as after the first two lines of the example above. In an empty session the reply is would_work: false with the reason no project.
Files are not undone. Saving and export write files, and printing sends a job to the printer. Undo does not reverse them. That is why check mode and batches refuse commands that write files, print or handle feedback.
A person accepts the licence, not the agent. The tools open no project until the terms are accepted: start PirtoCAD and choose Accept (Hyväksy), or type pirtocad-cli accept-licence in a terminal yourself. The command reads the answer from the terminal and refuses an answer piped in.
The designer is responsible for the results. Check the agent's work yourself before the drawing goes any further.
Coming
These are in progress and not yet in the alpha:
- Starting an agent session from the window. Today an agent can attach to a project open in the window only when PirtoCAD is started from a terminal with
--agent-session. - A trial in which a desktop AI app draws in PirtoCAD through the MCP server, and a video of the agent at work
Every command, with its name and required parameters, is in the command reference. The program gives the same information: pirtocad-cli commands lists every command as JSON, pirtocad-cli commands --brief shows an example of each command and pirtocad-cli commands wall.chain shows the full schema of one command.
The video will be recorded once drawing through the MCP server has been tried.