freecad-cli

A Python CLI tool for controlling FreeCAD from AI Agents via shell. Communicates with FreeCAD over XML-RPC (port 9875).

Architecture

flowchart TD
    A[AI Agent] -->|shell| B[freecad-cli<br/>Python CLI]
    B -->|XML-RPC<br/>localhost:9875| C[FreeCAD + Addon<br/>thin eval proxy]

Loading

The addon is a minimal XML-RPC server that runs inside FreeCAD. It only exposes ping and execute_code — all business logic lives in the CLI client. Once installed, the addon never needs to be updated. See docs/architecture.md for design rationale and docs/product-direction.md for the command philosophy.

Security note: execute-code runs arbitrary Python inside the FreeCAD process. The RPC server binds to 127.0.0.1 only — it is not accessible over the network. Only connect to a FreeCAD instance you control.

Setup

1. Install the CLI: uv tool install -e .
2. Install the FreeCAD addon: freecad-cli install-addon
3. Restart FreeCAD
4. Verify: freecad-cli ping

Usage

execute-code

The core command. Sends Python code to FreeCAD for execution.

# Inline code
freecad-cli execute-code 'print(FreeCAD.ActiveDocument.Name)'

# Read from a file
freecad-cli execute-code --file script.py

# Pipe from stdin
cat script.py | freecad-cli execute-code -
echo 'print(1+1)' | freecad-cli execute-code -

export

Export the active object to STL, STEP, or FCStd.

freecad-cli export stl -o output.stl
freecad-cli export step -o output.step --object MyBody
freecad-cli export fcstd -o model.FCStd

Other commands

freecad-cli ping
freecad-cli create-document MyDoc
freecad-cli active-document
freecad-cli screenshot --width 800

All commands return JSON output:

{"status": "ok", "data": true}

Agent Skills

Claude Code

Install as a Claude Code plugin:

/plugin marketplace add yoshikouki/freecad-cli
/plugin install freecad-cli@yoshikouki-freecad-cli

The plugin provides the /freecad-cli skill (setup, operation reference, troubleshooting) and a freecad-operator agent for CAD modeling tasks.

Other AI Agents

Copy and paste this prompt to your AI agent:

Install freecad-cli by following the setup guide at SETUP_AGENT.md in the repository: https://github.com/yoshikouki/freecad-cli. If any prerequisites are missing, ask me before installing them.

Development

Setup

uv sync
git config core.hooksPath .githooks

Install as a command

uv tool install -e .

Installed in editable mode — source code changes take effect immediately.

To uninstall:

uv tool uninstall freecad-cli

Test

uv run pytest