# How to Run text-to-cad on Linux, macOS, and Windows: Complete Setup Guide

> Easily run text-to-cad on Linux, macOS, and Windows. Follow this complete setup guide to install Node.js, Python, clone the repository, and launch the tool.

- Repository: [earthtojake/text-to-cad](https://github.com/earthtojake/text-to-cad)
- Tags: how-to-guide
- Published: 2026-09-13

---

**To run text-to-cad on any operating system, install Node.js ≥16 and Python 3.9+, clone the earthtojake/text-to-cad repository, create a Python virtual environment, install dependencies with `pip install -r requirements-dev.txt` and `npm ci`, then register the skill with `npx skills add earthtojake/text-to-cad` and launch with `skills run cad`.**

text-to-cad is an open-source collection of agent skill packages that generate, inspect, and visualize CAD geometry from natural language prompts. This guide explains how to run text-to-cad on different operating systems using the repository's hybrid Python and Node.js runtime architecture.

## Prerequisites for All Platforms

Before installing text-to-cad, ensure your system meets these requirements:

- **Node.js LTS** (version 16 or higher)
- **Python 3.9+** with `venv` module support
- **Git** for cloning the repository

The repository combines a Python backend for geometric computation with a Node.js frontend for the CAD viewer interface.

## Installing text-to-cad on Linux and macOS

POSIX systems use similar terminal commands for setup. The installation process relies on the [`scripts/install/install-skills.sh`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/install/install-skills.sh) helper to register skills with the CLI.

1. **Clone the repository**:

```bash
git clone https://github.com/earthtojake/text-to-cad.git
cd text-to-cad

```

2. **Create and activate a Python virtual environment**:

```bash
python3 -m venv .venv
source .venv/bin/activate

```

3. **Install Python dependencies**:

```bash
pip install -r requirements-dev.txt

```

This file pins the correct `cadgen` version required by the `packages/cadgen` runtime.

4. **Install Node dependencies**:

```bash
npm ci

```

This command installs the JavaScript CAD library located in `packages/cadgen-js/` and ensures a reproducible Node environment as documented in [`packages/cadgen-js/README.md`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadgen-js/README.md).

5. **Register the skill with the Skills CLI**:

```bash
npx skills add earthtojake/text-to-cad

```

6. **Launch a CAD generation task**:

```bash
skills run cad "cube size=10"

```

This command spawns the `cadgen.viewer` backend and opens `http://localhost:3000` in your default browser.

## Installing text-to-cad on Windows

Windows installation follows the same logical steps but uses PowerShell syntax for path handling and virtual environment activation.

1. **Clone the repository**:

```powershell
git clone https://github.com/earthtojake/text-to-cad.git
Set-Location text-to-cad

```

2. **Create and activate a virtual environment**:

```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1

```

3. **Install Python and Node dependencies**:

```powershell
pip install -r requirements-dev.txt
npm ci

```

4. **Register and run the skill**:

```powershell
npx skills add earthtojake/text-to-cad
skills run cad "cylinder radius=5 height=20"

```

The viewer backend starts automatically and launches your browser to the local interface.

## Alternative Installation via AI Agent Plugins

If you use **Codex**, **Claude**, or **Grok** instead of the standalone Skills CLI, install text-to-cad using these platform-specific commands. All methods ultimately register the same skill definitions found in the repository's skill package.

### Codex Plugin Installation

```bash
codex plugin marketplace add earthtojake/text-to-cad
codex plugin add cad@text-to-cad

```

### Claude Plugin Installation

```bash
claude plugin marketplace add earthtojake/text-to-cad
claude plugin install cad@text-to-cad

```

### Grok Plugin Installation

```bash
grok plugin install earthtojake/text-to-cad --trust

```

After installation through any plugin, invoke skills using the standard `skills run cad "your prompt here"` syntax.

## Running CAD Generation Commands

Once installed, use the `skills run` command to generate geometry. The system processes natural language through the Python runtime in `packages/cadgen/` and renders results via the viewer application in `apps/viewer/`.

**Create a 3D box with specific dimensions**:

```bash
skills run cad "box width=15 height=5 depth=8"

```

**Export a model to GLB format**:

```bash
skills run cad "box width=10 height=2 depth=4 export=glb"

```

This writes `output.glb` to your current working directory using the export functionality defined in the CAD generation pipeline.

**Generate a DXF mesh with layers**:

```bash
skills run dxf "circle radius=4 layers=top,bottom"

```

## Understanding the Repository Structure

Key files and directories referenced during installation:

- **[`requirements-dev.txt`](https://github.com/earthtojake/text-to-cad/blob/main/requirements-dev.txt)** – Pins Python dependencies including the `cadgen` package version required for geometric operations
- **[`packages/cadgen/README.md`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadgen/README.md)** – Documents the Python + Node hybrid runtime architecture
- **[`packages/cadgen-js/README.md`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadgen-js/README.md)** – Describes the JavaScript CAD renderer and geometry library
- **[`scripts/install/install-skills.sh`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/install/install-skills.sh)** – Automates skill registration with the local CLI
- **[`apps/viewer/README.md`](https://github.com/earthtojake/text-to-cad/blob/main/apps/viewer/README.md)** – Contains instructions for launching the CAD Viewer backend and client interface

The `cadgen.viewer` module mentioned in the raw analysis serves as the bridge between the Python geometry engine and the browser-based visualization interface.

## Summary

- Install **Node.js ≥16** and **Python 3.9+** before attempting setup on any OS
- Use `source .venv/bin/activate` on Linux/macOS or `.\.venv\Scripts\Activate.ps1` on Windows to activate the Python environment
- Install dependencies via `pip install -r requirements-dev.txt` and `npm ci` to satisfy both runtime requirements
- Register the skill using `npx skills add earthtojake/text-to-cad` or equivalent plugin commands for Codex, Claude, or Grok
- Launch generation with `skills run cad "your description"` to automatically start the backend viewer at `localhost:3000`
- Generated files export to your current directory when using the `export=glb` or similar parameters

## Frequently Asked Questions

### What are the exact Node.js and Python version requirements for text-to-cad?

text-to-cad requires **Node.js LTS version 16 or higher** and **Python 3.9 or newer** with the `venv` module available. These versions ensure compatibility with the `packages/cadgen-js` JavaScript library and the Python geometric computation backend. Earlier versions may fail during the `npm ci` or `pip install` steps due to dependency conflicts.

### Can I run text-to-cad on Windows without using PowerShell?

Yes, you can use **Git Bash** or the standard **Command Prompt (cmd.exe)** instead of PowerShell. In Git Bash, use the same POSIX commands as Linux (`source .venv/bin/activate`). In Command Prompt, activate the virtual environment with `.venv\Scripts\activate.bat` instead of the PowerShell script. The `npx` and `skills` commands function identically across all Windows shell environments.

### How do I uninstall the text-to-cad skill from my system?

Run the uninstall script provided in the repository or use the reverse of your installation method. For Skills CLI installations, execute `npx skills remove earthtojake/text-to-cad`. If you used the [`scripts/install/install-skills.sh`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/install/install-skills.sh) helper during setup, the companion [`scripts/install/uninstall-skills.sh`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/install/uninstall-skills.sh) script removes all registered skills and cleans up local cache directories.

### Where does text-to-cad store generated CAD files?

By default, exported files write to your **current working directory** where you executed the `skills run` command. When you include `export=glb` or similar parameters in your prompt, the Python backend in `packages/cadgen/` handles file I/O and saves outputs relative to the shell's active directory. The viewer interface at `localhost:3000` displays previews but does not permanently store geometry unless you explicitly export.