Batch Operations

The apply_batch tool applies multiple schematic modifications atomically from a JSON file. All operations share a single load-save cycle for performance and consistency.

Overview

Batch files live in the .mckicad/ sidecar directory by default (next to the schematic). The schema supports six operation types, processed in dependency order:

1. components — placed first so pin-reference wires can find them
2. power_symbols — attached to component pins
3. wires — connect components by coordinates or pin references
4. labels — local or global net labels, by coordinates or pin references
5. label_connections — place the same net label on multiple pins simultaneously
6. no_connects — no-connect flags by coordinates or pin references

Usage

Apply the batch file circuit.json to my schematic at /path/to/project.kicad_sch

Dry run

Validate the batch without modifying the schematic:

Apply the batch file circuit.json to my schematic with dry_run=True

Returns validation results and a preview of what would be applied.

Hierarchy context

For sub-sheets in a hierarchical design, pass parent_uuid and sheet_uuid (both returned by add_hierarchical_sheet). This sets the instance path so that kicad-cli correctly resolves power symbol nets during netlist export.

Without hierarchy context, power symbols (GND, +3V3, etc.) may be silently dropped from the netlist.

JSON schema

{
  "components": [
    {
      "lib_id": "Device:C",
      "reference": "C1",
      "value": "100nF",
      "x": 100,
      "y": 200,
      "rotation": 0,
      "unit": 1
    }
  ],
  "power_symbols": [
    {
      "net": "GND",
      "pin_ref": "C1",
      "pin_number": "2",
      "lib_id": "power:GND",
      "stub_length": 2.54
    }
  ],
  "wires": [
    {
      "start_x": 100,
      "start_y": 200,
      "end_x": 200,
      "end_y": 200
    },
    {
      "from_ref": "R1",
      "from_pin": "1",
      "to_ref": "R2",
      "to_pin": "2"
    }
  ],
  "labels": [
    {
      "text": "SPI_CLK",
      "x": 150,
      "y": 100,
      "global": false,
      "rotation": 0
    },
    {
      "text": "GPIO5",
      "pin_ref": "U8",
      "pin_number": "15",
      "global": true,
      "shape": "bidirectional",
      "direction": "left",
      "stub_length": 2.54
    }
  ],
  "label_connections": [
    {
      "net": "BOOT_MODE",
      "global": true,
      "shape": "bidirectional",
      "stub_length": 2.54,
      "connections": [
        {"ref": "U8", "pin": "48"},
        {"ref": "R42", "pin": "1", "direction": "right", "stub_length": 5.08}
      ]
    }
  ],
  "no_connects": [
    {"x": 300, "y": 300},
    {"pin_ref": "U8", "pin_number": "33"}
  ]
}

Field reference

components

Field	Required	Type	Description
lib_id	yes	string	Library symbol ID (e.g., "Device:C", "MCU_Microchip:ATmega328P-PU")
reference	no	string	Reference designator (e.g., "C1", "U3")
value	no	string	Component value (e.g., "100nF", "10k")
x	yes	number	X position in schematic units (mm)
y	yes	number	Y position in schematic units (mm)
rotation	no	number	Rotation angle in degrees (default: 0)
unit	no	integer	Unit number for multi-unit components (default: 1)

power_symbols

Field	Required	Type	Description
net	yes	string	Power net name (e.g., "GND", "+3V3", "VCC")
pin_ref	yes	string	Reference of the component to attach to
pin_number	yes	string	Pin number on that component
lib_id	no	string	Override the power symbol library ID
stub_length	no	number	Wire stub length in mm

wires

Wires accept either coordinate mode or pin-reference mode:

Coordinate mode:

Field	Required	Type	Description
start_x	yes	number	Wire start X
start_y	yes	number	Wire start Y
end_x	yes	number	Wire end X
end_y	yes	number	Wire end Y

Pin-reference mode:

Field	Required	Type	Description
from_ref	yes	string	Source component reference
from_pin	yes	string	Source pin number
to_ref	yes	string	Destination component reference
to_pin	yes	string	Destination pin number

labels

Labels accept either coordinate placement or pin-reference placement (with automatic wire stub):

Field	Required	Type	Description
text	yes	string	Label text (net name)
x	coord mode	number	X position
y	coord mode	number	Y position
pin_ref	pin mode	string	Component reference to attach to
pin_number	pin mode	string	Pin number on that component
global	no	boolean	True for global label, false for local (default: false)
rotation	no	number	Rotation in degrees (default: auto-calculated for pin mode)
shape	no	string	Global label shape: "bidirectional", "input", "output", etc.
direction	no	string	Override label direction: "left", "right", "up", "down"
stub_length	no	number	Wire stub length in mm

label_connections

Place the same net label on multiple pins simultaneously:

Field	Required	Type	Description
net	yes	string	Net name for all labels
global	no	boolean	True for global labels (default: false)
shape	no	string	Global label shape
stub_length	no	number	Default stub length for all connections
connections	yes	array	List of pin connections

Each connection in the connections array:

Field	Required	Type	Description
ref	yes	string	Component reference
pin	yes	string	Pin number
direction	no	string	Override label direction for this pin
stub_length	no	number	Override stub length for this pin

no_connects

No-connect flags accept either coordinate or pin-reference placement:

Field	Required	Type	Description
x	coord mode	number	X position
y	coord mode	number	Y position
pin_ref	pin mode	string	Component reference
pin_number	pin mode	string	Pin number

Batch limits

The following limits are enforced during validation:

Limit	Value
Max components per batch	Configured in BATCH_LIMITS
Max wires per batch	Configured in BATCH_LIMITS
Max labels per batch	Configured in BATCH_LIMITS (includes label_connections)
Max total operations	Configured in BATCH_LIMITS

Validation

Before applying, the batch tool validates:

• All required fields are present
• No unknown top-level keys
• Component lib_id values reference valid libraries
• Pin references (pin_ref, from_ref, to_ref) exist in the schematic or are declared in the same batch
• Operation counts are within limits

Project-local symbol libraries (referenced in sym-lib-table) are automatically registered with the kicad-sch-api cache so that non-standard lib_id values resolve correctly.

Collision detection

When placing pin-referenced labels, the batch tool:

1. Clamps stub length to avoid bridging adjacent pins
2. Resolves label collisions — shifts labels that would overlap existing ones
3. Resolves wire collisions — adjusts wire stubs that would overlap existing wire segments

The summary reports how many collisions were resolved.

Return value

On success:

{
  "success": true,
  "components_placed": 5,
  "component_refs": ["C1", "C2", "R1", "R2", "U1"],
  "power_symbols_placed": 3,
  "wires_placed": 4,
  "labels_placed": 6,
  "no_connects_placed": 2,
  "collisions_resolved": 1,
  "wire_collisions_resolved": 0,
  "total_operations": 20,
  "batch_file": "/path/to/.mckicad/circuit.json",
  "schematic_path": "/path/to/project.kicad_sch",
  "engine": "kicad-sch-api"
}