| get_schematic_summaryA | Get schematic page info and item counts. Args:
schematic_path: Path to .kicad_sch file. Optional; omit to use the configured default.
|
| list_schematic_componentsA | List all placed components in the schematic. Args:
schematic_path: Path to .kicad_sch file. Optional; omit to use the configured default.
|
| list_schematic_labelsA | List all net labels in the schematic. Args:
schematic_path: Path to .kicad_sch file. Optional; omit to use the configured default.
|
| list_schematic_wiresA | List all wire segments in the schematic. Args:
schematic_path: Path to .kicad_sch file. Optional; omit to use the configured default.
|
| list_schematic_global_labelsA | List all global labels in the schematic. Args:
schematic_path: Path to .kicad_sch file. Optional; omit to use the configured default.
|
| list_schematic_hierarchical_labelsA | List all hierarchical labels in the schematic. Args:
schematic_path: Path to .kicad_sch file. Optional; omit to use the configured default.
|
| list_schematic_sheetsA | List all hierarchical sheets in the schematic. Args:
schematic_path: Path to .kicad_sch file. Optional; omit to use the configured default.
|
| list_schematic_junctionsA | List all junctions in the schematic. Args:
schematic_path: Path to .kicad_sch file. Optional; omit to use the configured default.
|
| list_schematic_no_connectsA | List all no-connect flags in the schematic. Args:
schematic_path: Path to .kicad_sch file. Optional; omit to use the configured default.
|
| list_schematic_bus_entriesA | List all bus entries in the schematic. Args:
schematic_path: Path to .kicad_sch file. Optional; omit to use the configured default.
|
| get_symbol_pinsA | Get pin info for a symbol in the schematic's lib_symbols. Args:
symbol_name: Symbol name (e.g. "LM7805", "C", "Fuse")
schematic_path: Path to .kicad_sch file. Optional; omit to use the configured default.
|
| get_pin_positionsA | Get absolute pin positions for a placed component (accounts for rotation/mirror). A multi-unit part is placed as one symbol per unit and they all share the
reference, so every placed unit is listed, each with its own pins plus the
unit-0 pins they all share.
Args:
reference: Component reference (e.g. "U1", "R1")
schematic_path: Path to .kicad_sch file. Optional; omit to use the configured default.
|
| get_net_connectionsA | Find all component pins connected to a net label. Scans labels matching the text, traces wires from label positions,
and identifies component pins at wire endpoints. Each placed symbol
contributes only its own unit's pins, so a multi-unit part does not
report a sibling gate's input as sitting on this net.
Args:
label_text: Net name to search for (e.g. "VCC", "GND")
schematic_path: Path to .kicad_sch file. Optional; omit to use the configured default.
|
| place_componentA | Place a schematic symbol: resistor, capacitor, inductor, diode, LED,
transistor, crystal, switch, connector, or an IC such as a microcontroller
or regulator chip. Any lib_id in a library works. Args:
lib_id: Library identifier (e.g. "Device:R", "Device:C", "MyLib:MyPart")
reference: Reference designator (e.g. "R1", "U1")
value: Component value (e.g. "10K", "100nF")
x: X position in schematic units (mm)
y: Y position in schematic units (mm)
rotation: Rotation angle in degrees (0, 90, 180, 270)
symbol_lib_path: Path to a .kicad_sym file that defines the symbol, for a
library outside KiCad's stock set. Optional; omit to load the symbol
from the stock library named by the lib_id prefix.
mirror: Mirror axis ("x", "y", or "" for none)
schematic_path: Path to .kicad_sch file. Optional; omit to use the configured default.
project_path: Path to .kicad_pro file (for correct hierarchy resolution in sub-sheets)
|
| remove_componentA | Remove a component by reference designator. Args:
reference: Reference designator to remove (e.g. "U2")
schematic_path: Path to .kicad_sch file. Optional; omit to use the configured default.
|
| remove_labelA | Remove net label(s) or global label(s) by text, optionally filtered by position. If x and y are provided, only removes labels matching both text AND
position (within 0.1mm tolerance). Otherwise removes ALL labels with
matching text. To move a global label, remove it and re-add with
add_global_label (which takes shape and rotation).
Args:
text: Label text to match (e.g. "VCC", "PGND")
x: Optional X position filter
y: Optional Y position filter
schematic_path: Path to .kicad_sch file. Optional; omit to use the configured default.
|
| remove_wireA | Remove a wire segment by its endpoint coordinates. Matches wires with endpoints within 0.1mm tolerance (in either order).
Use list_schematic_wires to get wire coordinates first.
Args:
x1: Start X
y1: Start Y
x2: End X
y2: End Y
schematic_path: Path to .kicad_sch file. Optional; omit to use the configured default.
|
| remove_junctionA | Remove a junction at the given coordinates, as KiCad's delete removes one. The junction within 0.1 mm goes, with any other at exactly its point. Then, as KiCad's
DeleteJunction does (bus-wire-junction.cpp:115-185 at 9.0.8), of the wires and buses
ending there each parallel pair is made one, or one of two identical lines goes, so
whatever met only at the junction is disconnected: a T loses its stem, a crossing becomes
two wires that do not join. Wires that merely meet there at an angle stay joined. Where a
bus entry ends at the point nothing is merged, since kicad-cli 9 cuts a wire at a bus entry
end inside it. The result names each merge.
Args:
x: X position
y: Y position
schematic_path: Path to .kicad_sch file. Optional; omit to use the configured default.
|
| add_wiresA | Add multiple wires at once, as KiCad's wire tool adds them. Each wire dict has keys:
x1, y1, x2, y2. Following SCH_LINE_WIRE_BUS_TOOL::finishSegments (sch_line_wire_bus_tool.cpp:1168-1276 at
9.0.8): a junction goes wherever three or more wire directions, pins or sheet pins meet,
at a new wire's end or at a point already on the sheet that a new wire runs through (a
pin, a wire end), and every wire through a junction is split there, so a T, or a wire
drawn through a pin, joins in every reader. As KiCad merges the new wire with the
collinear wires of its stroke that it overlaps or meets end to end (where no junction
is), a stretch such a wire already covers is left out, and a merged run holding both
pins of a two-pin part loses the stretch between them, so drawing across a part never
shorts it. A wire of no length is left out, as KiCad's tool drops one. Existing wires
are only ever split: where KiCad's trim would cut a wire already on the sheet, the call
is refused and nothing is written. The result counts the wire nodes written and names
each junction, split, left-out and trimmed stretch; when nothing changes it says so and
writes nothing.
Args:
wires: List of wire defs [{x1, y1, x2, y2}, ...]
schematic_path: Path to .kicad_sch file. Optional; omit to use the configured default.
|
| add_labelA | Add a net label at a position. Args:
text: Net name (e.g. "VIN_PROT", "5V_REL")
x: X position
y: Y position
rotation: Degrees (0=right, 90=up, 180=left, 270=down)
schematic_path: Path to .kicad_sch file. Optional; omit to use the configured default.
|
| add_junctionsA | Add multiple junctions, as KiCad's junction tool places them. Each point dict has
keys: x, y. A junction joins only where three or more wire directions, pins or sheet pins meet: a
crossing, a T, a wire end at a pin with another wire. Anywhere else (empty space, a
straight wire's interior, an L corner, a wire ending at a pin) KiCad's editor refuses it,
"Junction location contains no joinable wires and/or pins." (sch_drawing_tools.cpp:
1465-1497 at 9.0.8), and its cleanup deletes one placed there, so the whole call is
refused, naming each such point, and nothing is written. Every wire through a junction
is split there, which kicad-cli 9 needs to read the join; where a junction is already
exactly at a point no second one is added, but a wire still running through it is split.
A point where KiCad allows a junction, or where one already is, is taken even off the
page: it lies on wires or pins already drawn, which KiCad reads there as anywhere else.
Any other point off the page is refused as off the page. The result names each junction
written, each one already there and each split.
Args:
points: List of junction positions [{x, y}, ...]
schematic_path: Path to .kicad_sch file. Optional; omit to use the configured default.
|
| add_lib_symbolC | Load a symbol definition from a .kicad_sym library into the schematic. Args:
symbol_lib_path: Path to .kicad_sym file. Optional; omit to use the configured default.
symbol_name: Symbol name (e.g. "LM7805")
schematic_path: Path to .kicad_sch file. Optional; omit to use the configured default.
|
| move_componentA | Move a placed component, turn it, or both. The symbol and all its fields move together: each field keeps its place relative to the
symbol, rotation included, and keeps its own text angle, so KiCad draws it turning with
the symbol. KiCad's GUI would also re-place auto-placed fields after a turn when its
autoplace preference is on; this tool does not.
Wires, labels, junctions and no-connect flags stay where they are, as with KiCad's own
Move. The result lists every pin whose connections changed (what it left, what it now
meets); reconnect those with wire_pins_to_net or connect_pins.
x and y snap to the 1.27 mm grid when the symbol moves, and the grid point must lie on the
page. Passing the symbol's own position (as list_schematic_components reports it) turns it in
place without snapping, wherever it stands, off the page included. Nothing is written when
nothing would change.
Args:
reference: Reference designator (e.g. "R1")
x: New X position
y: New Y position
rotation: The absolute angle in degrees (None = keep current); a mirrored symbol keeps
its mirror. It is written as KiCad writes it, so it also repairs an angle KiCad
cannot load, such as 45, +90 or none; a call without it refuses one this tool
cannot read as 0, 90, 180 or 270.
schematic_path: Path to .kicad_sch file. Optional; omit to use the configured default.
|
| set_component_propertyA | Set any property on a placed component, or rename it. Creates the
property if it is missing. Reference, Value and Footprint are mirrored into the symbol's own
instances and into the root symbol_instances table, so setting
key="Reference" is how a component is renamed and both views stay in
step. The root table needs the .kicad_pro to resolve the hierarchy
path; a loose .kicad_sch with no project beside it keeps the symbol
correct and leaves that table alone.
Args:
reference: Component reference (e.g. "R1")
key: Property name (e.g. "MPN", "Tolerance", "Value")
value: Property value
schematic_path: Path to .kicad_sch file. Optional; omit to use the configured default.
|
| set_page_sizeA | Set the schematic page/sheet size. Args:
size: Standard name (A5, A4, A3, A2, A1, A0, A, B, C, D, E) or 'User' for custom
width: Custom width in mm (required when size='User')
height: Custom height in mm (required when size='User')
portrait: If True, swap width/height for portrait orientation
schematic_path: Path to .kicad_sch file. Optional; omit to use the configured default.
|
| add_global_labelA | Add a global net label (visible across all sheets). Args:
text: Net name (e.g. "VCC", "SDA")
x: X position
y: Y position
rotation: Degrees (0=right, 90=up, 180=left, 270=down)
shape: Label shape: input, output, bidirectional, tri_state, passive
schematic_path: Path to .kicad_sch file. Optional; omit to use the configured default.
|
| add_hierarchical_labelA | Add a hierarchical label to a sub-sheet schematic. Args:
text: Label name (must match parent sheet pin name)
shape: Direction — input, output, bidirectional, tri_state, passive
x: X position in mm
y: Y position in mm
rotation: Degrees (0, 90, 180, 270)
schematic_path: Path to .kicad_sch file. Optional; omit to use the configured default.
|
| remove_hierarchical_labelA | Remove a hierarchical label by name or UUID. Args:
text: Label text to match
schematic_path: Path to .kicad_sch file. Optional; omit to use the configured default.
uuid: Optional UUID for disambiguation when multiple labels share a name
|
| modify_hierarchical_labelA | Modify an existing hierarchical label. Args:
text: Current label text to find
schematic_path: Path to .kicad_sch file. Optional; omit to use the configured default.
new_text: New label text (empty = keep current)
new_shape: New shape/direction (empty = keep current)
new_x: New X position (None = keep current)
new_y: New Y position (None = keep current)
uuid: UUID for disambiguation
|
| add_power_symbolA | Place a power symbol (VCC, GND, +3V3, etc.). Uses place_component internally. Power symbols are regular symbols
from the 'power' library with isPower=True.
Places only the symbol asked for. A PWR_FLAG tells ERC the net has a
source it cannot see, which only the designer knows, so add one with
lib_id="power:PWR_FLAG" on each net that needs it.
Args:
lib_id: Library ID (e.g. "power:VCC", "power:GND")
reference: Reference (e.g. "#PWR01")
x: X position
y: Y position
rotation: Rotation in degrees
symbol_lib_path: Path to a .kicad_sym file that defines the power symbol,
for a library outside KiCad's stock set. Optional; omit to load it
from the stock library named by the lib_id prefix.
schematic_path: Path to .kicad_sch file. Optional; omit to use the configured default.
project_path: Path to .kicad_pro file (for sub-sheet instance tracking)
|
| auto_place_decoupling_capA | Place a decoupling capacitor and wire it to power/ground nets. Places the cap, wires pin 1 (top) to power_net and pin 2 (bottom)
to ground_net via stub wires + labels.
Args:
lib_id: Cap symbol (e.g. "Device:C")
reference: Reference (e.g. "C5")
value: Cap value (e.g. "100nF")
x: X position
y: Y position
power_net: Label for pin 1 (e.g. "VCC", "+3V3")
ground_net: Label for pin 2 (e.g. "GND", "PGND")
rotation: Rotation in degrees (default 0)
symbol_lib_path: Path to a .kicad_sym file that defines the capacitor,
for a library outside KiCad's stock set. Optional; omit to load it
from the stock library named by the lib_id prefix.
schematic_path: Path to .kicad_sch file. Optional; omit to use the configured default.
project_path: Path to .kicad_pro file (for sub-sheet instance tracking)
|
| add_textB | Add a text annotation to the schematic. Args:
text: Text content
x: X position
y: Y position
rotation: Rotation in degrees
schematic_path: Path to .kicad_sch file. Optional; omit to use the configured default.
|
| remove_textA | Remove text annotation(s) by content, optionally filtered by position. If x and y are provided, only removes texts matching both content AND
position (within 0.1mm tolerance). Otherwise removes ALL texts with
matching content.
Args:
text: Text content to match
x: Optional X position filter
y: Optional Y position filter
schematic_path: Path to .kicad_sch file. Optional; omit to use the configured default.
|
| wire_pins_to_netA | Put each listed pin on the net named label_text, or refuse and write nothing. Each pin gets a short wire stub pointing away from its symbol, with a net
label at the stub's end. When the stub would touch, overlap or cross
anything else on the sheet, or move a net into another net class, the
label goes on the pin end itself instead. No junction is ever written, and
a pin already on the net is left alone. The file is written once or not
at all.
The whole call is refused when any pin cannot be wired safely: its net may
already carry another name, it may reach something this tool cannot judge
(a bus, a sheet pin, a text variable, a copy of the pad on another sheet),
another part shares its reference, or every position is blocked. The
refusal lists every refused pin with a bracketed reason code such as
[names] or [touch], the obstacle, and a remedy. add_label and add_wires
check none of this, so they are no way around a refusal.
It places no PWR_FLAG: whether a net needs one depends on every driver on
the net, not on the pins in one call. Use add_power_symbol for that.
Args:
pins: List of {"reference": "R1", "pin": "1"} dicts
label_text: Net name (e.g. "GND", "VCC"), exactly as it should read: no surrounding
spaces, no leading "/", no text variable ("${...}"), no bus syntax, not a KiCad
auto name such as "Net-(R1-1)"
direction: Stub direction: "auto" (away from the symbol), "left", "right", "up", "down"
stub_length: Stub length in mm, a multiple of 1.27 up to 1000 (default 2.54)
schematic_path: Path to .kicad_sch file. Optional; omit to use the configured default.
|
| connect_pinsA | Connect two component pins with Manhattan (L-shaped) wire routing. Combines get_pin_positions + coordinate math + add_wires into one call. At its own
points (both pins and the L's corner) a junction goes where three or more directions
meet, and any wire through it is split there, as KiCad's wire tool does
(sch_line_wire_bus_tool.cpp:1263-1267 at 9.0.8); a leg running through a junction or a
bus entry end already on the sheet is split there too, as KiCad's cleanup splits it. The
result names each junction and split.
Args:
ref1: First component reference (e.g. "U1")
pin1: First pin name or number
ref2: Second component reference (e.g. "C3")
pin2: Second pin name or number
schematic_path: Path to .kicad_sch file. Optional; omit to use the configured default.
|
| no_connect_pinA | Place a no-connect flag on a component pin. Resolves pin position and places a no-connect flag. Idempotent:
calling again for a pin that already has one is a no-op.
Args:
reference: Component reference (e.g. "U2")
pin_name: Pin name (e.g. "NC") or number (e.g. "3")
schematic_path: Path to .kicad_sch file. Optional; omit to use the configured default.
|
| remove_no_connectA | Remove no-connect flag(s) from a component pin. Removes every no-connect at the pin's position, so stacked
duplicates from repeated no_connect_pin calls clear in one go.
Args:
reference: Component reference (e.g. "U2")
pin_name: Pin name (e.g. "NC") or number (e.g. "3")
schematic_path: Path to .kicad_sch file. Optional; omit to use the configured default.
|
| list_unconnected_pinsA | List unconnected pins by running ERC and filtering results. Requires kicad-cli. Lists the violations KiCad types pin_not_connected. A
sub-sheet is checked from its project's root, as run_erc does, and gets
the pins of that sheet alone, under every top-level sheet the project lists.
A sheet below a top-level sheet other than the root is refused when that
kicad-cli did not check it from the root. A run that makes no report
raises and leaves output_dir as it was.
The x and y of each entry are millimetres (mm) in sheet coordinates, the
numbers get_pin_positions prints.
Args:
schematic_path: Path to .kicad_sch file. Optional; omit to use the configured default.
output_dir: Directory for ERC report file. Optional; omit to use the configured default.
project_path: Path to .kicad_pro file; the project whose hierarchy to look in.
Refused when no sheet of it uses the file.
|
| run_ercA | Run Electrical Rules Check (ERC) on a schematic. A sub-sheet is checked from its project's root, so the hierarchy around it
counts, and only that sheet's own violations are returned, those of every
use of it under every top-level sheet the project lists. A sheet below a
top-level sheet other than the root is refused when that kicad-cli did not
check it from the root; run_erc on that top-level sheet checks it on its
own. A file that no sheet of its project uses is checked on its own. A run
that makes no report raises and leaves output_dir as it was.
Returns JSON report with violations. An item's position is in
millimetres (mm) in sheet coordinates, the numbers get_pin_positions prints.
The report file saved in output_dir is kicad-cli's own.
Args:
schematic_path: Path to .kicad_sch file. Optional; omit to use the configured default.
output_dir: Directory for report file (default: beside the file ERC runs on).
Optional; omit to use the configured default.
project_path: Path to .kicad_pro file; the project whose hierarchy to look in.
Refused when no sheet of it uses the file.
|
| export_schematicA | Export schematic to PDF, SVG, or DXF format. pdf and dxf produce one file, so path names it and size_bytes is filled.
svg produces one file per sheet, so path names the directory. files and
count are filled either way.
Args:
format: Output format - "pdf", "svg", or "dxf"
schematic_path: Path to .kicad_sch file. Optional; omit to use the configured default.
output_dir: Directory for output files. Optional; omit to use the configured default.
|
| export_netlistA | Export a schematic netlist. Args:
schematic_path: Path to .kicad_sch file. Optional; omit to use the configured default.
output_dir: Output directory. Optional; omit to use the configured default.
format: Netlist format. spice and spicemodel produce simulator input.
|
| export_bomA | Export Bill of Materials (BOM) as CSV. Args:
schematic_path: Path to .kicad_sch file. Optional; omit to use the configured default.
output_dir: Output directory. Optional; omit to use the configured default.
|
| list_pcb_footprintsA | List all footprints on the PCB. Args:
pcb_path: Path to .kicad_pcb file. Optional; omit to use the configured default.
|
| list_pcb_tracesA | List all trace segments and vias on the PCB. Args:
pcb_path: Path to .kicad_pcb file. Optional; omit to use the configured default.
|
| list_pcb_netsA | List all named nets on the PCB. Args:
pcb_path: Path to .kicad_pcb file. Optional; omit to use the configured default.
|
| list_pcb_zonesA | List all zones (copper and keepout) on the PCB. Args:
pcb_path: Path to .kicad_pcb file. Optional; omit to use the configured default.
|
| list_pcb_layersA | List all layers defined in the PCB stackup: copper, silkscreen,
soldermask, solder paste, courtyard, fabrication, and the board outline. Which of those a given board actually defines is up to the board. Call
this before any tool that takes a layer name, since the valid set is
per-board and renamed layers are common.
Args:
pcb_path: Path to .kicad_pcb file. Optional; omit to use the configured default.
|
| list_pcb_graphic_itemsA | List all graphic items (lines, text, etc.) on the PCB. Args:
pcb_path: Path to .kicad_pcb file. Optional; omit to use the configured default.
|
| get_board_infoA | Get board summary: footprint count, trace count, net count, thickness.
The net count includes the unconnected net, as KiCad's own count does. Args:
pcb_path: Path to .kicad_pcb file. Optional; omit to use the configured default.
|
| get_footprint_padsA | Get pad info for a placed footprint on the PCB. Args:
reference: Footprint reference (e.g. "R1", "U1")
pcb_path: Path to .kicad_pcb file. Optional; omit to use the configured default.
|
| place_footprintA | Place a footprint on the PCB. Name a library and a footprint to place the real thing: its pads, silkscreen,
courtyard and 3D model are copied from the library file exactly as KiCad
would place them, a footprint in KiCad 7's form taking the reference and value
in its own (fp_text reference|value ...), where one holding %V or %R, which KiCad
reads there as a variable, is refused. Without them you get a marker carrying
only the reference and value, which has NO PADS and so cannot be routed or
checked; that is the older behaviour and it is kept for callers that only want a
placeholder.
Use list_lib_footprints to see what a library holds.
The footprint is turned to its rotation as KiCad's own rotate turns it: every
pad and text turns with it (a pad's angle is its library angle plus the
footprint's), and a keep-upright text that would read upside down is turned
half a turn with its justification mirrored, so it stays readable on the same
side of its anchor. Angles are written as KiCad writes them: the footprint's
between -180 and 180 and left out at 0, each pad's and text's absolute. Off the
quarter turns the result reads as KiCad's placement without matching pcbnew's
save byte for byte: footprint-relative coordinates stay as the library writes
them where pcbnew re-derives them through two RotatePoint roundings, an fp_rect
stays where pcbnew writes an fp_poly, and arc mid points stay as written. A
library footprint without a Datasheet or Description field is placed without
it, so KiCad reads that hidden field at its default on F.Fab, whereas pcbnew
writes it, on B.Fab for a placement on the back.
Zones the footprint owns (keepouts, say) and a KiCad 10 footprint's points are
stored in board coordinates (format( ZONE ), pcb_io_kicad_sexpr.cpp:2628-2637 at
9.0.8), so they land where KiCad's placement puts them: moved with the footprint,
turned about it and, on the back, mirrored with it.
A footprint carrying what this tool does not move with it (a dimension, image,
table or barcode, or a child no KiCad it knows reads), or on the back what it does
not flip (see move_footprint), is refused and nothing is written.
Args:
reference: Reference designator (e.g. "R2")
value: Component value (e.g. "4.7K")
x: X position in mm
y: Y position in mm
rotation: The footprint's angle in degrees, counter-clockwise as seen on
screen; any finite value (270 is stored as -90, 360 as 0). inf and nan
are refused and nothing is written.
layer: F.Cu or B.Cu; any other layer is refused. B.Cu places the footprint
flipped as KiCad's own flip does, then turns it to rotation
(FOOTPRINT::Flip, pcbnew/footprint.cpp:2491-2550 at 9.0.8).
library: Footprint library nickname (e.g. "Resistor_SMD"), or a path to a
.pretty directory. A nickname is resolved as update_pcb_from_schematic
resolves it: the project's fp-lib-table beside the board, .pretty
directories beside the board, KICAD_FP_LIB, the user's global
fp-lib-table (with the libraries the Plugin and Content Manager
installed), then KiCad's stock footprints. Optional; omit for a
pad-less marker.
footprint: Footprint name within that library (e.g. "R_0805_2012Metric").
Required when library is given.
pcb_path: Path to .kicad_pcb file. Optional; omit to use the configured default.
|
| move_footprintA | Move a footprint to a new position. A move rewrites the footprint's own position and nothing of its pads, texts
or graphics, which KiCad stores relative to the footprint. The zones it owns
and a KiCad 10 footprint's points are stored in board coordinates, so they
move by the same delta, as KiCad's FOOTPRINT::SetPosition moves them
(pcbnew/footprint.cpp:2553-2584 at 9.0.8). A rotation turns the footprint to
that angle as KiCad's own rotate turns it: every pad and text turns by the
change from the angle it had, its zones and points turn about it, and a
keep-upright text that would read upside down is turned half a turn with its
justification mirrored, so it stays readable on the same side of its anchor.
Angles are written as KiCad writes them: the footprint's between -180 and 180
and left out at 0. Off the quarter turns the result reads as KiCad's turn
without matching pcbnew's save byte for byte: footprint-relative coordinates
stay as written where pcbnew re-derives them through two RotatePoint roundings,
an fp_rect stays where pcbnew writes an fp_poly, and arc mid points stay as
written. A footprint carrying what this tool does not move with it
(a dimension, image, table or barcode, or a child no KiCad it knows reads) is
refused and nothing is written. The keep-out warning reads keepouts as
check_placement does.
Args:
reference: Reference designator (e.g. "R1")
x: New X position
y: New Y position
rotation: The footprint's angle after the move, in degrees (None keeps the
current one). An angle the footprint already has (270 for one at -90,
360 for one at 0) changes nothing and leaves the file byte-identical,
where KiCad's footprint properties dialog would still re-run its
rotate by a full turn. inf and nan are refused and nothing is written.
layer: F.Cu or B.Cu (empty keeps the side; anything else is refused). The
other side flips the footprint as KiCad's own flip does (FOOTPRINT::Flip,
pcbnew/footprint.cpp:2491-2550 at 9.0.8): pads, texts and graphics
mirror, their layers go to their opposites on this board (user layers it
pairs included), a text's mirror toggles on side-specific layers only,
zones and points mirror about the footprint with their layers, and 3D
models stay as they are. With a rotation the flip comes first, so
rotation names the angle the footprint ends at. Refused, with nothing
written: a text box, a pad's own padstack, KiCad 10's back drills, and on
a board of four or more copper layers an item (a zone included) on inner
copper that does not name every inner layer, which KiCad 9 and 10 flip
apart.
pcb_path: Path to .kicad_pcb file. Optional; omit to use the configured default.
|
| check_placementA | Check if placing/moving a footprint to (x, y) would violate constraints. Both checks are on the footprint's origin point, not its courtyard, so a
footprint whose body overlaps a keep-out while its origin does not still
reports ok. That is also why there is no rotation parameter: rotating about
the origin cannot move the origin, so an angle could not change either
answer.
Keep-outs are read as KiCad reads them: a footprint's own keep-outs in board
coordinates, as the file stores them; a layer set such as *.Cu or F&B.Cu as
the layers it names; the footprint on its side, B.Cu or else F.Cu, as KiCad
reads any other footprint layer; and the footprint's own keep-outs never
count against it (intersectsArea skips an area whose parent is the item,
pcbnew/pcbexpr_functions.cpp:697 at 9.0.8).
Args:
reference: Footprint reference designator
x: Proposed X position
y: Proposed Y position
pcb_path: Path to .kicad_pcb file. Optional; omit to use the configured default.
|
| remove_footprintA | Remove a footprint by reference designator. Args:
reference: Reference designator (e.g. "R1")
pcb_path: Path to .kicad_pcb file. Optional; omit to use the configured default.
|
| add_traceA | Add a trace segment between two points. Args:
x1: Start X
y1: Start Y
x2: End X
y2: End Y
width: Trace width in mm
layer: Copper layer (e.g. "F.Cu", "B.Cu")
net: A net number from list_pcb_nets, or 0 for no net. Any other number is refused
and nothing is written, and so is every number but 0 on a board in KiCad 9's
format or older that has no net table. A KiCad 10 board holds nets by name and
its numbers are derived from where each net first appears, so read
list_pcb_nets again after an edit.
pcb_path: Path to .kicad_pcb file. Optional; omit to use the configured default.
|
| add_viaA | Add a via at a position. Args:
x: X position
y: Y position
size: Via pad size in mm
drill: Drill diameter in mm
net: A net number from list_pcb_nets, or 0 for no net. Any other number is refused
and nothing is written, and so is every number but 0 on a board in KiCad 9's
format or older that has no net table. A KiCad 10 board holds nets by name and
its numbers are derived from where each net first appears, so read
list_pcb_nets again after an edit.
layers: Via layers (default: ["F.Cu", "B.Cu"])
pcb_path: Path to .kicad_pcb file. Optional; omit to use the configured default.
|
| add_pcb_textA | Add text to the PCB (silkscreen, fab layer, etc.). Args:
text: Text content
x: X position
y: Y position
layer: Layer (e.g. "F.SilkS", "B.SilkS", "F.Fab")
rotation: Rotation in degrees
pcb_path: Path to .kicad_pcb file. Optional; omit to use the configured default.
|
| add_pcb_lineA | Add a graphic line to the PCB (edge cuts, silkscreen, etc.). Args:
x1: Start X
y1: Start Y
x2: End X
y2: End Y
layer: Layer (e.g. "Edge.Cuts", "F.SilkS")
width: Line width in mm
pcb_path: Path to .kicad_pcb file. Optional; omit to use the configured default.
|
| add_copper_zoneA | Create an unfilled copper zone: a ground plane, power plane, or any
filled copper pour. Call fill_zones afterward to compute the fills. Args:
net_name: Name of the net to assign to this zone (e.g. "GND")
layer: Copper layer (e.g. "F.Cu", "B.Cu")
corners: List of {x, y} dicts defining the zone polygon (min 3)
clearance: Zone clearance in mm
min_thickness: Minimum copper thickness in mm
thermal_relief: Use thermal relief pads (True) or solid connection (False)
thermal_gap: Thermal relief gap in mm
thermal_bridge_width: Thermal relief bridge width in mm
priority: Zone fill priority (higher fills first)
pcb_path: Path to .kicad_pcb file. Optional; omit to use the configured default.
|
| add_keepout_zoneA | Create a keep-out zone that restricts placement of specified items. Args:
corners: List of {x, y} dicts defining the zone polygon (min 3)
layers: Layers to apply keep-out to (default: ["F.Cu", "B.Cu"])
no_tracks: Restrict tracks in this zone
no_vias: Restrict vias in this zone
no_pads: Restrict pads in this zone
no_copper_pour: Restrict copper pour in this zone
no_footprints: Restrict footprints in this zone
pcb_path: Path to .kicad_pcb file. Optional; omit to use the configured default.
|
| fill_zonesA | Fill all copper zones on the board using pcbnew's zone filler. pcbnew computes the fill; this server writes it. The board is handed to
pcbnew read-only and the computed polygons come back as data, so the file
that reaches the disk is the original with its zones' fills replaced and
every other byte untouched. Nothing else about it changes: not its format
version, not its layer names, not the constructs pcbnew does not model.
Requires KiCad's pcbnew Python bindings to be installed.
Args:
pcb_path: Path to .kicad_pcb file. Optional; omit to use the configured default.
|
| update_pcb_from_schematicA | Update the PCB from the schematic (headless Tools -> Update PCB from Schematic). Exports the schematic's netlist, loads the assigned footprints from
libraries, and binds every pad to its net. Creates the .kicad_pcb if
it does not exist; new footprints land in a grid cluster at orientation
0, written as KiCad writes a footprint it has just loaded (no angle on the
footprint, library pad and text angles normalized as KiCad holds them). Existing
footprints are matched by reference and keep their position; a footprint in KiCad
7's form, on the board or from its library, takes the symbol's reference and value
in its (fp_text reference|value ...), and the update is refused when one holds %V or
%R, which KiCad reads there as a variable. A changed
footprint assignment swaps the footprint as KiCad's exchange does
(pcbnew/pcb_edit_frame.cpp:2346-2587 at 9.0.8): it keeps its position,
angle and side, its texts turned with it as the exchange turns them
(SetOrientation, then on a KiCad 10 board KeepUpright on those it pairs
with old ones), and its uuid, its pads' (by number; on a KiCad 10 board
only a number each footprint holds once) and its fields' (by name), so a
group still finds it. Off the quarter turns a swapped footprint reads as
KiCad's exchange leaves it without matching pcbnew's save byte for byte:
footprint-relative coordinates stay as the library writes them where
pcbnew re-derives them through two RotatePoint roundings, an fp_rect stays
where pcbnew writes an fp_poly, and arc mid points stay as written. A
locked footprint is not swapped
(skipped: footprint_locked), nor is one whose new footprint carries what
this tool cannot move or flip (skipped: footprint_unsupported); either
still takes the symbol's value, fields and nets. A new footprint carrying
what this tool cannot move is not added (skipped: footprint_unsupported).
Stale board footprints are reported, and removed only with delete_stale
(a locked one, in any spelling KiCad reads, never is, and neither is one
marked board only: KiCad's update keeps both). Zones are NOT refilled: run
fill_zones afterward. Net names arrive exactly as KiCad's F8 produces them
(local labels sheet-prefixed, e.g. "/SIG"); read them with list_pcb_nets.
A pad whose net did not change is left as it is, and one that gains a net
gets it where KiCad's writer puts it. A net that left the schematic goes to
no net with everything on it, written as the board's format writes no net,
unless a pad of a footprint that stays on the board is still on it (a stale
footprint that is kept: delete_stale off, or locked, or board only); such a
net keeps its row and everything on it. Segments, arcs and vias sent to no
net are counted in orphaned_tracks, zones in orphaned_zones, and copper
shapes are named in warnings. Nothing on a renamed net is moved to its new
name: it goes to no net with the rest, or stays on the old net while a kept
pad holds it.
What KiCad's own update copies from the symbol follows it here, with
two exceptions named below. The Value. Every other symbol field, as hidden
text on the fabrication layer of the footprint's side: Datasheet and
Description are updated where the library footprint put them, a new field
is added at the footprint's origin at the footprint's own angle (mirrored
on the back), and a field that left the symbol stays on the footprint
(KiCad keeps a footprint's library fields the same way, and text the
user may have placed is not an import's to remove). The symbol's
footprint filters, as KiCad's (property ki_fp_filters ...). The DNP and
"In BOM" boxes, set and cleared on the footprint's attributes; on a
KiCad 10 netlist "Exclude from position files" too, while on KiCad 9,
whose netlist has no such marker, that flag stays the board's own, as
the mounting type, board_only and the courtyard choice always do. The
sheet name and file, and the path that links the footprint to its
symbol. A symbol with "On board" unticked is never placed and is listed
in excluded_from_board; a footprint it left behind is reported stale like
any other. Not copied: the Component Class field, which KiCad assigns as
a component class rather than a field (dropped here), and KiCad 10's
variant overrides, which are not applied. Existing footprints whose
fields, filters, flags or sheet linkage moved are listed in
fields_updated; a second run that changes nothing writes nothing.
A footprint's library nickname is resolved the way KiCad resolves it:
the project's own fp-lib-table first (beside the .kicad_pro, or beside
the board or the schematic when none is named), then .pretty directories
beside the board and the schematic, then KICAD_FP_LIB, then the user's
global fp-lib-table together with the libraries the Plugin and Content
Manager installed, then KiCad's stock footprints. ${KIPRJMOD}, the
variables of Preferences > Configure Paths (kicad_common.json), the
${KICAD*_3RD_PARTY} and ${KICAD*_FOOTPRINT_DIR} families and the other
KiCad path variables expand as KiCad expands them: the environment
first, then the configured value, then KiCad's own default. A nickname
none of those know is reported in skipped as footprint_lib_not_found.
place_footprint resolves through the same code, so a hand-placed part
and an imported one resolve to the same file.
Requires kicad-cli. It no longer needs KiCad's pcbnew Python bindings.
Every byte this writes goes through the server's byte-preserving write, so
a board's format stamp does not move and the parts of it this tool did not
touch arrive unchanged.
Args:
schematic_path: Path to .kicad_sch file. Optional; omit to use the configured default.
pcb_path: Path to .kicad_pcb file (created if missing).
Optional; omit to use the configured default.
delete_stale: Remove unlocked board footprints absent from the schematic, except
those marked board only
project_path: Path to .kicad_pro for explicit root resolution (sub-sheets)
|
| set_trace_widthA | Change the width of existing traces matching the given filters.
At least one filter (net_name, layer, or bounding box) is required. Args:
width: New trace width in mm
net_name: Filter by net name
layer: Filter by layer name (e.g. "F.Cu", "B.Cu")
x_min: Left edge of bounding box filter (mm)
y_min: Top edge of bounding box filter (mm)
x_max: Right edge of bounding box filter (mm)
y_max: Bottom edge of bounding box filter (mm)
pcb_path: Path to .kicad_pcb file. Optional; omit to use the configured default.
|
| remove_tracesA | Remove trace segments matching the given filters. Does not remove vias.
At least one filter (net_name, layer, or bounding box) is required. Args:
net_name: Filter by net name
layer: Filter by layer name (e.g. "F.Cu", "B.Cu")
x_min: Left edge of bounding box filter (mm)
y_min: Top edge of bounding box filter (mm)
x_max: Right edge of bounding box filter (mm)
y_max: Bottom edge of bounding box filter (mm)
pcb_path: Path to .kicad_pcb file. Optional; omit to use the configured default.
|
| add_thermal_viasA | Add a grid of thermal vias under a footprint pad. Args:
reference: Footprint reference (e.g. "U1", "R1")
pad_number: Pad number to center vias on. If empty, auto-selects largest SMD pad.
rows: Number of rows in the via grid, at least 1. rows * cols is at most 256.
cols: Number of columns in the via grid, at least 1.
spacing: Spacing between vias in mm
via_size: Via annular ring diameter in mm
via_drill: Via drill diameter in mm
net_name: Net to assign to vias. If None, auto-detect from pad.
pcb_path: Path to .kicad_pcb file. Optional; omit to use the configured default.
|
| set_net_classA | Create or update a net class with design rules and assign nets. Edits the KiCad project file (.kicad_pro) alongside the board to
define the net class and assign nets. Does NOT require pcbnew.
Args:
name: Net class name (e.g. "Power", "HighSpeed")
nets: List of net names to assign to this class
track_width: Track width in mm (None = use default)
clearance: Clearance in mm (None = use default)
via_size: Via diameter in mm (None = use default)
via_drill: Via drill in mm (None = use default)
pcb_path: Path to .kicad_pcb file. Optional; omit to use the configured default.
|
| remove_dangling_tracksA | Detect and remove trace segments with unconnected endpoints. Iteratively removes dangling segments until no more are found.
A segment is considered dangling if either endpoint does not connect
to a pad, via, or another trace endpoint.
Args:
pcb_path: Path to .kicad_pcb file. Optional; omit to use the configured default.
|
| run_drcA | Run Design Rules Check (DRC) on a PCB. Returns structured report with violations.
Args:
pcb_path: Path to .kicad_pcb file. Optional; omit to use the configured default.
output_dir: Directory for report file (default: same as PCB).
Optional; omit to use the configured default.
|
| export_pcbA | Export PCB to PDF, SVG, or DXF format. Args:
format: Output format - "pdf", "svg", or "dxf"
pcb_path: Path to .kicad_pcb file. Optional; omit to use the configured default.
output_dir: Directory for output files. Optional; omit to use the configured default.
layers: Optional list of layer names to include (required for DXF)
output_units: DXF output units - "in" or "mm" (DXF only)
exclude_refdes: Exclude reference designators (DXF only)
exclude_value: Exclude component values (DXF only)
use_contours: Use board outline contours (DXF only)
include_border_title: Include border and title block (DXF only)
|
| export_gerbersA | Export Gerber files for manufacturing. When layers contains exactly one layer, exports a single Gerber file: path
names it, and size_bytes and layer are filled. Otherwise exports all layers
(or the specified subset) plus optional drill files, and path names the
output directory. files and count are filled either way.
Args:
pcb_path: Path to .kicad_pcb file. Optional; omit to use the configured default.
output_dir: Output directory for gerber files. Optional; omit to use the configured default.
include_drill: Also export drill files (default: True, ignored in single-layer mode)
layers: Optional list of layer names. Single layer = single file output.
|
| export_3dA | Export PCB 3D model or render 3D view to image. `render` fills width, height and side; the mesh formats leave them unset.
Args:
format: Output format - "step", "stl", "glb", or "render" (PNG image)
pcb_path: Path to .kicad_pcb file. Optional; omit to use the configured default.
output_dir: Output directory. Optional; omit to use the configured default.
width: Image width in pixels (render only)
height: Image height in pixels (render only)
side: View side: top, bottom, left, right, front, back (render only)
quality: Render quality: basic, high (render only)
|
| export_positionsA | Export component position file (pick and place) as CSV, in millimetres (mm). The columns are Ref, Val, Package, PosX, PosY, Rot and Side. PosX and PosY
are the footprint's position in millimetres, with the board's Y axis
negated; Rot is its angle in degrees; Side is top or bottom.
Args:
pcb_path: Path to .kicad_pcb file. Optional; omit to use the configured default.
output_dir: Output directory. Optional; omit to use the configured default.
|
| export_ipc2581A | Export PCB in IPC-2581 format for manufacturing data exchange. Args:
pcb_path: Path to .kicad_pcb file. Optional; omit to use the configured default.
output: Output file path. Optional; omit to write <board name>.xml to the
configured output directory, or beside the board when none is configured.
precision: Numeric precision (default: 3)
compress: Compress output file
version: IPC-2581 version (default: "C")
units: Output units - "mm" or "in"
|
| autoroute_pcbA | Autoroute PCB traces using the Freerouting autorouter. Exports the board to Specctra DSN format, runs Freerouting for automated
trace routing, and imports the results into a new PCB file. The original
board is never modified.
Requires KiCad's pcbnew Python bindings, whose major version has to match
the board's format era, and Java 25+ for the Freerouting build it
downloads. Unless FREEROUTING_JAR names a Freerouting jar, the first run
downloads Freerouting 2.5.0 (65 MB) from GitHub, checks its SHA-256 and
caches it.
Args:
pcb_path: Path to .kicad_pcb file. Optional; omit to use the configured default.
max_passes: Maximum autorouter optimization passes
num_threads: Thread count for routing. Defaults to 1 because
freerouting prints "Multi-threaded route optimization is broken
and it is known to generate clearance violations" on every run.
Raise it only if you are willing to DRC the result carefully.
timeout: Max seconds to wait for routing (default: 600)
output_dir: Directory for output files (default: same as PCB).
Optional; omit to use the configured default.
|
| get_footprint_boundsA | Get the board-coordinate bounding box of a placed footprint. Args:
reference: Footprint reference designator
pcb_path: Path to .kicad_pcb file. Optional; omit to use the configured default.
|
| validate_boardA | Validate all footprint placements against keep-out zones and board edge. Each footprint's origin is checked as check_placement checks it: keep-outs read
as KiCad reads them, footprint keep-outs in board coordinates and layer sets
such as *.Cu included, and a footprint never flagged by its own keep-outs, which
KiCad's DRC never tests it against (pcbnew/pcbexpr_functions.cpp:697 at 9.0.8).
Args:
pcb_path: Path to .kicad_pcb file. Optional; omit to use the configured default.
|
| list_lib_symbolsA | List all symbols in a .kicad_sym library file. Args:
symbol_lib_path: Path to .kicad_sym file. Optional; omit to use the configured default.
|
| get_symbol_infoA | Get detailed pin and property info for a symbol in a library. Args:
symbol_name: Symbol name (e.g. "LM7805")
symbol_lib_path: Path to .kicad_sym file. Optional; omit to use the configured default.
|
| add_symbolA | Add a new symbol definition to a .kicad_sym library. Creates a complete symbol with pins and body graphics. If the library
file does not exist it will be created.
Args:
name: Symbol name (e.g. "MP4572GQB-P", "TLV75733PDBVR")
pins: Pin definitions — list of dicts, each with keys:
number (str): pin number, e.g. "1"
name (str): pin name, e.g. "VIN" ("~" for unnamed)
type (str): electrical type — "input", "output", "bidirectional",
"passive", "power_in", "power_out", "tri_state",
"open_collector", "open_emitter", "unconnected", "free"
x (float): X position in mm (default 0)
y (float): Y position in mm (default 0)
rotation (float): angle 0/90/180/270 (default 0)
length (float): pin length in mm (default 2.54)
reference_prefix: Reference prefix e.g. "U", "R", "C" (default "U")
is_power: True for power symbols (default False)
pin_names_offset: Pin name label offset in mm (default 0.508)
in_bom: Include in BOM (default True)
on_board: Place on board (default True)
footprint: Default footprint e.g. "Package_SO:SOIC-8" (default "")
datasheet: Datasheet URL (default "~")
rectangles: Optional body rectangle(s) — list of dicts with keys:
x1, y1, x2, y2 (float): corner coordinates in mm
fill (str): "none", "background", or "outline" (default "background")
If omitted, a rectangle is auto-computed from pin positions.
symbol_lib_path: Path to .kicad_sym file. Optional; omit to use the configured default.
|
| export_symbol_svgA | Export symbol library to SVG images. Args:
symbol_lib_path: Path to .kicad_sym file. Optional; omit to use the configured default.
output_dir: Output directory. Optional; omit to use the configured default.
|
| upgrade_symbol_libA | Upgrade a symbol library to current KiCad format. KiCad performs the migration, as it should, but it performs it on a copy:
the result lands through the server's atomic write, so your library is
replaced whole or not at all and can never be left truncated. A backup is
still taken beside it at ``<name>.kicad_sym.bak``, and the result names it,
because that is the undo for an upgrade that SUCCEEDED and is not something
an atomic write can offer. There is exactly one, and every run overwrites it.
Args:
symbol_lib_path: Path to .kicad_sym file. Optional; omit to use the configured default.
|
| list_lib_footprintsA | List all footprints in a .pretty library directory. Args:
pretty_dir: Path to .pretty directory containing .kicad_mod files
|
| get_footprint_infoB | Get pad and outline details for a footprint .kicad_mod file. Args:
footprint_path: Path to .kicad_mod file. Optional; omit to use the configured default.
|
| export_footprint_svgB | Export footprint to SVG. Args:
footprint_path: Path to a .kicad_mod file, or a .pretty library directory.
Optional; omit to use the configured default.
output_dir: Output directory. Optional; omit to use the configured default.
|
| upgrade_footprint_libA | Upgrade a footprint library to current KiCad format. Rewrites every footprint in the library, so this takes the library
directory. kicad-cli has no per-footprint option here, and a single
.kicad_mod path is rejected. So is a library that is, or holds, a link or
anything other than plain files and folders, before anything is copied.
KiCad performs the migration, as it should, but it performs it on a copy and
each result lands through the server's atomic write, so no footprint file can
be left truncated. Only files whose content actually changed are written, so
an upgrade that touches three footprints leaves the rest of the library
alone. The whole library is still copied to ``<name>.pretty.bak`` first and
the result names it, because that is the undo for an upgrade that SUCCEEDED.
There is exactly one, and every run overwrites it.
Each file is atomic; the library as a whole is not a transaction. An upgrade
interrupted midway leaves some footprints migrated and some not, and no file
damaged. Version control is still the better answer for a library you care
about.
Args:
footprint_path: Path to a .pretty library directory.
Optional; omit to use the configured default.
|
| create_projectA | Create a KiCad 9 project (.kicad_pro + root .kicad_sch). No .kicad_prl is written, and an existing .kicad_sch or .kicad_prl of that name is left
as it is; the result says whether the root schematic was created or kept.
Args:
directory: Directory to create the project in (created if missing)
name: Project name (used for filenames)
|
| create_schematicB | Create a valid empty KiCad 9 schematic file. Args:
schematic_path: Path for the new .kicad_sch file.
Optional; omit to use the configured default.
|
| create_symbol_libraryA | Create a valid empty KiCad 9 symbol library. Args:
symbol_lib_path: Path for the new .kicad_sym file.
Optional; omit to use the configured default.
|
| create_sym_lib_tableA | Create a sym-lib-table file in the given directory. Each entry dict needs 'name' (the library nickname) and 'uri' (its path, usually
"${KIPRJMOD}/..."). Overwrites existing sym-lib-table if present. A backslash in a uri
is written as '/', as KiCad stores it.
The whole list is checked first. An entry that cannot be written as given refuses the
call, names the entry, and leaves any existing table as it was: an empty name; a name
holding a character below U+0020, a backslash or a colon (a library nickname cannot);
a name an earlier entry has; an empty uri; a double quote in a name or uri, or a line
end or NUL in a uri (KiCad 9 and KiCad 10 read these differently in a table).
Args:
directory: Directory to write sym-lib-table in
entries: List of dicts with 'name' and 'uri' keys
|
| add_hierarchical_sheetA | Add a hierarchical sheet to a parent schematic with matching labels in the child. Creates the sheet block in the parent, with its pins on the left edge, and the
corresponding hierarchical labels in the child schematic. The child schematic must
already exist (create it with create_schematic first).
Everything is checked before the first write, so a refusal changes neither file: a pin
direction that is not one of the five below, an empty pin name, a child that is no
schematic, and a child that is the parent or has the parent somewhere below it.
The sheet's page is the lowest number no sheet of the hierarchy uses. It is written at
the instance path of the parent (the sheet that holds the block), which is where KiCad
reads a sheet's page; give project_path when the parent is itself a sub-sheet, so that
path can be found. Symbols already in the child get an instance entry at the new
sheet's path.
Args:
parent_schematic_path: Path to parent .kicad_sch
sheet_name: Display name for the sheet
sheet_file: Path to child .kicad_sch (must exist)
pins: List of dicts with 'name' (str) and 'direction' (str) keys.
Direction: input, output, bidirectional, tri_state, passive.
x: X position of sheet block (default 25.4)
y: Y position of sheet block (default 25.4)
project_path: Path to .kicad_pro file (for sub-sheet instance tracking)
|
| remove_hierarchical_sheetA | Remove a hierarchical sheet block from a parent schematic. Identify the sheet by name, uuid, or both. If name matches multiple sheets,
returns an error with UUIDs for disambiguation.
Args:
parent_schematic_path: Path to parent .kicad_sch
name: Sheet name to match
uuid: Sheet UUID for unambiguous identification
delete_child_file: If True, delete the child .kicad_sch file
(unless still referenced by another sheet)
|
| modify_hierarchical_sheetA | Modify properties of an existing hierarchical sheet block. A new width or height keeps each pin on its edge and moves it with the edge, places the
name and file fields of an autoplaced sheet again, and moves a wire, bus end or
no-connect that sat on a moved pin with it, so the sheet stays connected. A size smaller
than the sheet's pins need is refused, naming the minimum, and a size equal to the
current one changes nothing.
Args:
sheet_uuid: UUID of the sheet to modify (from list_schematic_sheets)
schematic_path: Path to parent .kicad_sch. Optional; omit to use the configured default.
sheet_name: New display name (empty = keep)
file_name: New file path (empty = keep)
width: New width in mm (None = keep)
height: New height in mm (None = keep)
|
| add_sheet_pinA | Add a pin to an existing hierarchical sheet block. The pin goes on the chosen edge at the first slot, counting down from the sheet's top
edge in steps of 2.54 mm, that has no pin within 2.54 mm and lies inside the edge (this
layout is the tool's own, not KiCad's). When the edge has no such slot the call is
refused, writing nothing, and the message gives the height that takes one more pin
(set it with modify_hierarchical_sheet). A direction that is not one of the five below,
an empty name and a side other than left or right are refused too.
Args:
sheet_uuid: UUID of the sheet
pin_name: Pin name (should match a hierarchical label in the child schematic)
connection_type: input, output, bidirectional, tri_state, passive
schematic_path: Path to parent .kicad_sch. Optional; omit to use the configured default.
side: Which sheet edge to place pin on (left or right)
|
| remove_sheet_pinA | Remove a pin from a hierarchical sheet block. Args:
sheet_uuid: UUID of the sheet
pin_name: Name of the pin to remove
schematic_path: Path to parent .kicad_sch. Optional; omit to use the configured default.
|
| annotate_schematicA | Auto-assign reference designators to unannotated components. Finds components with '?' in their reference (e.g. R?, U?) and assigns
sequential numbers, respecting existing references in the schematic
and across the hierarchy when project_path is provided.
Args:
schematic_path: Path to .kicad_sch file. Optional; omit to use the configured default.
project_path: Path to .kicad_pro file (scans hierarchy for existing refs)
|
| validate_hierarchyA | Validate a hierarchical schematic for common issues. Checks every sheet below the root, however deep, each file once. A relative sheet file
name is found beside the file holding the sheet, as KiCad finds it; a sheet that contains
itself, which KiCad refuses, is skipped. Per sheet block: orphaned labels and pins,
direction mismatches, a missing file, a file that cannot be parsed ("unreadable_file",
whose "note" names the file; its checks are skipped, the rest still run). Per sheet
instance, so a reused sheet counts once per use: duplicate and unannotated reference
designators, each read from the entry KiCad reads at that instance, the root's
symbol_instances table on a root in KiCad 6's form, else the symbol's own (the units of
one multi-unit part share theirs); an instance with no entry reads the symbol's first
entry, else its Reference property. Past 4096 instances a "references_unchecked" note says
the rest went unchecked. Per file: the points where kicad-cli 9 drops part of a line that
KiCad's editor keeps.
Those are a junction strictly inside a wire or bus ("junction_inside_wire") and, in a file
kicad-cli 9 loads, a bus entry end strictly inside one ("bus_entry_inside_wire"); KiCad's
editor never saves either, and earlier versions of this package wrote both. kicad-cli 9
(ERC, netlist export, PCB update) cuts the line there: per line, "kept" is the stretch it
keeps and "dropped" the stretch it loses, cutting off whatever joins the line only along
that. "editor" says what KiCad 9's editor makes of it: it splits the line, keeping a
junction where three or more directions meet ("keeps_junction"), deleting it elsewhere
("deletes_junction"), and at a bus entry end placing none ("splits_wire"). A file stamped
past KiCad 9's format gets neither reading. The readings follow KiCad's source; whether
kicad-cli 9 loads the sheet at all is not checked. To fix one, make the call in its
"repair" as given: add_junctions at the point, which splits the line, or remove_junction.
Such an issue carries a "note" in place of a repair in two cases only: its sheet is one the
connectivity model refuses (a symbol or pin at an angle KiCad cannot load; no reading
either), or it is a bus entry end where KiCad allows no junction.
Per file too: the no-connect flags ("no_connect_off_pin") and wire ends
("wire_end_off_pin") at the point releases 0.5.8 to 0.20.1 gave a pin of a symbol at
rotation 90 or 270 with a mirror. They mirrored before rotating, so that point is the
pin's end reflected through the symbol's origin, and 0.20.1's no_connect_pin,
wire_pins_to_net and connect_pins wrote there (measured). Only a point where KiCad draws
no pin is checked. Each issue names the symbol ("reference"), the "pin", the point ("x",
"y") and where KiCad draws the pin ("pin_x", "pin_y"), and a wire end its "wire". Where
the old transform put several pins at the point, the issue lists them under "pins" in
place of those four, with a note and no repair, since which pin the flag or wire was
written for is not known. A flag is not reported where a sheet pin or a hierarchical label
is too; a wire end is not where an end of another item but a bus's lies on it, a flag and
the Net-(<ref>-<pin>) label connect_pins wrote there apart; neither is where any reader
may join it to a pin KiCad draws for the point already. A flag carries a note: no tool
removes one by its position, so delete it in KiCad's editor, then no_connect_pin flags the
pin. A wire end's "repair" is wire_pins_to_net with the one local label name on its net
that the tool accepts, planned first; else a note, with the plan's refusal or, where the
net has no single such name, the pin the wire reaches. Nothing is written.
Args:
schematic_path: Path to root .kicad_sch file. Optional; omit to use the configured default.
|
| is_root_schematicA | Check if a schematic is the root or a sub-sheet. A sheet is found in its project wherever its file sits below the project's
folder. A file that no sheet of its project uses is a root. For a sub-sheet,
root_path is the top-level sheet of its project that holds it.
Args:
schematic_path: Path to .kicad_sch file. Optional; omit to use the configured default.
|
| list_hierarchyA | List the full sheet hierarchy starting from a root schematic. Args:
schematic_path: Path to root .kicad_sch file. Optional; omit to use the configured default.
|
| get_sheet_infoA | Get detailed info about a hierarchical sheet including pin/label matching. Args:
sheet_uuid: UUID of the sheet
schematic_path: Path to parent .kicad_sch. Optional; omit to use the configured default.
|
| trace_hierarchical_netA | Trace a net across the hierarchy, following hierarchical pins and labels. Args:
net_name: Net/label name to trace
schematic_path: Path to root .kicad_sch file. Optional; omit to use the configured default.
|
| list_cross_sheet_netsA | List all nets that cross sheet boundaries (hierarchical pins and global labels). Args:
schematic_path: Path to root .kicad_sch file. Optional; omit to use the configured default.
|
| get_symbol_instancesA | List all symbol instances from a root schematic's symbolInstances table. Args:
schematic_path: Path to root .kicad_sch file. Optional; omit to use the configured default.
|
| move_hierarchical_sheetA | Move a hierarchical sheet block to a new position, including all pins. Args:
sheet_uuid: UUID of the sheet to move
new_x: New X position in mm
new_y: New Y position in mm
schematic_path: Path to parent .kicad_sch. Optional; omit to use the configured default.
|
| reorder_sheet_pagesA | Put hierarchical sheets in the page order given: sheets listed come first, in that order,
then the others in the order they have now. KiCad orders sheets by their page numbers, not by where their blocks sit in the file, so
this rewrites the page numbers and leaves the blocks where they are. Call it on the root
schematic: a sheet's page is stored at its parent's path, and a sub-sheet's blocks are
refused. The numbers already in use are given back in the new order, so custom labels
such as "Intro" stay; when they repeat, or a deeper sheet uses one, the sheets are numbered
from the lowest positive whole number no other sheet holds. A sheet whose instance entry
was written at its own path, as earlier versions of the tools did, has it moved to the path
KiCad reads. A root older than format 20221110, which keeps every page in its own
sheet_instances table, is refused.
Args:
page_order: List of sheet UUIDs in desired order
schematic_path: Path to root .kicad_sch file. Optional; omit to use the configured default.
|
| duplicate_sheetA | Duplicate a hierarchical sheet, copying the child file with new UUIDs. The new block is a copy of the source block, moved to its right, with its fields placed
again when the source's were autoplaced, and its page the lowest number no sheet uses,
stored at the parent's path where KiCad reads it. The copied file's symbols get references
of their own, so the two sheets are two sets of parts: each prefix takes its first free
number across the hierarchy, in the order of the symbols' x then y position, and the
units of one part keep one reference. A reference with no number stays as it is.
A source file that holds sheets of its own is refused, with nothing written, because its
sub-sheets would need new instance paths in other files. Give project_path when the
parent is itself a sub-sheet, so its place in the hierarchy can be found.
Args:
sheet_uuid: UUID of the sheet to duplicate
new_sheet_name: Display name for the new sheet
schematic_path: Path to parent .kicad_sch. Optional; omit to use the configured default.
project_path: Path to .kicad_pro (for hierarchy metadata)
new_file_name: Name for the copied file (auto-generated if empty)
|
| flatten_hierarchyA | Flatten a hierarchical schematic into a single sheet whose netlist is the hierarchy's. The flat file is the root schematic with each sub-sheet's content copied below it, one
cell per use of a sheet file (a file used twice is copied twice). Each part keeps the
reference and unit KiCad reads for it at its sheet's path. A sheet pin becomes a
local label at its place when its sheet has a hierarchical label of its name, and nothing
otherwise. A local or hierarchical label of a sub-sheet becomes a local label named after
the sheet's path, so nets keep their joins and no others; net names change to those
labels. A label whose own sheet has a global label, a power symbol or a hidden power input
pin of its text keeps that text, so it keeps joining it. Text variables that name the
sheet are not rewritten.
The tool refuses, writing nothing, where the flat file could not keep the netlist: a
sheet pin or sub-sheet label that may be a bus, a file older than format 20221002, a
local power symbol, a bus_alias in a sub-sheet, a root label named like a global net
that only another sheet has, a library symbol whose pins differ between two files, a
sheet marked DNP, out of the BOM, off the board or out of simulation,
two sheets of one name, more than 4096 sheet instances, or a sheet file that cannot be
read. A sheet file that is missing is flattened as an empty sheet, as KiCad loads it.
Creates a new file and does not modify the hierarchy.
Args:
schematic_path: Path to root .kicad_sch file. Optional; omit to use the configured default.
output_path: Path for flattened output (defaults to *_flat.kicad_sch)
|
| export_hierarchical_netlistA | Export a netlist from the root schematic, including hierarchy info. Runs kicad-cli to generate a netlist and returns parsed component/net data
with sheet path information for each component.
Args:
schematic_path: Path to root .kicad_sch file. Optional; omit to use the configured default.
output_dir: Directory for netlist output (defaults to schematic directory).
Optional; omit to use the configured default.
|
| run_jobsetA | Run a KiCad jobset file: every output it defines. The jobset runs against the one .kicad_pro in its own folder, and a relative
output folder in it is relative to that folder. kicad-cli is given a copy of
the jobset, never the file, because it rewrites or deletes a jobset it cannot
parse. It is an error when nothing ran or a job failed, and the error carries
the counts kicad-cli reported.
Args:
jobset_path: Path to .kicad_jobset file
|
| get_versionA | Get KiCad version information including build details and library versions. |
