How to Perform Inspection Tasks with cadgen: A Complete CLI and API Guide

The cadgen package ships a powerful command-line interface for inspecting CAD models, exposing functionality through the cadgen step inspect command with sub-commands for reference parsing, frame extraction, measurement, alignment, and differential analysis.

Performing detailed analysis of STEP files requires specialized tooling that can parse complex topology and geometry. The earthtojake/text-to-cad repository provides the cadgen inspection framework, implemented in the cadgen.cli.step_inspect module, to enable scriptable querying of CAD model structure and spatial relationships. This guide covers both the CLI interface and the underlying Python API for automated inspection workflows.

CLI Architecture and Entry Points

The cadgen inspection system is built around a modular CLI architecture defined in packages/cadgen/src/cadgen/cli/step_inspect/cli.py. The entry point cadgen step inspect parses sub-commands—including refs, frame, measure, align, and diff—and forwards arguments to implementation functions in inspect.py.

When processing a CAD file, the system first loads an EntryContext through _load_entry_context and _load_step_context (lines 106-118 in inspect.py). This context contains the manifest, selector index, and file locations, with the selector index built from STEP topology artifacts to enable fast lookups.

Core Inspection Commands

Parsing References with refs

The refs sub-command enables inspection of selector tokens within STEP files. In packages/cadgen/src/cadgen/cli/step_inspect/inspect.py, the inspect_cad_refs function (lines 58-71) parses selector strings using cadgen.cad_ref_syntax to create ParsedToken objects.

# Show a summary of all selectors in a STEP file

cadgen step inspect refs robot.step

# Show detailed geometry and positioning for a specific selector

cadgen step inspect refs robot.step "#o1.2.f1" --detail --facts --positioning

The _inspect_selector function (lines 99-105 and 145-165) resolves these selectors against the index and builds human-readable summaries with optional geometry, facts, or positioning data.

Extracting Coordinate Frames

To retrieve the coordinate frame of a specific part or assembly, use the frame sub-command. This invokes inspect_target_frame (line 508 in inspect.py), which returns the part's transformation matrix and orientation data.

cadgen step inspect frame robot.step "#o1.2"

Measuring Distances Between Selectors

The measure sub-command calculates spatial relationships between two selectors. Calling measure_targets (line 778) supports both axis-aligned and Euclidean distance calculations.

cadgen step inspect measure robot.step "#o1.2.f1" "#o2.1.f3" --axis x

Aligning Parts

For assembly verification and positioning tasks, the align sub-command runs align_targets (line 832) to compute the translation vector and rotation hint required to align one selector to another.

cadgen step inspect align robot.step "#o1.2" "#o2.1" --mode center --axis z

Diffing CAD Files

Comparing model versions is handled by the diff sub-command, which executes diff_entry_targets (line 1014). This compares summaries, bounding boxes, and major planes between two STEP files.

cadgen step inspect diff robot_v1.step robot_v2.step --planes

Programmatic API Usage

While the CLI provides convenient access, all cadgen inspection logic is available as a Python library. Import functions directly from cadgen.cli.step_inspect.inspect for integration into automated pipelines.

from cadgen.cli.step_inspect.inspect import inspect_cad_refs

result = inspect_cad_refs(
    entry_target="robot.step",
    refs_text="#o1.2.f1",
    detail=True,
    facts=True,
    positioning=True,
)
print(result["tokens"][0]["summary"])

All inspection commands return JSON-serializable dictionaries containing a top-level "ok" flag, detailed "tokens" or "diff" sections, and optional "errors".

Key Implementation Files

The cadgen inspection system relies on several coordinated modules:

• packages/cadgen/src/cadgen/cli/step_inspect/inspect.py — Core implementation of all inspection verbs (refs, frame, measure, align, diff), including _load_entry_context, _inspect_selector, and the high-level helper functions starting at lines 508, 778, 832, and 1014.

• packages/cadgen/src/cadgen/cli/step_inspect/cli.py — Argument parser wiring for the cadgen step inspect command; maps sub-commands to functions in inspect.py.

• packages/cadgen/src/cadgen/cli/step_inspect/__main__.py — Entry point for python -m cadgen.cli step inspect.

• packages/cadgen/src/cadgen/cad_ref_syntax.py — Parses selector strings like #o1.2.f1 and validates file prefixes.

• packages/cadgen/src/cadgen/lookup.py — Builds and queries the selector index used by inspection functions.

• packages/cadgen/src/cadgen/analysis.py — Provides geometry facts, positioning calculations, and plane extraction used by inspection reports.

Summary

• The cadgen step inspect command provides sub-commands for refs, frame, measure, align, and diff operations on STEP files.
• All CLI functionality lives in packages/cadgen/src/cadgen/cli/step_inspect/inspect.py, with entry point handling in cli.py.
• The system uses ParsedToken objects and selector indices built from STEP topology for fast lookups.
• Results are returned as JSON-serializable dictionaries with consistent "ok" flags and detailed data sections.
• Functions like inspect_cad_refs, measure_targets, and diff_entry_targets are directly importable for Python automation.

Frequently Asked Questions

How do I install cadgen to use the inspection features?

As implemented in the earthtojake/text-to-cad repository, cadgen is installed from source by cloning the repository and running pip install -e packages/cadgen from the repository root. This makes the cadgen CLI and all inspection modules available system-wide.

What selector syntax does cadgen inspection support?

According to the source code in cadgen.cad_ref_syntax, cadgen uses a token-based selector syntax like #o1.2.f1 where o represents objects, numbers indicate indices, and additional letters denote sub-elements such as faces or edges. The parser validates file prefixes and decomposes these strings into ParsedToken objects for internal processing.

Can I use cadgen inspection commands in automated scripts?

Yes. All inspection functionality is available both through the CLI and as Python library functions in cadgen.cli.step_inspect.inspect. The API returns JSON-serializable dictionaries, making it suitable for integration into CI/CD pipelines and automated validation workflows.

What CAD file formats does cadgen inspection support?

The inspection module primarily targets STEP files (.step or .stp). The EntryContext loading mechanism in _load_step_context is specifically designed to parse STEP topology artifacts and build selector indices from them, enabling the reference and measurement operations described in this guide.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}