dcad 0.1.0

Text to CAD from your terminal — generate real STEP/STL/3MF/GLB files from plain-language descriptions.

dcad

Text to CAD from your terminal. Connect an LLM API key, pick a working folder, and describe what you want to build — dcad generates real CAD files (STEP, STL, 3MF, GLB) on disk.

Status: Milestone 2. dcad run "your prompt" sends your description to the configured LLM, which writes a build123d script, runs it through vendored cadpy (skills/cad/scripts/step), and retries on failure.

How it works

Before writing any code, the configured LLM produces a CAD brief (persisted as brief.md) — dimensions, units, features, and a small set of machine-checkable validation targets derived from your prompt. It then writes build123d — a Python parametric CAD library built on the OpenCASCADE kernel — which is executed via cadpy to produce a STEP file and optional sidecar exports (STL, 3MF, GLB).

The result is checked against the brief's validation targets (bounding box, face/solid count). When enabled, a rendered snapshot (snapshots/*.png) is also reviewed by the same LLM; that visual review is advisory — deterministic checks decide pass/fail, and vision findings are logged without blocking acceptance when validation passes. Deterministic failures are classified and repaired per the vendored skills/cad/references/repair-loop.md — the LLM reads the failure output, classifies it, and applies the smallest source fix before rerunning.

CAD tools (upstream-shaped CLI)

dcad mirrors the earthtojake/text-to-cad skill tool layout:

dcad run "your prompt"     # full SKILL.md workflow (primary UX)
dcad step model.py -o model.step --stl model.stl
dcad inspect refs model.step --facts --planes --positioning
dcad snapshot model.step   # Playwright snapshots (requires `.model.step.glb` sidecar)
dcad open step|stl|recent  # open artifacts with your OS default app

The vendored skill lives at skills/cad/ (see skills/cad/UPSTREAM_SHA for the pinned commit).

Install

pipx install dcad

Requires Python 3.11–3.14. pipx keeps dcad and its dependencies (including the OpenCASCADE binding) isolated from your other Python projects.

If pipx is not installed yet:

brew install pipx
pipx ensurepath

First release: dcad is published to PyPI when a GitHub release is cut. Until then, install from a built wheel with pipx install /path/to/dcad-*.whl or follow the source setup below.

From source (contributors):

git clone https://github.com/HumfDev/derive-cad.git
cd derive-cad
bash scripts/setup-dev.sh
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

Do not also run pip install -e packages/cadpy — dcad already pulls in the vendored cadpy via pyproject.toml. Installing both in one command makes pip treat them as conflicting requirements.

Note: dcad vendors earthtojake/text-to-cad's skills/cad/ workflow and packages/cadpy. STEP generation and inspection use skills/cad/scripts/step and skills/cad/scripts/inspect. OpenCASCADE comes via cadquery-ocp (~60MB per platform). Alpine/musl Docker images are not supported; use python:3.12-slim or similar glibc base images.

Quickstart

dcad run "design a phone stand with 45 degree angle"

On first use, dcad run launches an interactive setup wizard (LLM provider, model dropdown, API key, working folder) and immediately generates your model. Reconfigure any time with dcad init.

dcad run creates a named design folder directly in your working directory — for example ~/derivecad-projects/phone-stand/model.stl. The folder name is generated by your configured LLM from your prompt (falls back to a slug if naming fails). Each design folder contains model.step, your configured export formats (default: model.stl), the generated Python source, brief.md (the CAD brief the model wrote before coding), snapshots/*.png (the rendered views used for visual review), and stdout/stderr logs. Open the latest outputs with:

dcad open stl      # open the most recent STL in your default viewer
dcad open step     # open the most recent STEP file
dcad open recent   # open the most recent run folder in Finder/Files

Supported open targets: step, stl, 3mf, glb, py, recent.

Browse and run any command interactively:

dcad commands

Supported LLM providers

Provider	Env var	Notes
OpenAI	OPENAI_API_KEY
Anthropic	ANTHROPIC_API_KEY
Gemini	GEMINI_API_KEY
Groq	GROQ_API_KEY
Ollama	(none)	Local, no API key required.
Other	(you choose)	Any litellm-supported model string + env var.

API keys are stored in your OS keychain via keyring. If no OS keychain backend is available (common in CI/containers/headless Linux), dcad init falls back to ~/.derivecad/credentials.toml (mode 600) and warns you that this is less secure. An already-set environment variable always takes precedence over stored config.

Supported output formats

STEP, STL, 3MF, GLB.

Configuration

• Global config: ~/.derivecad/config.toml
• Per-project override: .derivecad.toml in your working folder
• Precedence: CLI flags > per-project config > env vars (API keys only) > global config > defaults
• enable_snapshot_review (default true): set to false to skip rendering and reviewing a snapshot of each result — the release valve if the extra LLM call's cost/latency isn't worth it for your use case. When enabled, vision findings are logged but do not block acceptance if deterministic validation already passed. Vision review is also automatically skipped (and reported as such) for models with no known vision support.
• bbox_tolerance_pct (default 15.0): tolerance applied to a brief's bounding-box validation targets before a mismatch is treated as a failure.

Contributing

See CONTRIBUTING.md.

License

MIT