Plan: CLI & Command-File Options Documentation
Goal
Ensure every option from linkcad.exe --help / --help-all is documented in the
correct section of the docs site, with no fabricated options, and that format-specific
options are grouped per-format with their exact key names so users can use them in
command files and on the CLI.
Audit Summary
Options correctly documented today
The following modern CLI flags in automation/cli.md and reference/cli-parameters.md
are accurate and match the source code:
| Option | Status |
|---|---|
-i, --import |
Correct |
-o, --export |
Correct |
--input-format |
Correct |
--output-format |
Correct |
--layer-map |
Correct |
-c, --config |
Correct |
--top-cell |
Correct |
--apply-tool |
Correct |
--apply-layer-map |
Correct |
--batch-combine |
Correct |
-u, --units |
Correct |
-q, --quit |
Correct |
--exit |
Correct |
--console |
Correct |
--trace |
Correct |
--save-settings |
Correct |
--no-save-settings |
Correct |
--load-defaults |
Correct |
--python-script |
Correct |
--python-cmd |
Correct |
--python-interactive |
Correct |
--help |
Correct |
--help-all |
Correct |
Errors to fix
| File | Issue |
|---|---|
automation/cli.md |
Lists --version — does NOT exist (no set_version call in CLI11 setup) |
reference/cli-parameters.md |
Lists --version — same |
Content gaps
| Gap | Description |
|---|---|
| Format-specific option key names | Every format page (formats/*.md) describes options by human-readable name ("Scaling", "Ignore text") but does NOT include the CLI/command-file key name (DxfInScaling, GdsInIgnoreText). Users cannot use these pages to write command files. |
Automation Lc* options |
The --help-all output includes many Lc* options relevant to automation (LcSkipImportOptions, LcSkipExportOptions, LcConvertBatch, LcSelectTopCell, LcDeleteEmtpyCells, LcDeleteUnresolvedRefs, LcNoRestart, etc.). These are not documented. |
| Batch tool flags | LcBatchToolsMerge, LcBatchToolsDeembed, LcBatchToolsOutline, LcBatchToolsQuasiCircles — used in batch mode — not documented with key names. |
| Tool option key names | Tool pages (tools/*.md) don't include Tool* key names for CLI/command-file usage. |
| Viewer option key names | Viewer pages don't include Lv* key names. |
Proposed Documentation Organization
Section (a): General Program Options
File: automation/cli.md (existing — minor fix)
File: reference/cli-parameters.md (existing — minor fix)
Changes:
- Remove
--versionfrom both files (it doesn't exist) - No other structural changes needed; these are already correct
Section (b): Automation Options
File: automation/cli.md — add a new "Automation Options" subsection after "Control"
These are the Lc* options from --help-all that control unattended operation.
They're settable on the CLI and in command files.
| Key | Type | Description |
|---|---|---|
LcSkipImportOptions |
flag | Skip the import options dialog |
LcSkipExportOptions |
flag | Skip the export options dialog |
LcSkipSteps |
string | Comma-separated list of wizard steps to skip |
LcSelectTopCell |
flag | Auto-select the top cell instead of prompting |
LcConvertBatch |
flag | Enable batch conversion mode |
LcNoRestart |
flag | Disable automatic restart on crash |
LcDeleteEmtpyCells |
flag | Delete empty cells after import |
LcDeleteUnresolvedRefs |
flag | Delete unresolved cell references |
LcAutoAlternatePolarity |
flag | Auto-alternate polarity on multi-layer import |
LcAutoNumberMaterialValues |
flag | Auto-number material values |
LcAutoNumberZValues |
flag | Auto-number Z values |
Also add a brief note: these are the same key names used in .lsn command files.
Cross-reference automation/config-files.md.
Section (c): Batch Tool Options
File: automation/batch.md — add key names to the "Batch Tools" table
| Key | Description |
|---|---|
LcBatchToolsMerge |
Merge overlapping shapes |
LcBatchToolsDeembed |
De-embed polygons |
LcBatchToolsOutline |
Extract outlines |
LcBatchToolsQuasiCircles |
Detect quasi-circles |
These map to the checkboxes in the batch wizard and can be set in command files.
Section (d): Python Options
File: automation/cli.md — already correct, no changes needed.
Note: The Lc* legacy aliases (LcPythonScript, LcPythonCmd,
LcPythonInteractive) are internal/runtime options. They are documented
implicitly through the modern --python-* flags.
Section (e): Format-Specific Options
File: Each formats/<format>.md page — add a "CLI / Command-File Options"
section at the bottom with tables mapping key name → type → description.
This is the largest change. Each format page needs a section like:
## CLI / Command-File Options
These option keys can be used on the command line or in
[command files](../automation/config-files.md).
### Import Options
| Key | Type | Description |
|-----|------|-------------|
| `DxfInScaling` | float | Import scaling factor |
| `DxfInIgnoreText` | flag | Ignore TEXT/MTEXT entities |
| ... | ... | ... |
### Export Options
| Key | Type | Description |
|-----|------|-------------|
| `DxfOutScaling` | float | Export scaling factor |
| `DxfOutBinary` | flag | Write binary DXF |
| ... | ... | ... |
Option-to-format mapping (from --help)
DXF (formats/dxf.md)
Import:
| Key | Type | Description |
|---|---|---|
DxfInEndcapType |
int | Wire endcap style (0=flat, 1=round, 2=square) |
DxfInExplodeSplines |
flag | Explode splines to polylines |
DxfInHatchProcessing |
int | Hatch mode (0=ignore, 1=import, 2=fill) |
DxfInIgnoreText |
flag | Ignore TEXT/MTEXT entities |
DxfInImportPoints |
flag | Import POINT entities |
DxfInPointMode |
int | Point display mode (PDMODE) |
DxfInPointSize |
float | Point size in drawing units (PDSIZE) |
DxfInReadPolyfaceMesh |
flag | Read polyface mesh entities |
DxfInScaling |
float | Import scaling factor |
DxfInTextLineWidth |
float | Text stroke width |
DxfInUnitsUnit |
int | Unit enum (e.g. Micron) |
DxfInUnitsValue |
int | Units scaling value |
Export:
| Key | Type | Description |
|---|---|---|
DxfOutBinary |
flag | Binary DXF format |
DxfOutEndcapType |
int | Wire endcap style |
DxfOutExplodeArrays |
flag | Explode array references |
DxfOutExplodeText |
flag | Explode text to polylines |
DxfOutExportAsRegions |
flag | Export polygons as REGION entities |
DxfOutFillPolygons |
flag | Fill polygons with SOLID entities |
DxfOutFlatten |
flag | Flatten hierarchy |
DxfOutFormatVersion |
int | DXF version (12, 14, 2000, …) |
DxfOutHatchPolygons |
flag | Hatch polygons |
DxfOutScaling |
float | Export scaling factor |
DxfOutUnitsUnit |
int | Unit enum |
DxfOutUnitsValue |
int | Units scaling value |
DWG (formats/dwg.md)
| Key | Type | Description |
|---|---|---|
DwgOutUnitsUnit |
int | DWG export units enum |
DwgOutUnitsValue |
int | DWG export units scaling value |
(DWG shares DXF import options; note this in the page)
GDSII (formats/gdsii.md)
Import:
| Key | Type | Description |
|---|---|---|
GdsInFontSizeUnits |
int | Font size unit enum |
GdsInFontSizeValue |
float | Font size value |
GdsInIgnoreDataTypes |
flag | Ignore GDSII data types |
GdsInIgnoreText |
flag | Ignore text elements |
Export:
| Key | Type | Description |
|---|---|---|
GdsOutDbScalingUnits |
int | Database scaling units |
GdsOutDbScalingValue |
float | Database scaling value |
GdsOutFontSizeValue |
float | Export font size multiplier |
GdsOutPad |
flag | Zero-pad output records |
CIF (formats/cif.md)
Import:
| Key | Type | Description |
|---|---|---|
CifInFontAnchorH |
int | Font horizontal anchor |
CifInFontAnchorV |
int | Font vertical anchor |
CifInFontSizeUnits |
int | Font size unit enum |
CifInFontSizeValue |
float | Font size value |
CifInIgnoreText |
flag | Ignore text primitives |
CifInUnitsCents |
flag | Use centimicrons |
Export:
| Key | Type | Description |
|---|---|---|
CifOutCleMode |
flag | CLE mode output |
CifOutFlatten |
flag | Flatten hierarchy |
CifOutFlavour |
int | CIF dialect |
CifOutHeader |
string | File header comment |
CifOutLayerNameLength |
int | Max layer name length |
CifOutLinefeed |
flag | Add linefeeds |
CifOutNoGlobalCell |
flag | No global cell |
CifOutPolygonLimit |
int | Max vertices per polygon |
CifOutScaleDS |
flag | Scale DS command |
CifOutSpaceDS |
flag | Space after DS |
CifOutSpaceL |
flag | Space after L |
CifOutSplitPolygons |
flag | Split polygons at limit |
CifOutUnitsCents |
flag | Use centimicrons |
CifOutUseBox |
flag | Use box primitive |
CifOutUseRound |
flag | Use round flash |
CifOutUseWire |
flag | Use wire primitive |
Gerber RS-274X (formats/gerber.md)
Import:
| Key | Type | Description |
|---|---|---|
GbrInApertureFile |
flag | Use external aperture file |
GbrInApertureFilePath |
string | Aperture definition file path |
GbrInCoordinateMode |
int | Coordinate mode (abs/incr) |
GbrInCustomApertureFile |
flag | Use custom aperture definitions |
GbrInFormatXDec |
int | X decimal digits |
GbrInFormatXInt |
int | X integer digits |
GbrInFormatYDec |
int | Y decimal digits |
GbrInFormatYInt |
int | Y integer digits |
GbrInMergeLayers |
flag | Merge all layers |
GbrInModalD03 |
flag | Modal D03 interpretation |
GbrInModalG02 |
flag | Modal G02 interpretation |
GbrInQuadrantMode |
int | Arc quadrant mode |
GbrInUnits |
int | Import units |
GbrInZeroSuppression |
int | Zero suppression mode |
Export:
| Key | Type | Description |
|---|---|---|
GbrOutAbsCoordinate |
flag | Absolute coordinates |
GbrOutCircularInterpolation |
flag | Use circular interpolation |
GbrOutDecimals |
int | Decimal digits |
GbrOutEobCharacter |
string | End-of-block character |
GbrOutFillPolygons |
flag | Fill polygons |
GbrOutFlashCircles |
flag | Flash circles |
GbrOutFlashRectangles |
flag | Flash rectangles |
GbrOutForceDraw |
flag | Force draw mode |
GbrOutIntegers |
int | Integer digits |
GbrOutLinebreaks |
int | Insert linebreaks |
GbrOutParameterDelimiter |
string | Parameter delimiter |
GbrOutRectAptLimitUnits |
int | Rect aperture limit units |
GbrOutRectAptLimitValue |
float | Rect aperture limit value |
GbrOutRoundAptLimitUnits |
int | Round aperture limit units |
GbrOutRoundAptLimitValue |
float | Round aperture limit value |
GbrOutSingleFile |
flag | All layers in one file |
GbrOutStepAndRepeat |
flag | Use step and repeat |
GbrOutSuppressLeadingZero |
flag | Suppress leading zeros |
GbrOutUnitsImperial |
flag | Imperial units |
GbrOutWidthUnits |
int | Width unit enum |
GbrOutWidthValue |
float | Default width value |
PostScript / PDF (formats/pdf-postscript.md)
Import (PostScript only):
| Key | Type | Description |
|---|---|---|
PsInDrawText |
int | Import text |
PsInIgnoreClipPath |
flag | Ignore clipping paths |
PsInPage |
int | Page to import |
PsInPstoeditOptions |
string | pstoedit options |
PsInSubtractWhite |
flag | Subtract white regions |
Export:
| Key | Type | Description |
|---|---|---|
PsOutBlack |
flag | Force black output |
PsOutCustomDbScale |
float | Custom database scale |
PsOutCustomPaperLengthValue |
float | Custom paper length |
PsOutCustomPaperWidthValue |
float | Custom paper width |
PsOutFormatType |
int | Format type (PS/EPS) |
PsOutLandscape |
flag | Landscape orientation |
PsOutLayout |
int | Layout mode |
PsOutPaperLengthPt |
int | Paper length in points |
PsOutPaperMarginValue |
float | Paper margin |
PsOutPaperUnits |
int | Paper unit enum |
PsOutPaperWidthPt |
int | Paper width in points |
PsOutScaleMode |
int | Scaling mode |
PsOutStandardFormat |
int | Standard format |
Raster / Bitmap (formats/bitmap.md)
Import only:
| Key | Type | Description |
|---|---|---|
RasterInGrayLevels |
int | Number of gray levels |
RasterInKeepWhite |
flag | Keep white pixels |
RasterInMergeType |
int | Merge type |
RasterInProcessing |
int | Processing mode |
RasterInScalingUnits |
int | Scaling unit enum |
RasterInScalingValue |
float | Scaling value |
RasterInScalingValueY |
float | Y-axis scaling |
ACIS SAT (formats/acis.md)
Import only:
| Key | Type | Description |
|---|---|---|
AcisInPlane |
int | Import plane |
ANF (formats/anf.md)
Export only:
| Key | Type | Description |
|---|---|---|
AnfOutCmdAadd |
flag | Use AADD command |
AnfOutCmdAglue |
flag | Use AGLUE command |
AnfOutCmdFacet |
string | Facet command |
AnfOutCmdFilname |
string | Output filename in command |
AnfOutCmdNummrg |
flag | Use NUMMRG command |
AnfOutCmdNummrgToler |
float | NUMMRG tolerance |
AnfOutCmdStitle |
string | Model subtitle |
AnfOutCmdTitle |
string | Model title |
AnfOutExplodeArcs |
flag | Explode arcs into lines |
AnfOutMerge |
flag | Merge overlapping areas |
AnfOutModelType |
int | ANSYS model type |
AnfOutUnits |
int | Output units |
IE3D (formats/ie3d.md)
Export only (from --help):
| Key | Type | Description |
|---|---|---|
Ie3dOutFormatVersion |
int | IE3D format version |
Ie3dOutUnits |
int | IE3D output units |
Sonnet (formats/sonnet.md)
Export only (from --help):
| Key | Type | Description |
|---|---|---|
SonOutSubstrateThickness |
float | Substrate thickness |
SonOutUnits |
int | Output units |
SonXCells |
int | X cell count |
SonYCells |
int | Y cell count |
LASI TLC (formats/lasi-tlc.md)
Export:
| Key | Type | Description |
|---|---|---|
TlcOutFlatten |
flag | Flatten hierarchy |
TlcOutUserUnits |
int | User units |
ASCII Data (formats/ascii.md)
Import only:
| Key | Type | Description |
|---|---|---|
AsciiInScalingUnits |
int | Scaling unit enum |
AsciiInScalingValue |
int | Scaling value |
AsciiInType |
int | 0=polygon, 1=wire |
AsciiInWidth |
int | Wire width |
TetGen / TETIN (in formats/anf.md or separate)
Export:
| Key | Type | Description |
|---|---|---|
TetinOutCmdAadd |
flag | Add command |
TetinOutCmdAglue |
flag | Glue command |
TetinOutCmdFacet |
string | Facet mode |
TetinOutCmdNummrg |
flag | Numeric merge |
TetinOutCmdNummrgToler |
float | Merge tolerance |
TetinOutCmdStitle |
string | Surface title |
TetinOutExplodeArcs |
flag | Explode arcs |
TetinOutModelType |
int | Model type |
TetinOutTriangToler |
float | Triangulation tolerance |
TetinOutUnits |
int | Output units |
Note: TETIN is not a separate format page today. These options are under "TetGen Input Options" in
--help. TETIN export is an ANF variant. Document these in the ANF page under a "TETIN Variant" subsection.
Formats with no format-specific options in --help
These formats have no CLI options in the --help output. Their pages need no changes:
- OASIS (
formats/oasis.md) - SVG (
formats/svg.md) - GDS-TXT (
formats/gdstxt.md) - STEP (
formats/step.md) - IGES (
formats/iges.md) - Parasolid XT (
formats/parasolid.md) - Compass (
formats/compass.md) - DBSF (
formats/dbsf.md)
However STEP and IGES have
StepOutUnitsandIgesOutUnitslisted in "Other Options". Document those in their respective pages.
"Other Options" group — orphaned options to distribute
These appear in the --help "Other Options" group and need to be documented in
the correct format page:
| Key | Goes in | Description |
|---|---|---|
DwgOutUnitsUnit |
formats/dwg.md |
DWG export units enum |
DwgOutUnitsValue |
formats/dwg.md |
DWG export units value |
Ie3dOutFormatVersion |
formats/ie3d.md |
IE3D format version |
Ie3dOutUnits |
formats/ie3d.md |
IE3D output units |
IgesOutUnits |
formats/iges.md |
IGES export units |
OdbppInApplyLayerPolarities |
formats/gerber.md or new ODB++ page |
ODB++ polarities |
OdbppInLayer |
(same) | ODB++ layer filter |
OdbppInStep |
(same) | ODB++ step filter |
OdbppOutStep |
(same) | ODB++ output step |
SonOutSubstrateThickness |
formats/sonnet.md |
Sonnet substrate |
SonOutUnits |
formats/sonnet.md |
Sonnet units |
SonXCells |
formats/sonnet.md |
Sonnet X cells |
SonYCells |
formats/sonnet.md |
Sonnet Y cells |
StepOutUnits |
formats/step.md |
STEP export units |
TlcOutFlatten |
formats/lasi-tlc.md |
TLC flatten |
TlcOutUserUnits |
formats/lasi-tlc.md |
TLC user units |
XtOutExplodeArcs |
formats/parasolid.md |
Parasolid explode arcs |
TextLineWidthRel |
cross-format (common) | Text width relative to height |
CmdToolCropBounds |
tools/drawing-operations/crop.md |
Crop bounds (runtime) |
OdbppIn*/OdbppOut*: ODB++ is not documented as a separate format page. These are internal/rarely-used. Skip or add a brief note in the Gerber page.CmdToolCropBoundsis runtime-only — skip.TextLineWidthRelis cross-format — document inautomation/cli.mdunder common options.
Section (f): Drawing Tool Options (Tool*)
File: reference/cli-parameters.md — add a "Drawing Tool Options" section
These Tool* options control how tools behave when invoked via CLI or command files.
Group into sub-categories:
Arc & Curve Precision
| Key | Type | Description |
|---|---|---|
ToolArcPrecUnits |
int | Precision mode (Facets, Tolerance) |
ToolArcPrecValue |
int | Arc approximation value |
Shape Conversion (auto-applied during import/export)
| Key | Type | Description |
|---|---|---|
ToolConvertArcs |
flag | Convert arcs to polylines |
ToolConvertCircles |
flag | Convert circles to polygons |
ToolConvertDonuts |
flag | Convert donuts |
ToolConvertDonutsStyle |
int | 0=single outline, 1=two halves |
ToolConvertSplines |
flag | Convert splines to polylines |
ToolConvertText |
flag | Convert text to polygons |
ToolConvertWires |
flag | Convert wires to polygons |
Polygon Handling
| Key | Type | Description |
|---|---|---|
ToolCloseOpenPolygons |
flag | Close open polygons |
ToolAddWidthToPolygons |
flag | Add width to zero-width polylines |
ToolEraseZeroWidthPolylines |
flag | Erase zero-width polylines |
ToolMergeZeroWidthPolylines |
flag | Merge zero-width polylines |
ToolJoinOpenPolygons |
flag | Join open polygons |
ToolAllowPolylineSpanning |
flag | Allow polyline spanning |
ToolEvenOddFill |
flag | Use even-odd fill rule |
ToolForceManhattan |
flag | Force Manhattan geometry |
ToolSelectionOutlineOnly |
flag | Select outline only |
ToolSelectionPercentage |
int | Selection tolerance percentage |
Holes & Sanitize
| Key | Type | Description |
|---|---|---|
ToolHolesMode |
int | 0=link, 1=split, 2=extract |
ToolHolesModeLink |
flag | Link holes |
ToolHolesModeOmitLink |
flag | Omit link in holes |
ToolKeepInternalEdges |
flag | Keep internal edges |
Tolerance & Width
| Key | Type | Description |
|---|---|---|
ToolPolyToleranceUnits |
int | Tolerance unit enum |
ToolPolyToleranceValue |
int | Polygon tolerance value |
ToolPolyWidthUnits |
int | Width unit enum |
ToolPolyWidthValue |
int | Width value |
ToolErrorMargin |
float | Error margin multiplier |
Quasi-Circle Detection
| Key | Type | Description |
|---|---|---|
ToolQuasiCircleMinFacets |
int | Minimum facets for detection |
Crop
| Key | Type | Description |
|---|---|---|
ToolCropX0 |
float | Crop region X0 |
ToolCropX1 |
float | Crop region X1 |
ToolCropY0 |
float | Crop region Y0 |
ToolCropY1 |
float | Crop region Y1 |
Etch Compensation
| Key | Type | Description |
|---|---|---|
ToolEtchMerge |
flag | Merge after etch |
ToolEtchNegaPosi |
flag | Negative-positive conversion |
ToolEtchPitchUm |
float | Pitch in microns |
ToolEtchRangeUm |
float | Range in microns |
ToolEtchResultLayerMax |
int | Max result layer |
ToolEtchResultLayerMin |
int | Min result layer |
Misc
| Key | Type | Description |
|---|---|---|
ToolAutoFlatten |
flag | Auto-flatten hierarchy |
ToolDontExplode |
flag | Don't explode arrays |
ToolSnapToGridSpacing |
float | Snap-to-grid spacing (runtime) |
ToolShapeFilter |
int | Shape filter mode (runtime) |
ToolExtractionHolesMode |
int | Hole extraction mode (runtime) |
Section (g): Viewer Options (Lv*)
File: reference/cli-parameters.md — add a "Viewer Options" section
These are mostly internal/advanced. Document briefly:
| Key | Type | Description |
|---|---|---|
LvDrawFilled |
flag | Draw filled polygons |
LvBackgroundColor |
int | 0=black, 1=white |
LvBlendFunction |
int | 0=opaque, 1=translucent, 2=hatched |
LvHiliteBrokenPlines |
flag | Highlight broken polylines |
LvAccellerate |
flag | Enable OpenGL acceleration |
LvDisabled |
flag | Disable viewer (runtime) |
Skip the OpenGL extension hint flags (LvGl*, LvWgl*, LvIsAccellerated) — these
are driver-level internals, not user-facing.
Section (h): Internal / Runtime Options — NOT to document
These Lc* options are internal state, not user-facing:
LcMainWindowX/Y/Width/Height,LcWindowMaximized,LcWindowPos*,LcWindowSize*— window stateLcSerialNumber,LcMaintenanceExp,LcNetworkLicense— licensingLcPrevVersion— migration stateLcSplashMinDuration,LcSplashOverlap,LcShowSplash— splash screen timingLcSessionMru— MRU list (managed by GUI)LcSuccess— runtime flagLcKeepTempFiles— debuggingLcDumpMemoryUsage— debuggingLcPythonScript/Cmd/InteractiveasLc*variants — redundant with modern--python-*LcUserUnitsNm— runtime calculationLcWriteLayerMap— runtimeLcApplyLayerMapBatch— runtime
These should NOT appear in user documentation.
Implementation Order
- Fix errors — Remove
--versionfromcli.mdandcli-parameters.md - Add automation options — Add
Lc*automation options toautomation/cli.md - Add batch tool keys — Add key names to
automation/batch.md - Add format-specific option keys — Add "CLI / Command-File Options" section to each format page that has options (13 format pages)
- Add drawing tool options — Add
Tool*options section toreference/cli-parameters.md - Add viewer options — Add
Lv*options section toreference/cli-parameters.md - Add common cross-format option — Document
TextLineWidthRelinreference/cli-parameters.md - Add orphaned format options — Add
StepOutUnitsto step.md,IgesOutUnitsto iges.md,XtOutExplodeArcsto parasolid.md,DwgOut*to dwg.md - Rebuild & verify —
mkdocs build