CLI command design

pcbdoc

Authors PCB documents through generated MCO operations.

Purpose

pcbdoc creates small blank board files for fixtures and generated projects. The initial release supports simple rigid boards, rectangular board outlines, generated copper/dielectric layer stacks, and optional standard mechanical layer kind initialization.

Usage

altium-cruncher pcbdoc create
altium-cruncher pcbdoc create pcbdoc_create.jsonc
altium-cruncher pcbdoc create board.PcbDoc
altium-cruncher pcbdoc create board.PcbDoc --layers 4 --width-mils 3000 --height-mils 2000
altium-cruncher pcbdoc create board.PcbDoc --mechanical-layer-profile standard_component_pairs --json
altium-cruncher pcbdoc create board.PcbDoc --stackupx-file board.stackupx --json
altium-cruncher pcbdoc create board.PcbDoc --layer-stack-template 2-layer

Arguments

Argument	Contract
`create`	With no target, writes `pcbdoc_create.jsonc` when no config exists. A later no-target run loads that config and creates the PCB document.
`create config.jsonc`	Loads or initializes a PcbDoc create config using schema `altium_cruncher.pcbdoc.create.config.a0`.
`create file`	Legacy direct mode. Destination `.PcbDoc`. Paths are passed into generated MCO as `file`.
`--layers`	Generated rigid copper layer count when neither `--layer-stack-template` nor `--stackupx-file` is supplied. The default is two copper layers.
`--layer-stack-template`	Uses an Altium Monkey built-in layer-stack template instead of generated rigid stack rows.
`--stackupx-file`	Imports a `.stackupx` file through Altium Monkey's typed layer-stack document path instead of generated rigid stack rows.
`--width-mils`, `--height-mils`	Rectangular board outline size in mils.
`--mechanical-layer-profile`	`none`, `standard_component_pairs`, or `v7_mechanical_53`. Profiles expand into explicit mechanical layer names, enabled states, layer pairs, and supported layer kinds in the generated MCO.
`--emit-mco`, `--force`, `--dry-run`, `--json`, `--json-output`	Follow the shared MCO command semantics for operation emission, overwrite, non-mutating planning, stdout JSON, and sidecar JSON report output.

Config Shape

The A0 config is the same child object shape used by prjpcb.pcb, with a top-level schema field. Generated configs include a rectangular board outline, generated rigid layer stack, editable single mechanical_layers, and grouped mechanical_layer_pairs with top and bottom layer rows. Configs may replace the generated rigid stack with one layer_stack_template or stackupx_file value. The template header documents valid mechanical layer ids, indexes, default names, and mechanical layer kind enum values.

MCO Shape

pcbdoc create compiles to one pcbdoc.create operation. Generated rigid stacks are passed as rigid_stack. The standard mechanical profile or explicit config rows are expanded into mechanical_layers, mechanical_layer_pairs, and mechanical_layer_kinds rather than stored as an opaque profile token.

Stackup Scope

stackupx_file imports an Altium .stackupx file through Altium Monkey's typed layer-stack document path before the PcbDoc is saved. Generated rigid rows remain capped to the legacy rigid-stack helper, while large signal-count boards should use stackupx_file. Since altium-monkey==2026.8.1, StackUpX layer ids must be GUID strings; non-GUID ids fail the create operation with the upstream guard message, which suggests omitting explicit ids to use generated GUIDs. Boards imported from an extended-signal .stackupx support V7 signal tokens such as MID31 in later authoring operations.

Output

The first config-first run writes the sample JSONC config only; the next run uses that config to write the requested .PcbDoc unless --dry-run is used. Tests reparse generated boards and verify copper layer names plus mechanical layer kind readback.

Tests

Coverage lives in tests/test_mco.py and tests/test_document_create_commands.py. It verifies generated rigid stack creation, standard mechanical layer-kind profile expansion, command JSON output, Altium Monkey reparse of generated boards, StackUpX extended-signal creation with V7 token authoring, and actionable StackUpX GUID-enforcement errors.