CLI Commands | Reference

The vcad CLI provides headless access to the full parametric kernel. Install it with cargo install vcad-cli. Running vcad with no subcommand launches the interactive TUI editor.

vcad new

Create a new .vcad document from a template.

vcad new <path> [--template <name>]

pathpathrequired

Output file path for the new document.

--templatestringrequired

Starting template. Options: empty (blank document), cube (single 20mm cube), assembly (two-part base and pillar).

vcad new project.vcad
vcad new starter.vcad --template cube
vcad new robot.vcad --template assembly

Evaluation cache

vcad info, vcad export (STL/GLB) and vcad-render keep a content-addressed cache of evaluated root geometry on disk, so a document where one root changed re-evaluates one root. A 108-root sheet-metal humanoid (hardware/rose-pro) renders cold in ~150 s and warm in 0.8 s; an edit to one plate costs ~3 s.

Each root's key is the SHA-256 of its fully resolved IR subgraph (renumbered structurally, so node ids and names don't matter), the tessellation settings, and the kernel identity — the evaluator version, target architecture, and a content hash of every kernel / IR / evaluator / tang source file baked in at build time. Editing the kernel changes the id, and the cache simply starts a new directory; nothing is ever served across kernel builds. Roots that read files outside the IR (STEP/mesh imports, part instances) are never cached, and neither are failed or empty roots.

Only the tessellated mesh is cached — vcad_kernel::Solid has no serialized form — so consumers that need the BRep (STEP export, vcad-render --raytrace / --photoreal / --section) bypass it.

Control	Effect
`$VCAD_CACHE_DIR`	cache root (default `$XDG_CACHE_HOME/vcad`, else `~/.cache/vcad`)
`VCAD_CACHE=0`, `--no-cache`	read and write nothing
`rm -rf ~/.cache/vcad/geom`	drop everything; safe at any time

Every run that consulted the cache prints one stderr line: cache: 107 hit, 1 miss, 1 stored (<dir>).

vcad info

Display document metadata and mesh statistics.

vcad info <file>

filepathrequired

Path to a .vcad file or .loon source (evaluated on load; [use …] modules resolve next to the file and on $VCAD_LOON_PATH).

The command reads the document, prints its node count, materials, and scene entries, then evaluates the parametric DAG through the kernel to report tessellation statistics.

$ vcad info bracket.vcad
vcad document: bracket.vcad
  Version: 1.0.0
  Nodes: 5
  Materials: 2
  Scene entries: 1

Scene:
  1: Bracket (material: aluminum)

Mesh stats:
  Total triangles: 1284
  Total vertices: 642

vcad export

Export a .vcad file to a mesh or CAD interchange format. The output format is determined by the file extension.

vcad export <input> <output>

inputpathrequired

Input .vcad file.

outputpathrequired

Output file. Extension determines format: .stl, .step/.stp, .glb, .urdf.

vcad export bracket.vcad bracket.stl
vcad export bracket.vcad bracket.step
vcad export robot.vcad robot.urdf

Extension	Format	Notes
`.stl`	Binary STL	Combined mesh of all scene entries
`.step` / `.stp`	STEP AP214	Primitives and imported STEP only; booleans not supported
`.glb`	glTF Binary	Currently prints a notice (not yet fully implemented in CLI)
`.urdf`	URDF	Exports assembly with links and joints

STEP export limitations

STEP export works for primitive shapes (cube, cylinder, sphere, cone) and previously imported STEP files. Boolean operations convert geometry to a triangle mesh, which cannot be exported back to STEP. The command will exit with an error explaining this if you try.

vcad import

Import a STEP file into vcad format.

vcad import <input> <output> [--name <name>]

inputpathrequired

Input STEP file (.step or .stp).

outputpathrequired

Output .vcad file.

--namestringrequired

Part name. Defaults to the input filename without extension.

vcad import housing.step housing.vcad
vcad import housing.step housing.vcad --name "Motor Housing"

If the STEP file contains multiple solids, each gets its own node with a numbered suffix (e.g., Housing_0, Housing_1).

vcad import-urdf

Import a URDF robot description file into vcad format.

vcad import-urdf <input> <output>

inputpathrequired

Input URDF file (.urdf or .xml).

outputpathrequired

Output .vcad file.

vcad import-urdf robot.urdf robot.vcad

The importer reads links and joints from the URDF, creating part definitions and assembly data in the vcad document.

vcad boolean

Apply a boolean operation between two parts in a document.

vcad boolean <file> <op> <part_a> <part_b> [-o <output>] [--result-name <name>]

filepathrequired

Input .vcad file.

openumrequired

Operation: union, difference, or intersection.

part_astringrequired

First part, by node ID or name.

part_bstringrequired

Second part, by node ID or name.

-o / --outputpathrequired

Output file. Defaults to modifying the input file in place.

--result-namestringrequired

Name for the result node. Defaults to "<Op> Result".

vcad boolean model.vcad difference Base Hole
vcad boolean model.vcad union Plate Rib -o combined.vcad --result-name "Reinforced Plate"

The operands are removed from the scene and replaced by the result node.

vcad transform

Apply a transform to a part in a document.

vcad transform <file> <part> [--translate x,y,z] [--rotate rx,ry,rz] [--scale sx,sy,sz] [-o <output>]

filepathrequired

Input .vcad file.

partstringrequired

Part to transform, by node ID or name.

--translatestringrequired

Translation offset as x,y,z in millimeters.

--rotatestringrequired

Rotation as rx,ry,rz in degrees.

--scalestringrequired

Scale factors as sx,sy,sz or a single uniform value.

-o / --outputpathrequired

Output file. Defaults to modifying the input file in place.

Transforms are applied in order: scale, then rotate, then translate. When multiple flags are given, the chain is: scale the part, rotate the result, then translate.

vcad transform model.vcad Bracket --translate 50,0,10
vcad transform model.vcad Arm --rotate 0,0,45 --translate 100,0,0
vcad transform model.vcad Part --scale 2 -o scaled.vcad

vcad render

Render a document to a PNG or JPEG image using software rasterization.

vcad render <input> <output> [options]

inputpathrequired

Input .vcad file.

outputpathrequired

Output image file (.png or .jpg).

--widthu32required

Image width in pixels.

--heightu32required

Image height in pixels.

--azimuthf64required

Camera azimuth angle in degrees, counter-clockwise from +X in the XY plane.

--elevationf64required

Camera elevation angle in degrees.

--distancef64required

Camera distance from subject. Auto-calculated if omitted.

--backgroundstringrequired

Background color as a hex string (e.g., ffffff) or transparent.

--upz | yrequired

World up axis. z matches the kernel, loon semantics and the docs (grid in XY, Z vertical) — a model built Z-up stands up in the render. Use y only for geometry authored in a Y-up graphics frame.

vcad render bracket.vcad preview.png
vcad render bracket.vcad hero.png --width 3840 --height 2160 --azimuth 30 --elevation 20
vcad render bracket.vcad thumb.png --width 512 --height 512 --background transparent

vcad slice

Slice a document for 3D printing, producing G-code or 3MF output.

vcad slice <input> -o <output> [options]

inputpathrequired

Input .vcad file.

-o / --outputpathrequired

Output file (.gcode or .3mf).

--profilestringrequired

Printer profile: generic, bambu_x1c, bambu_p1s, bambu_a1, bambu_a1_mini, ender3, prusa_mk4, voron_24.

--layer-heightf64required

Layer height in mm. Overrides profile default.

--wall-countu32required

Number of perimeter walls.

--infillu32required

Infill density as a percentage (0-100).

--supportflagrequired

Enable support generation.

--print-tempu32required

Nozzle temperature in degrees C.

--bed-tempu32required

Bed temperature in degrees C.

--smartflagrequired

Use BRep analysis to recommend layer height, infill, and support settings.

--explainflagrequired

Print reasoning behind smart defaults (requires --smart).

vcad slice bracket.vcad -o bracket.gcode --profile bambu_x1c
vcad slice bracket.vcad -o bracket.3mf --smart --explain
vcad slice bracket.vcad -o bracket.gcode --layer-height 0.1 --infill 30 --support

Smart defaults

The --smart flag analyzes the part's BRep geometry (overhangs, thin walls, surface features) and recommends print settings. Add --explain to see the reasoning. You can still override individual settings -- CLI flags take priority over smart recommendations.

vcad tui

Launch the interactive terminal UI editor.

vcad tui [file]

filepathrequired

Optional .vcad file to open. If omitted, starts with an empty document.

The TUI provides an ASCII wireframe 3D viewport, a feature tree you can navigate with j/k, and keyboard shortcuts for adding primitives (1 for box, 2 for cylinder, 3 for sphere). See the TUI tutorial for a full walkthrough.

vcad repl

Launch the interactive REPL for building geometry command-by-command.

vcad repl [file]

filepathrequired

Optional .vcad file to load as the starting state.

The REPL lets you type commands like cube 30 30 30, translate 10 0 0, and export out.stl in an iterative workflow. See the REPL tutorial for details.

Exit Codes

The CLI exits with code 0 on success. On failure it exits with code 1 and prints a descriptive error message. This makes it straightforward to use in scripts and CI pipelines where you need to detect failures.

For tutorials that walk through common workflows, see the CLI Quick Start, REPL, and TUI.