OneCAD-Draft/docs/automation

Headless automation API

Open CAD Studio can run without a GUI and be driven over a line-based JSON protocol — for scripts, batch jobs, or AI agents.

OpenCADStudio --serve

It reads one JSON request per line on stdin and writes one JSON response per line on stdout. The active document persists across requests, so a caller can act → observe → act.

Protocol

Request	Response
{"op":"new"}	{"ok":true,"total":0,"by_type":{}}
{"op":"open","path":"plan.dwg"}	entity summary
{"op":"run","cmd":"LAYER Walls"}	{"ok":true,"cmd":...,"entities":N,"added":D}
{"op":"entities"}	{"ok":true,"total":N,"by_type":{"Line":42,...}}
{"op":"save","path":"out.dwg"}	{"ok":true,"saved":"out.dwg"} (path optional once opened/saved)

Every response has "ok"; failures carry "error". run drives Open CAD Studio's own command system — no separate bindings to maintain — so its coverage grows with the app.

Status (first increment): run applies synchronous commands (system variables, layer ops, …). Pick-based interactive commands (drawing by clicking points) need coordinate feeding and are not wired headless yet.

Python client

ocs.py is a ~100-line client — nothing to compile:

from ocs import Ocs

with Ocs(binary="OpenCADStudio") as ocs:   # spawns `--serve`
    ocs.open("plan.dwg")
    ocs.run("LAYER Walls")
    print(ocs.entities())
    ocs.save("plan_out.dwg")

Any language can speak the same protocol over a subprocess pipe.