/freecad/agent-harness/FREECAD.md

FreeCAD CLI Harness — Standard Operating Procedure

Software Overview

FreeCAD is an open-source parametric 3D CAD modeler built on OpenCASCADE (OCCT). It supports Part design, Sketcher, Assembly, TechDraw, Mesh, and many other workbenches.

This harness targets FreeCAD 1.1 (released March 2026) with 258 commands across 18 workbench groups.

• Backend engine: OpenCASCADE Technology (OCCT)
• Native format: .FCStd (ZIP containing Document.xml + BREP geometry files)
• Python API: FreeCAD (App) module — full document/object manipulation
• Headless mode: freecadcmd or freecad -c — runs without GUI
• Macro execution: freecadcmd script.py — executes Python macro headlessly
• Export formats: STEP, IGES, STL, OBJ, DXF, SVG, PDF (via TechDraw)

Architecture

┌──────────────────────────────────────────────────────┐
│  cli-anything-freecad (CLI + REPL)                   │
│  ┌──────────────┐  ┌──────────────┐  ┌────────────┐ │
│  │ document.py   │  │ parts.py     │  │ sketch.py  │ │
│  │ create/save   │  │ primitives   │  │ 2D shapes  │ │
│  └──────────────┘  └──────────────┘  └────────────┘ │
│  ┌──────────────┐  ┌──────────────┐  ┌────────────┐ │
│  │ body.py       │  │ materials.py │  │ export.py  │ │
│  │ pad/pocket    │  │ PBR mats     │  │ STEP/STL   │ │
│  └──────────────┘  └──────────────┘  └────────────┘ │
│  ┌──────────────┐                                    │
│  │ session.py    │  ← undo/redo, state management    │
│  └──────────────┘                                    │
├──────────────────────────────────────────────────────┤
│  freecad_macro_gen.py — generates FreeCAD macros     │
│  freecad_backend.py   — invokes FreeCAD headless     │
├──────────────────────────────────────────────────────┤
│  FreeCAD (freecadcmd) — the REAL software            │
│  OpenCASCADE — geometry kernel                       │
└──────────────────────────────────────────────────────┘

Data Model

The CLI maintains project state as a JSON document:

{
    "version": "1.0",
    "name": "my_project",
    "units": "mm",
    "parts": [
        {
            "id": 0,
            "name": "Box",
            "type": "box",
            "params": {"length": 10, "width": 10, "height": 10},
            "placement": {"position": [0, 0, 0], "rotation": [0, 0, 0]},
            "material_index": null,
            "visible": true
        }
    ],
    "sketches": [],
    "bodies": [],
    "materials": [],
    "metadata": {
        "created": "2026-03-22T...",
        "modified": "2026-03-22T...",
        "software": "cli-anything-freecad 1.1.0"
    }
}

Command Groups

Group	Commands
document	new, open, save, info, profiles
part	add, remove, list, get, transform, boolean
sketch	new, add-line, add-circle, add-rect, constrain, close
body	new, pad, pocket, fillet, chamfer, list
material	create, assign, list, set
export	render, info, presets
session	undo, redo, status, history
draft	wire, rectangle, circle, polygon, fillet-2d, shapestring, ...
assembly	new, add-part, constrain, solve, insert-part, create-simulation, ...
techdraw	new-page, add-view, add-annotation, export-pdf, ...
mesh	import, from-shape, export, repair, decimate, ...
fem	new-analysis, mesh-generate, solve, add-beam-section, add-tie, ...
cam	new-job, add-profile, add-tapping, set-tool, generate-gcode, ...
measure	distance, length, angle, area, volume, check-geometry, ...
import	auto, step, iges, stl, obj, dxf, brep, 3mf, ...
surface	filling, sections, extend, blend-curve, sew, cut
spread	new, set-cell, get-cell, set-alias, import-csv, export-csv

FreeCAD 1.1 Changes

Breaking: Datum/Origin Redesign

FreeCAD 1.1 replaces the legacy Origin object with LocalCoordinateSystem. Use body local-coordinate-system to create configurable coordinate systems with cross-workbench attachment support. Datum planes, lines, and points now support --attachment-mode and --attachment-refs for flexible positioning.

Note: Files created with FreeCAD 1.1 are NOT backward-compatible with 1.0.

New Features by Workbench

• PartDesign: Whitworth threads (BSW/BSF/BSP/NPT), tapered holes, feature freeze toggle
• Assembly: Inline part insertion, joint motion simulation
• CAM: G84/G74 tapping, multi-pass profiles, new tool library system
• FEM: Netgen refinement, beam sections (box/elliptical), tie constraints, result purging
• Sketcher: Projection/reference modes, plane intersection, face-based external geometry
• Draft: Edge-selective fillet, relative font paths
• TechDraw: Area annotations with hole accounting, shape validation
• Measure: Enhanced check-geometry with valid entries, additive measurements

Rendering Pipeline

1. Build JSON state via CLI commands (document, part, sketch, body, material)
2. Generate FreeCAD macro from JSON state (freecad_macro_gen.py)
3. Execute macro headlessly via freecadcmd script.py
4. Export output (STEP, IGES, STL, OBJ) from the generated .FCStd document
5. Verify output (file exists, size > 0, correct format magic bytes)

FreeCAD Python API Reference

import FreeCAD
import Part

# Document management
doc = FreeCAD.newDocument("MyProject")
doc.saveAs("/path/to/project.FCStd")

# Primitives
box = doc.addObject("Part::Box", "MyBox")
box.Length = 10
box.Width = 10
box.Height = 10

cyl = doc.addObject("Part::Cylinder", "MyCylinder")
cyl.Radius = 5
cyl.Height = 20

sphere = doc.addObject("Part::Sphere", "MySphere")
sphere.Radius = 10

cone = doc.addObject("Part::Cone", "MyCone")
cone.Radius1 = 10
cone.Radius2 = 5
cone.Height = 15

torus = doc.addObject("Part::Torus", "MyTorus")
torus.Radius1 = 10
torus.Radius2 = 3

# Boolean operations
cut = doc.addObject("Part::Cut", "Cut")
cut.Base = box
cut.Tool = cyl

fuse = doc.addObject("Part::Fuse", "Fuse")
fuse.Base = box
fuse.Tool = cyl

common = doc.addObject("Part::Common", "Common")
common.Base = box
common.Tool = cyl

# Placement
import FreeCAD
box.Placement = FreeCAD.Placement(
    FreeCAD.Vector(x, y, z),
    FreeCAD.Rotation(FreeCAD.Vector(0, 0, 1), angle_degrees)
)

# Export
Part.export([box, cyl], "/path/to/output.step")
Part.export([box], "/path/to/output.stl")

# Recompute
doc.recompute()

Dependencies

• FreeCAD (system package) — HARD DEPENDENCY
  • Windows: Download from freecad.org
  • Linux: apt install freecad or snap install freecad
  • macOS: brew install --cask freecad
• Python 3.10+
• click >= 8.0 (CLI framework)
• prompt-toolkit >= 3.0 (REPL)