cadcli

Agent-friendly CAD inspection, search, viewing, and editing for DWG/DXF files.

npm install -g @miclivs/cadcli

Inspection, search, viewing, and editing use the pure TypeScript acad-ts backend. No native CAD tools are required.

Why cadcli

CAD files are hard to inspect from scripts. cadcli gives agents and developers a predictable interface over DWG/DXF drawings: structured JSON for automation, concise human output in the terminal, SVG previews for visual checks, and safe copy-first editing.

cadcli info floorplan.dwg --json
cadcli overview floorplan.dwg
cadcli search floorplan.dwg "conference" --layer A-TEXT --json
cadcli view floorplan.dwg -o preview.svg
cadcli edit floorplan.dwg --set-text "Conference" --text-id 2A -o edited.dwg

Workflow

info → overview → layers/blocks/entities → search → view → edit

Start with info to understand the drawing, use overview to see the searchable vocabulary, narrow down with layers, blocks, entities, and search, render agent-friendly PNG/SVG evidence with render, then write edits to a new file with edit -o.

Commands

cadcli info <file>                       # metadata, version, counts, bounds
cadcli overview <file>                   # search vocabulary by layer/type/block/text
  --keywords 12 --samples 8
cadcli layers <file> [--total]           # layers and entity counts
cadcli blocks <file> [--total]           # block names and entity counts
cadcli entities <file>                   # entities, optionally filtered
  --type LINE --layer A-WALL --limit 20 --total

cadcli search <file> [query]             # search IDs, types, layers, text, raw fields
  --query "door" --type TEXT --layer A-TEXT --limit 10 --score --no-snippets
cadcli query <file> --schema             # show SQL query tables
cadcli query <file> --sql "select text from texts"

cadcli view <file> [-o preview.svg]      # SVG preview
cadcli render <file> -o overview.png     # agent-friendly PNG/SVG render
cadcli render <file> -o renders/ --diagnose # overview, architecture, furniture slices
cadcli edit <file> --set-text <text> --text-id <id> -o out.dwg
cadcli edit <file> --set-layer <layer> --layer-id <id> -o out.dwg
cadcli edit <file> --set-color '#ff0000' --color-id <id> -o out.dwg
cadcli edit <file> --move <id> --dx 10 --dy 0 -o out.dwg
cadcli edit <file> --rotate <id> --angle 90 --origin 0,0 -o out.dwg
cadcli edit <file> --scale <id> --factor 2 -o out.dwg
cadcli edit <file> --copy <id> --dx 10 --dy 0 -o out.dwg
cadcli edit <file> --delete <id> -o out.dwg
cadcli edit <file> --add-line 0,0:10,0 --new-layer A-WALL -o out.dwg
cadcli edit <file> --add-text "Label" --at 5,5 --height 2.5 -o out.dwg
cadcli json <file> [-o drawing.json]     # normalized JSON
cadcli svg <file> [-o sketch.svg]        # best-effort SVG from normalized JSON
cadcli thumbnail <file> [-o thumb.png]   # embedded thumbnail when available

All commands support --json for structured output and -q, --quiet where useful. Primary data goes to stdout; diagnostics and errors go to stderr.

Overview

cadcli overview is the map before the search. It shows the drawing's useful vocabulary broken down by layer, entity type, block, text keyword, and search hint so agents do not have to guess what to query.

WORKFLOW: overview (you are here) → search/entities → view/edit

SUMMARY
  DWG · 1906 entities · 33 layers · 42 blocks

LAYERS
A-TEXT
  entities: 88
  types: TEXT, MTEXT
  keywords: conference room, office, lobby

SEARCH HINTS
  conference room, office, A-TEXT, DOOR_SINGLE, TEXT

Text normalization

Some CAD files store visible text through legacy code pages and SHX fonts. For example, a Hebrew DWG may store jsr muu, 8 while AutoCAD displays it as חדר צוות 8. cadcli automatically normalizes these cases while loading the drawing, before overview, search, entities, json, and future query features consume the document.

The normalizer is route-based: document metadata such as codePage is combined with per-entity text style/font metadata such as gil.shx, narkism$.shx, or heb.shx. When the route is confident, cadcli rewrites the in-memory text field to the intended text. It does not store both raw and normalized copies in caches or output.

raw DWG text:  jsr muu, 8
cadcli text:   חדר צוות 8

The normalized document metadata records what happened:

{
  "metadata": {
    "codePage": "ansi_1255",
    "textNormalization": {
      "applied": ["hebrew-keyboard"],
      "entitiesChanged": 58
    }
  }
}

This makes discovery work naturally:

cadcli overview office.dwg
cadcli search office.dwg "חדר" --json

Query

cadcli query runs read-only SQL over a narrow in-memory projection of the normalized drawing. It does not create a user-visible database file.

cadcli query office.dwg --schema
cadcli query office.dwg --schema --json
cadcli query office.dwg --sql "select id, text, layer, x, y from texts where text like 'חדר%'" --json
cadcli query office.dwg --file rooms.sql --json

The base tables are summary, metadata, layers, blocks, and entities. Convenience tables expose common drawing concepts such as texts and inserts.

Rendering for visual understanding

cadcli render creates agent-friendly visual evidence from DWG/DXF files. PNG renders use content-fit bounds, high-contrast linework, and expanded block inserts by default so useful drawing geometry is not shrunk by far-out CAD extents.

cadcli render office.dwg -o overview.png
cadcli render office.dwg -o core.png --around-label "Server Room" --radius 3000
cadcli render office.dwg -o architecture.png --layers "wall,core,A-WALL"
cadcli render office.dwg -o renders/ --diagnose

--diagnose writes a small bundle for agents: overview.png, architecture.png, no-furniture.png, furniture.png, evidence-marked.png, and evidence.json with render counts and viewports. Use it when a question depends on layout, entrances, adjacency, or separating architectural evidence from furniture noise.

Viewing vs SVG export

cadcli view renders SVG through acad-ts directly from the CAD document.

cadcli svg renders a lightweight SVG from cadcli’s normalized JSON model. It is useful for quick agent previews and debugging, while view preserves more of acad-ts’ CAD model semantics.

Editing

Editing is intentionally copy-first and typed. You can update text, layers, color, linetype, lineweight, transparency, visibility, block attributes, transforms, copies, and deletion; you can also add point, line, circle, arc, text, mtext, and lightweight polyline entities.

cadcli edit drawing.dwg --set-text "New label" --text-id 2A -o edited.dwg
cadcli edit drawing.dwg --set-attr ROOM=204 --insert-id 3F -o edited.dwg
cadcli edit drawing.dwg --points '0,0;10,0;10,5' --closed --new-layer A-WALL -o edited.dwg

In-place edits are refused unless you explicitly pass --overwrite:

cadcli edit drawing.dwg --set-text "New label" --text-id 2A --overwrite

SDK

import { Dwg } from "@miclivs/cadcli";

const drawing = Dwg.open("floorplan.dwg");

console.log(await drawing.info());
console.log(await drawing.layers());
console.log(await drawing.search({ query: "conference", layer: "A-TEXT" }));

const preview = drawing.view();
console.log(preview.svg);

The public SDK is intentionally small: Dwg plus stable CAD/result types.

Cache

Search indexes are cached automatically in the platform-standard cache directory. On Node.js installs, cadcli search uses a disk-backed SQLite FTS index when the optional SQLite dependency is available; otherwise it falls back to a low-memory scan.

macOS    ~/Library/Caches/cadcli
Linux    $XDG_CACHE_HOME/cadcli or ~/.cache/cadcli
Windows  %LOCALAPPDATA%\cadcli\Cache

Set CADCLI_CACHE_DIR to override this location.

Requirements

Inspection, overview, layers, blocks, entities, search, JSON, SVG export, viewing, and editing work through the default pure TypeScript acad-ts backend.

License

MIT