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

> Master cadgen inspection tasks using its CLI and API. Explore reference parsing, frame extraction, measurement, alignment, and differential analysis with this guide.

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

---

**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`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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.

```bash

# 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`](https://github.com/earthtojake/text-to-cad/blob/main/inspect.py)), which returns the part's transformation matrix and orientation data.

```bash
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.

```bash
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.

```bash
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.

```bash
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.

```python
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`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/inspect.py).

- **[`packages/cadgen/src/cadgen/cli/step_inspect/__main__.py`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadgen/src/cadgen/lookup.py)** — Builds and queries the selector index used by inspection functions.

- **[`packages/cadgen/src/cadgen/analysis.py`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadgen/src/cadgen/cli/step_inspect/inspect.py), with entry point handling in [`cli.py`](https://github.com/earthtojake/text-to-cad/blob/main/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.