Command reference

Every command and flag of shapemason, as shapemason --help and shapemason COMMAND --help print them. The options reference explains each option with its default and what the app and the web app call it.

Usage: shapemason [OPTIONS] [FILE]... [COMMAND]

Bring vector art and mesh files into parametric CAD.

Argument	Description
FILE	Input file(s) when no subcommand is given.

Flags on every command

These work with no command and with every converting command.

Flag	Description
-o, --output OUTPUT	Output file (single input only). Defaults to the input name with the new extension, next to the input.
-d, --out-dir OUT_DIR	Output directory for one or more inputs.
--overwrite	Replace output files that already exist (default: refuse).
--dry-run	Convert and report, but write nothing.
--name NAME	Name inside the output: STEP part name (default: the input’s file name), or for vector input a DXF block wrapping the sketch (default: no block).
-r, --recursive	Treat directory arguments as every supported file inside them.
--preview PATH	Also write a preview picture (.svg or .png) of what was converted.
--json	Print the report as JSON instead of text.
-q, --quiet	Only print warnings.
--stdout	Write the converted file to stdout instead of a file.

-h, --help prints help and -V, --version the version.

convert

Convert with defaults: vector art to a DXF sketch, a mesh to a STEP solid. The same as giving no command.

shapemason convert [OPTIONS] <FILE>...

Argument	Description
FILE	Input files or folders (folders with -r).

sketch

Convert vector art (SVG, DXF) into a DXF sketch.

shapemason sketch [OPTIONS] <FILE>...

Argument	Description
FILE	Input files or folders (folders with -r).

Flag	Description
--units UNITS	How to read unitless SVG coordinates: css (96 px/in), mm, or in. For DXF input, mm or in overrides the file’s own units. One of css, mm, in.
--scale SCALE	Extra scale factor.
--width MM	Scale uniformly so the result is this many mm wide.
--height MM	Scale uniformly so the result is this many mm tall. With –width, fits inside both.
--mirror	Mirror left↔right (for stamping, back-side etching, negatives).
--curves CURVES	Curve output: auto (arcs+splines), spline, or polyline. One of auto, spline, polyline.
--origin ORIGIN	Where (0,0) lands: canvas corner, geometry min corner, or center. One of canvas, min, center.
--tolerance TOLERANCE	Snap/simplify tolerance in mm.
--flatten-tolerance FLATTEN_TOLERANCE	Flattening chord error in mm (polyline mode and R12).
--keep-duplicates	Keep duplicate paths.
--no-close-paths	Don’t close paths by snapping nearby endpoints together.
--no-simplify	Don’t simplify collinear points.
--include-hidden	Include hidden elements.
--closed-only	Drop paths that are still open instead of warning about them.
--union	Merge overlapping shapes into one outline (per layer); nested shapes stay holes. Curves in merged shapes are flattened.
--offset MM	Grow (+) or shrink (−) every closed shape by this many mm: kerf, clearance, shrinkage. Flattens curves.
--strokes STROKES	Stroked SVG paths: keep the centerline, convert them to paths with their width (closed shapes), or drop stroke-only paths. One of centerline, to-path, drop.
--select ID|LAYER	Convert only elements with this id, inside this <g id>, or on this layer. Repeatable.
--exclude ID|LAYER	Skip elements with this id, inside this <g id>, or on this layer.
--font FONT	Font family for text that doesn’t name one or whose font is missing.
--font-dir DIR	Extra directory of font files to load.
--no-join	Write lines and arcs as separate LINE/ARC entities instead of one polyline with bulges per profile.
--layer LAYER	DXF layer name (with –layer-by, the layer for anything unassigned; for DXF input, moves everything onto this layer).
--layer-by LAYER_BY	Put elements on layers by enclosing <g> id or by fill color. One of id, color, none.
--dxf-version DXF_VERSION	DXF version: r2000 (default) or r12 for old importers (no splines). One of r12, r2000.

mesh-to-solid

Convert a mesh (STL, 3MF, OBJ, PLY, glTF) into a STEP solid.

shapemason mesh-to-solid [OPTIONS] <FILE>...

Argument	Description
FILE	Input files or folders (folders with -r).

Flag	Description
--units UNITS	Input units (STL has none; defaults to mm). One of auto, mm, cm, m, in.
--scale SCALE	Extra scale factor.
--up UP	Which axis is up in the file: auto (Z, or Y for glTF), z, or y (rotates Blender/game assets to Z-up). One of auto, z, y.
--origin ORIGIN	Move the result: keep coordinates, min corner, center, or bottom-center (centered in XY, sitting on Z=0). With split, applied to each file separately. One of keep, min, center, bottom-center.
--object ID|NAME	Convert only the object with this id or name (see analyze) in a multi-object file (3MF, OBJ, glTF).
--repair	Try to fix broken meshes first: drop duplicate faces, weld cracks, unify winding, fill small holes.
--prismatic	Prismatic conversion: recognize faceted cylinders (holes, bosses, fillets) and write true cylindrical faces you can select, fillet and constrain.
--coplanar-angle COPLANAR_ANGLE	Max angle between normals (degrees) to merge as one face.
--coplanar-distance COPLANAR_DISTANCE	Max off-plane distance (mm) to merge as one face.
--merge-distance MM	Merge vertices closer than this many mm.
--no-merge-coplanar	One face per triangle (don’t merge coplanar faces).
--no-simplify	Don’t remove collinear edge vertices.
--no-fix-normals	Don’t fix normals (flip inside-out shells).
--surface-body	Convert even if the mesh isn’t watertight, as a surface body.

split

Convert a mesh into one STEP file per separate part.

shapemason split [OPTIONS] <FILE>...

Argument	Description
FILE	Input files or folders (folders with -r).

Flag	Description
--units UNITS	Input units (STL has none; defaults to mm). One of auto, mm, cm, m, in.
--scale SCALE	Extra scale factor.
--up UP	Which axis is up in the file: auto (Z, or Y for glTF), z, or y (rotates Blender/game assets to Z-up). One of auto, z, y.
--origin ORIGIN	Move the result: keep coordinates, min corner, center, or bottom-center (centered in XY, sitting on Z=0). With split, applied to each file separately. One of keep, min, center, bottom-center.
--object ID|NAME	Convert only the object with this id or name (see analyze) in a multi-object file (3MF, OBJ, glTF).
--repair	Try to fix broken meshes first: drop duplicate faces, weld cracks, unify winding, fill small holes.
--prismatic	Prismatic conversion: recognize faceted cylinders (holes, bosses, fillets) and write true cylindrical faces you can select, fillet and constrain.
--coplanar-angle COPLANAR_ANGLE	Max angle between normals (degrees) to merge as one face.
--coplanar-distance COPLANAR_DISTANCE	Max off-plane distance (mm) to merge as one face.
--merge-distance MM	Merge vertices closer than this many mm.
--no-merge-coplanar	One face per triangle (don’t merge coplanar faces).
--no-simplify	Don’t remove collinear edge vertices.
--no-fix-normals	Don’t fix normals (flip inside-out shells).
--surface-body	Convert even if the mesh isn’t watertight, as a surface body.

analyze

Show what a file contains and whether it will convert cleanly. Writes nothing. Exit code 2 if anything needs attention.

shapemason analyze [OPTIONS] <FILE>...

Argument	Description
FILE	Input files or folders (folders with -r).

Flag	Description
--units UNITS	Input units: css|mm|in for vector art, auto|mm|cm|m|in for meshes.
--scale SCALE	Extra scale factor.
--up UP	Meshes: which axis is up in the file. One of auto, z, y.
--object ID|NAME	3MF: look at only the object with this id or name.
--repair	Meshes: repair before checking.
--surface-body	Meshes: accept open meshes (validate as a surface body).
--tolerance TOLERANCE	Vector art: snap/simplify tolerance in mm.
--include-hidden	Vector art: include hidden elements.
--closed-only	Vector art: drop open paths instead of warning.
--strokes STROKES	Vector art: how stroked paths are treated. One of centerline, to-path, drop.
--union	Vector art: merge overlapping shapes first.
--layer-by LAYER_BY	Vector art: layers by enclosing <g> id or by fill color. One of id, color, none.
--font FONT	Vector art: font family for text without one.
--font-dir DIR	Vector art: extra directory of font files.
--select ID|LAYER	Look at only elements with this id / group / layer. Repeatable.

validate

Convert without writing and print nothing unless there are warnings or errors. Exit code 0 clean, 2 warnings, 1 failure.

shapemason validate [OPTIONS] <FILE>...

Argument	Description
FILE	Input files or folders (folders with -r).

Flag	Description
--units UNITS	Input units: css|mm|in for vector art, auto|mm|cm|m|in for meshes.
--scale SCALE	Extra scale factor.
--up UP	Meshes: which axis is up in the file. One of auto, z, y.
--object ID|NAME	3MF: look at only the object with this id or name.
--repair	Meshes: repair before checking.
--surface-body	Meshes: accept open meshes (validate as a surface body).
--tolerance TOLERANCE	Vector art: snap/simplify tolerance in mm.
--include-hidden	Vector art: include hidden elements.
--closed-only	Vector art: drop open paths instead of warning.
--strokes STROKES	Vector art: how stroked paths are treated. One of centerline, to-path, drop.
--union	Vector art: merge overlapping shapes first.
--layer-by LAYER_BY	Vector art: layers by enclosing <g> id or by fill color. One of id, color, none.
--font FONT	Vector art: font family for text without one.
--font-dir DIR	Vector art: extra directory of font files.
--select ID|LAYER	Look at only elements with this id / group / layer. Repeatable.

extrude

Extrude vector art (SVG, DXF) straight into a STEP solid.

shapemason extrude [OPTIONS] <FILE>...

Argument	Description
FILE	Input files or folders (folders with -r).

Flag	Description
--depth MM|LAYER=MM,…	Depth in mm, or per layer: “FILL_FF0000=3,default=1” (0 skips a layer). Every layer starts at z=0. Default: 3.
--units UNITS	How to read unitless SVG coordinates: css (96 px/in), mm, or in. For DXF input, mm or in overrides the file’s own units. One of css, mm, in.
--scale SCALE	Extra scale factor.
--width MM	Scale uniformly so the result is this many mm wide.
--height MM	Scale uniformly so the result is this many mm tall. With –width, fits inside both.
--mirror	Mirror left↔right (for stamping, back-side etching, negatives).
--curves CURVES	Curve output: auto (arcs+splines), spline, or polyline. One of auto, spline, polyline.
--origin ORIGIN	Where (0,0) lands: canvas corner, geometry min corner, or center. One of canvas, min, center.
--tolerance TOLERANCE	Snap/simplify tolerance in mm.
--flatten-tolerance FLATTEN_TOLERANCE	Flattening chord error in mm (polyline mode and R12).
--keep-duplicates	Keep duplicate paths.
--no-close-paths	Don’t close paths by snapping nearby endpoints together.
--no-simplify	Don’t simplify collinear points.
--include-hidden	Include hidden elements.
--closed-only	Drop paths that are still open instead of warning about them.
--union	Merge overlapping shapes into one outline (per layer); nested shapes stay holes. Curves in merged shapes are flattened.
--offset MM	Grow (+) or shrink (−) every closed shape by this many mm: kerf, clearance, shrinkage. Flattens curves.
--strokes STROKES	Stroked SVG paths: keep the centerline, convert them to paths with their width (closed shapes), or drop stroke-only paths. One of centerline, to-path, drop.
--select ID|LAYER	Convert only elements with this id, inside this <g id>, or on this layer. Repeatable.
--exclude ID|LAYER	Skip elements with this id, inside this <g id>, or on this layer.
--font FONT	Font family for text that doesn’t name one or whose font is missing.
--font-dir DIR	Extra directory of font files to load.
--no-join	Write lines and arcs as separate LINE/ARC entities instead of one polyline with bulges per profile.
--layer LAYER	DXF layer name (with –layer-by, the layer for anything unassigned; for DXF input, moves everything onto this layer).
--layer-by LAYER_BY	Put elements on layers by enclosing <g> id or by fill color. One of id, color, none.
--dxf-version DXF_VERSION	DXF version: r2000 (default) or r12 for old importers (no splines). One of r12, r2000.

text

Set text in a font and write it as a DXF sketch, or with –depth a STEP solid.

shapemason text [OPTIONS] <TEXT>...

Argument	Description
TEXT	The text; use \n or several arguments for several lines. The font is –font (default: sans-serif, or –font-dir’s first match).

Flag	Description
--size MM	Font size (em height) in mm. Default: 10.
--align ALIGN	Line alignment for multi-line text. One of left, center, right. Default: left.
--letter-spacing MM	Extra space between glyphs in mm. Default: 0.
--line-spacing LINE_SPACING	Line pitch as a multiple of the size. Default: 1.2.
--depth MM	Extrude the text this many mm into a STEP solid instead.
--units UNITS	How to read unitless SVG coordinates: css (96 px/in), mm, or in. For DXF input, mm or in overrides the file’s own units. One of css, mm, in.
--scale SCALE	Extra scale factor.
--width MM	Scale uniformly so the result is this many mm wide.
--height MM	Scale uniformly so the result is this many mm tall. With –width, fits inside both.
--mirror	Mirror left↔right (for stamping, back-side etching, negatives).
--curves CURVES	Curve output: auto (arcs+splines), spline, or polyline. One of auto, spline, polyline.
--origin ORIGIN	Where (0,0) lands: canvas corner, geometry min corner, or center. One of canvas, min, center.
--tolerance TOLERANCE	Snap/simplify tolerance in mm.
--flatten-tolerance FLATTEN_TOLERANCE	Flattening chord error in mm (polyline mode and R12).
--keep-duplicates	Keep duplicate paths.
--no-close-paths	Don’t close paths by snapping nearby endpoints together.
--no-simplify	Don’t simplify collinear points.
--include-hidden	Include hidden elements.
--closed-only	Drop paths that are still open instead of warning about them.
--union	Merge overlapping shapes into one outline (per layer); nested shapes stay holes. Curves in merged shapes are flattened.
--offset MM	Grow (+) or shrink (−) every closed shape by this many mm: kerf, clearance, shrinkage. Flattens curves.
--strokes STROKES	Stroked SVG paths: keep the centerline, convert them to paths with their width (closed shapes), or drop stroke-only paths. One of centerline, to-path, drop.
--select ID|LAYER	Convert only elements with this id, inside this <g id>, or on this layer. Repeatable.
--exclude ID|LAYER	Skip elements with this id, inside this <g id>, or on this layer.
--font FONT	Font family for text that doesn’t name one or whose font is missing.
--font-dir DIR	Extra directory of font files to load.
--no-join	Write lines and arcs as separate LINE/ARC entities instead of one polyline with bulges per profile.
--layer LAYER	DXF layer name (with –layer-by, the layer for anything unassigned; for DXF input, moves everything onto this layer).
--layer-by LAYER_BY	Put elements on layers by enclosing <g> id or by fill color. One of id, color, none.
--dxf-version DXF_VERSION	DXF version: r2000 (default) or r12 for old importers (no splines). One of r12, r2000.

section

Cut a mesh with a plane and write the section as a DXF sketch.

shapemason section [OPTIONS] --at <MM[,MM…]> <FILE>...

Argument	Description
FILE	Input files or folders (folders with -r).

Flag	Description
--at MM[,MM…]	Position(s) along the axis to cut at, in mm (one layer each). Also --z. Required.
--axis AXIS	Axis the cutting plane is perpendicular to. One of x, y, z. Default: z.
--units UNITS	Input units (STL has none; defaults to mm). One of auto, mm, cm, m, in.
--scale SCALE	Extra scale factor.
--up UP	Which axis is up in the file: auto (Z, or Y for glTF), z, or y (rotates Blender/game assets to Z-up). One of auto, z, y.
--origin ORIGIN	Move the result: keep coordinates, min corner, center, or bottom-center (centered in XY, sitting on Z=0). With split, applied to each file separately. One of keep, min, center, bottom-center.
--object ID|NAME	Convert only the object with this id or name (see analyze) in a multi-object file (3MF, OBJ, glTF).
--repair	Try to fix broken meshes first: drop duplicate faces, weld cracks, unify winding, fill small holes.
--prismatic	Prismatic conversion: recognize faceted cylinders (holes, bosses, fillets) and write true cylindrical faces you can select, fillet and constrain.
--coplanar-angle COPLANAR_ANGLE	Max angle between normals (degrees) to merge as one face.
--coplanar-distance COPLANAR_DISTANCE	Max off-plane distance (mm) to merge as one face.
--merge-distance MM	Merge vertices closer than this many mm.
--no-merge-coplanar	One face per triangle (don’t merge coplanar faces).
--no-simplify	Don’t remove collinear edge vertices.
--no-fix-normals	Don’t fix normals (flip inside-out shells).
--surface-body	Convert even if the mesh isn’t watertight, as a surface body.
--dxf-version DXF_VERSION	DXF version: r2000 (default) or r12 for old importers. One of r12, r2000.
--tolerance TOLERANCE	Snap/simplify tolerance in mm for the sketch.

project

Project a mesh along an axis and write its silhouette as a DXF sketch.

shapemason project [OPTIONS] <FILE>...

Argument	Description
FILE	Input files or folders (folders with -r).

Flag	Description
--axis AXIS	Axis to look along. One of x, y, z. Default: z.
--units UNITS	Input units (STL has none; defaults to mm). One of auto, mm, cm, m, in.
--scale SCALE	Extra scale factor.
--up UP	Which axis is up in the file: auto (Z, or Y for glTF), z, or y (rotates Blender/game assets to Z-up). One of auto, z, y.
--origin ORIGIN	Move the result: keep coordinates, min corner, center, or bottom-center (centered in XY, sitting on Z=0). With split, applied to each file separately. One of keep, min, center, bottom-center.
--object ID|NAME	Convert only the object with this id or name (see analyze) in a multi-object file (3MF, OBJ, glTF).
--repair	Try to fix broken meshes first: drop duplicate faces, weld cracks, unify winding, fill small holes.
--prismatic	Prismatic conversion: recognize faceted cylinders (holes, bosses, fillets) and write true cylindrical faces you can select, fillet and constrain.
--coplanar-angle COPLANAR_ANGLE	Max angle between normals (degrees) to merge as one face.
--coplanar-distance COPLANAR_DISTANCE	Max off-plane distance (mm) to merge as one face.
--merge-distance MM	Merge vertices closer than this many mm.
--no-merge-coplanar	One face per triangle (don’t merge coplanar faces).
--no-simplify	Don’t remove collinear edge vertices.
--no-fix-normals	Don’t fix normals (flip inside-out shells).
--surface-body	Convert even if the mesh isn’t watertight, as a surface body.
--dxf-version DXF_VERSION	DXF version: r2000 (default) or r12 for old importers. One of r12, r2000.
--tolerance TOLERANCE	Snap/simplify tolerance in mm for the sketch.

preview

Render what a conversion would produce as an SVG (or PNG) picture: closed profiles filled, open paths red; meshes as an isometric view.

shapemason preview [OPTIONS] <FILE>...

Argument	Description
FILE	Input files or folders (folders with -r).

Flag	Description
--png	Write a PNG instead of an SVG (also implied by -o x.png).
--width WIDTH	PNG width in pixels. Default: 1200.
--open	Open the preview when done (open on macOS, xdg-open on Linux, start on Windows).
--units UNITS	Input units: css|mm|in for vector art, auto|mm|cm|m|in for meshes.
--scale SCALE	Extra scale factor.
--up UP	Meshes: which axis is up in the file. One of auto, z, y.
--object ID|NAME	3MF: look at only the object with this id or name.
--repair	Meshes: repair before checking.
--surface-body	Meshes: accept open meshes (validate as a surface body).
--tolerance TOLERANCE	Vector art: snap/simplify tolerance in mm.
--include-hidden	Vector art: include hidden elements.
--closed-only	Vector art: drop open paths instead of warning.
--strokes STROKES	Vector art: how stroked paths are treated. One of centerline, to-path, drop.
--union	Vector art: merge overlapping shapes first.
--layer-by LAYER_BY	Vector art: layers by enclosing <g> id or by fill color. One of id, color, none.
--font FONT	Vector art: font family for text without one.
--font-dir DIR	Vector art: extra directory of font files.
--select ID|LAYER	Look at only elements with this id / group / layer. Repeatable.

install-quick-action

Note

macOS builds only.

Add a Finder Quick Action (“Convert with shapemason”) that runs this shapemason on the selected files and reports problems as notifications.

shapemason install-quick-action [OPTIONS]

Flag	Description
--name NAME	Menu title. Default: Convert with shapemason.
--args ARGS	Arguments placed before the files, e.g. “–overwrite” or “extrude –depth 3”. Default: plain conversion.
--to DIR	Install into this folder instead of ~/Library/Services.
--overwrite	Replace an existing Quick Action of the same name.
--dry-run	Show what would be written.

uninstall-quick-action

Note

macOS builds only.

Remove a Quick Action that install-quick-action added.

shapemason uninstall-quick-action [OPTIONS]

Flag	Description
--name NAME	Menu title of the Quick Action to remove. Default: Convert with shapemason.
--to DIR	Remove it from this folder instead of ~/Library/Services.
--dry-run	Show what would be removed.

licenses

Print the licences of the third-party software in this build.

shapemason licenses [OPTIONS]

completions

Print a shell completion script.

shapemason completions [OPTIONS] <SHELL>

Argument	Description
SHELL	One of bash, elvish, fish, powershell, zsh.

telemetry

Turn anonymous usage telemetry on or off, or show whether it is on.

shapemason telemetry [OPTIONS] <ACTION>

Argument	Description
ACTION	One of on, off, status.