CLI reference¶
Every command and option of pcbkit, in the order you use them. The sections below are
generated from the command line itself when the site is built, so they say what the
installed version does.
Every command takes -h or --help, and pcbkit --version prints the version.
Run the commands from inside a board project: a folder that holds a pcbkit.toml, or
any folder below one. The ones that need KiCad's pcbnew module (build, route,
promote, finalize, check, mutants and compare) run from the project's own
.venv/bin/pcbkit, which pcbkit setup makes; the others run from any pcbkit,
including one started with uvx. Concepts explains why.
A command that cannot do its job prints what is wrong and what to do about it, and
exits 1. Three commands use other codes where they have more to say: check exits with
pytest's code (0 all passed, 1 a check failed, 5 nothing matched), mutants exits 2
when its control run does not pass, and compare exits 2 when a file is not a board.
pcbkit new¶
Create a board project called NAME from a template.
Copies the template into a new folder NAME (it may be a path; the folder must not
exist, or must be empty) and names the board after it: my-board becomes the file
stem my_board, the title My Board and the fab files My_Board_revA. The template is
the blinky example: a power connector, a resistor and an LED on a 30 x 20 mm
two-layer board, with its checks and a route that passed DRC, so it builds as it is.
Also written: the project's pyproject.toml, which depends on pcbkit and pytest, and
a README.md with the commands. Then cd into the folder and run pcbkit setup.
The project installs pcbkit from its git repository. To install it from your own copy instead, give the folder you cloned it into with --pcbkit-source (or set PCBKIT_SOURCE): the project's pyproject.toml then names it as an editable path source.
Usage:
Options:
--from TEXT The example board to start from. [default: blinky]
--pcbkit-source PATH A pcbkit checkout for the project to install pcbkit
from, instead of its git repository (default: the git
repository). Also read from PCBKIT_SOURCE.
--help Show this message and exit.
pcbkit doctor¶
Check this machine has everything pcbkit needs.
Looks for KiCad, Java, Freerouting and the other tools. Prints one line per item: OK or MISSING, the version and path found, and a fix for anything that is missing. Exits 1 if a required item is missing. ngspice and pcbnew in this Python are optional.
Usage:
Options:
pcbkit setup¶
Set up the project .venv and fetch Freerouting.
Run it in a board project (a folder with a pcbkit.toml and a pyproject.toml): once
after pcbkit new, and again whenever the dependencies change. It builds .venv on
KiCad's own Python, so that pcbnew imports in it (uv venv --system-site-packages),
installs the project's dependencies into it (uv sync) and checks that
import pcbnew works there. A .venv that already does is kept. It then makes sure
the Freerouting 1.9.0 jar is there: it uses one it finds (FREEROUTING_JAR,
~/.local/share/pcbkit or ~/.local/share/freerouting), and otherwise downloads it
from Freerouting's GitHub release into ~/.local/share/pcbkit. Last it prints the
commands to run next, from .venv/bin.
Needs uv and KiCad 10; a failure says what is wrong and how to fix it, and
pcbkit doctor shows what is missing on the machine. It does not need pcbnew in
the Python that runs it, so it works from uvx or any environment with pcbkit.
Usage:
Options:
pcbkit sch¶
Generate the schematic, run ERC and export the netlist.
Builds the project's own symbol and footprint libraries, draws the schematic from design.py, checks it with KiCad's ERC and exports the netlist, all into kicad/. Needs kicad-cli but not pcbnew. Exits 1 if ERC reports errors; warnings are listed and do not fail it.
Usage:
Options:
pcbkit build¶
Generate the schematic and netlist, then place the board.
Runs pcbkit sch, then builds kicad/<stem>.kicad_pcb: each footprint of the
netlist at its position in layout.py, the outline, the mounting holes and the
stackup. A part with no position is parked below the board and listed. ERC
findings are listed too: the board is placed anyway, and the exit code is 1 if ERC
reported errors. Needs pcbnew.
Usage:
Options:
pcbkit route¶
Pre-route, run Freerouting, fill zones and run DRC.
Starts from the placed board that pcbkit build wrote. Runs the project's
routing.py hooks, then Freerouting, and after each run fills the pours and runs DRC:
it stops at the first try with no copper problem, and otherwise gives up after
--tries tries and leaves the best board. Then it adds the silkscreen and shows the
DRC with schematic parity. A Freerouting run that never starts routing is killed
after [route] stall_timeout_s; with --eco that falls back to routing the whole
board. Exits 1 if no try was clean.
Usage:
Options:
--eco PATH Keep the route in this golden-style folder and only route what
changed.
--tries N Freerouting runs to try before giving up (default: [route]
tries). [x>=1]
--passes N Freerouting passes per run (default: [route]
freerouting_passes). [x>=1]
--help Show this message and exit.
pcbkit promote¶
Save the routed board as the golden route.
Copies the route that pcbkit route made (prerouted.kicad_pcb, the session file
and the DSN) into golden/, which pcbkit finalize rebuilds from. It first runs DRC
with schematic parity on the finished board and refuses to promote one that has
any violation, unconnected pad or footprint error.
Usage:
Options:
pcbkit finalize¶
Rebuild from the golden route, run DRC and export the fab files.
Copies golden/ into kicad/, imports the route, fills the pours, adds the silkscreen, runs DRC with schematic parity and exports the fab files and documents into out/. If DRC is not clean it stops before the export and exits 1.
Usage:
Options:
pcbkit check¶
Run the design checks against the board.
Runs the built-in checks of the groups listed in [checks] groups, then the project's own checks/ folder, with pytest. Writes out/checks/results.json and exits 1 if any check fails. Needs pcbnew.
Usage:
Options:
-k EXPR Only run the checks that match this pytest -k expression.
--help Show this message and exit.
pcbkit mutants¶
Plant known mistakes and confirm the checks catch every one.
Reads MUTANTS from the project's mutants.py. Each is planted in design.py in a scratch copy of the project and the checks it names must then fail; a control run on an unedited copy must pass first. Exits 1 if a mistake is missed, 2 if the control fails. Needs pcbnew.
Usage:
Options:
pcbkit report¶
Write the validation report from the last check run.
Turns out/checks/results.json (left by pcbkit check) into
out/checks/VALIDATION.md: the counts, then every check with its result and the
numbers it recorded. A run that -k cut short is marked as partial. Exits 1 if the
last run had a failed check or an error, or ran no checks. Runs anywhere: it only
reads the results file.
Usage:
Options:
pcbkit quote¶
Print every number the PCBWay quote form asks for.
Reads the files pcbkit finalize exported (out/fab, else fab): the Gerber zip for
the board (layers, size, thickness, copper, finish, smallest track, space and hole)
and the BOM for the assembly (unique parts, SMD placements, BGA/QFP/QFN parts,
through-hole parts and their designators). With --assembled the assembly numbers
are printed too; --self-solder-tht leaves the through-hole parts out of them. With
--notes the order notes must fit the form's 600 characters, or the command fails
and says by how many it is over.
Usage:
Options:
--assembled N Number of boards to have assembled. [x>=1]
--fab-qty N Number of bare boards to have made. [x>=1]
--self-solder-tht Leave the through-hole parts to solder yourself.
--notes FILE A text file of order notes; the form allows 600
characters.
--help Show this message and exit.
pcbkit compare¶
Compare the copper of two boards; exit 1 if they differ.
Compares the number and length of tracks, the number of vias, each zone's filled area, and the copper itself on F.Cu and B.Cu: what exists on one board only, judged piece by piece. Exits 0 when the boards match, 1 when they differ and 2 when a file cannot be read as a board.
Usage:
Options:
--json Print the report as JSON.
--piece-tol MM2 Copper on one board only is a difference when a piece is
larger than this. [default: 0.01; x>=0]
--fill-tol MM2 A zone's fill is a difference when it moved by this much or
more. [default: 0.5; x>=0]
--top N Pieces to list for each layer and board in the text report.
[default: 8; x>=0]
--help Show this message and exit.
pcbkit shots¶
Export crops and renders of named board regions for review.
Saves each region as an SVG and a PNG, and three 3D renders. The regions are the whole board, top and bottom, and the ones the project names in SHOTS in layout.py. Needs rsvg-convert for the PNGs.
Usage:
Options:
--out DIR Folder for the shots (default: out/shots in the project).
--pcb FILE Board to shoot (default: the project's
`kicad/<stem>.kicad_pcb`).
--region NAME Only this region; repeat the option for more (default: every
region).
--no-render Skip the 3D renders, which take the longest.
--help Show this message and exit.