Command line
The soldermask command builds a board from a sentence or a design file. Its subcommands manage projects, run the app, set up the machine and serve the pipeline to other models.
Install
| From | Command |
|---|---|
| GitHub | uv tool install "git+https://github.com/ashwinsk01/soldermask.git@integration" |
| A checkout | pip install -e . |
The repository is private while soldermask is in alpha, so installing from
GitHub needs access (request access).
The integration branch is the one this manual describes.
Run soldermask setup next. python -m soldermask is the same command.
Commands
| Command | Does |
|---|---|
soldermask "<prompt>" | Build a board from a sentence (below) |
soldermask --design FILE | Build a board from a design file, with no model |
soldermask setup | Fetch what the install cannot carry, and name what is missing |
soldermask projects | List, show, fork and revert saved boards, and judge them again |
soldermask serve | Run the app |
soldermask mcp | Serve the pipeline as MCP tools, for another model to drive |
soldermask parts | Show a part's datasheet record, or read its datasheet (below) |
soldermask learn | The routability corpus and model |
soldermask docs | Build this manual, so the app can serve it at /docs |
soldermask version | Print the version |
soldermask release | Add a changelog note, or cut a release |
soldermask banner | Print the brand mark |
Every subcommand except version and banner takes --help.
Common tasks
-
Build a board from a sentence:
soldermask "a 5V to 3.3V regulator breakout with a power LED" -
Build from a design file you wrote, with no model call:
soldermask --design my_design.json --out build/ -
Save the build as a version of a project:
soldermask "a 5V to 3.3V regulator breakout" --project LDO -
Edit a saved board. The prompt becomes an edit of the current version:
soldermask "add a reverse-polarity diode on the input" --from LDO --project LDO -
Try a different placement of the same design:
soldermask --design my_design.json --seed 4
Build a board
soldermask "<prompt>" [options]
soldermask --design design.json [options]Input and output
| Flag | Default | Does |
|---|---|---|
prompt | What board to build, in words | |
--design PATH | Load a design JSON and skip the model | |
--out DIR | build | Where the fab files, KiCad files and pictures go |
--project NAME | Also save the build as a new version of this project. A missing project is created. | |
--from NAME | Start from this project's current version. The prompt becomes an edit. | |
--qty N | 1, 10, 25, 100 | A quantity to price and stock-check. Repeat it for several. |
--version, -V | Print the version and exit |
How much to run
| Flag | Does |
|---|---|
--place-only (--no-route) | Stop after placing. Nothing is routed. |
--route-only | Route the --from version's placement again. Needs --from and takes no prompt. |
--sim-only | Resolve and simulate only. Writes sim.json to --out and saves no version. |
--no-sim | Skip the ngspice simulation. The board says it was not simulated. |
--no-render | Skip the KiCad raytrace and GLB. The DRC still runs. |
How the board is built. Each of these is written into the design's
constraints, as rules.* or board.layers. The version records it and a rebuild keeps it.
| Flag | Default | Does |
|---|---|---|
--seed N | the project's rules.seed, else 1 | The anneal seed. The same design, pins and seed give the same placement. |
--router NAME | lightcycle | Which router lays the copper first (see the table below) |
--no-pour | Route ground as tracks instead of pouring it | |
--no-precedent | Place from scratch, even when the corpus holds a board like this one. Precedents are still listed. | |
--no-mark | Leave the maker's mark off the silkscreen, the Gerbers and the KiCad file | |
--layers 2|4 | the design's own, else 2 | Copper layers. Four is signal, ground plane, signal, signal. SOLDERMASK_PLANES=gnd+power makes the third a power plane. Saved as board.layers, and --layers 2 clears a four. See Four layers. |
--router | Router | Track / clearance |
|---|---|---|
lightcycle | Lightcycle, this tree's own router (the default) | 0.127 / 0.127 mm |
krt | The A* router | 0.127 / 0.127 mm |
If the router named is not installed, the other one routes the board and the gaps say so. See Routers.
The model
| Flag | Default | Does |
|---|---|---|
--backend NAME | claude-code, or SOLDERMASK_BACKEND | Which model designs the board: claude-code, gemini, claude or groq |
--model ID | the backend's own | Use another model id |
--effort LEVEL | high | Reasoning effort, for claude-code, claude and groq |
--repair N | 0 | Feed the pipeline's findings back to the model and revise, up to N times |
--wire | A second model turn that wires each part by the pin names it really has. Writes wire.json to --out. |
What it prints
A build prints in two phases.
- While it runs. For a prompt, the
designline lists each search, pin read and check the designer makes. Thenbuildprints each stage as it starts. - When it returns. One section a stage, from
partstosaved, summarised from the finished build.
Then come three sections:
- board: a picture of the board, seen from the front.
- VERDICT: whether this is a working board.
- what this board does NOT guarantee: the gaps, printed last so they stay on screen.
| Verdict | Means |
|---|---|
| passes | Every part resolved. Every net and connection the design asked for is on the board. There are no ERC errors, the design check's included. The board routed, KiCad's DRC found no copper error, and no track runs 100 °C over the room at its net's current. |
| NOT JUDGED | Nothing that ran failed, but a check the verdict needs did not run. The lines under it say which. |
| DID NOT PASS | A check failed. The lines under it say which. |
The verdict is repair.passes(), the same rule the evaluator scores with. It
does not stop the build, and it does not change the gaps list. See
Copper too narrow for its current
for the heat rule.
The picture prints only when colour is on. Ghostty, Kitty, WezTerm, Konsole
and iTerm2 show it as an inline image. Other terminals, and tmux, get braille.
Braille shows the outline, pads and copper but not fine pitch. Into a pipe,
there is no picture unless FORCE_COLOR is set.
| Exit status | Means |
|---|---|
0 | Built, with no ERC errors and a KiCad file that passed its check |
1 | ERC errors, a KiCad file that failed its check, or a build that could not start (for example, no such project) |
2 | The model's credentials are missing |
A failed verdict does not change the exit status.
What it writes
File in --out | What it is |
|---|---|
design.json | The design that was built |
| Gerbers, drill, BOM, CPL | The fab package |
<board>.dsn | The placed board as a Specctra design, which other routers read |
board.svg | A drawing of the board |
inventory.json | Stock and prices at each quantity |
routing.json | What the router did: the placements it tried, the one kept, the nets left short and the pour |
<board>.kicad_pcb, <board>.kicad_pro | The KiCad board, and its project with the rule it was routed at |
models/*.step | The 3D models KiCad renders with. A --project build writes models/*.wrl instead. |
meshes.json | The vendor 3D meshes the viewer draws |
<board>.kicad_sch | The schematic |
sim.json | The simulation, when the circuit was simulated |
<board>-3d.png, <board>.glb | KiCad's raytrace and 3D model, unless --no-render |
inspector.html | A standalone viewer with the 3D models inside it |
wire.json | What the wiring turn changed, with --wire |
repair.json | The repair rounds, with --repair |
With KiCad installed, the schematic line says whether KiCad's netlist of the
sheet matches the design, and what KiCad's ERC found.
One stage at a time
The switches above all run the same build, workspace.realise(). Used
together, they run one stage on its own:
soldermask --design d.json --place-only # resolve, simulate, place; no copper
soldermask --from ldo --route-only --project ldo # ldo's current placement, routed again
soldermask --from ldo --sim-only --out sim # ldo's netlist simulated, nothing else
soldermask --design d.json --seed 4 # a different placement of the same designUse --route-only after changing something the router reads, such as a
hand-drawn track, a track floor, a part sent to the back, or the pour. The
parts stay where they are. --seed has no effect on it. Lightcycle stops on a
fixed amount of work, so an unchanged version comes back with the same copper.
A route stopped by Lightcycle's 300 s backstop or 600 s wall can differ, and the
board says it was stopped.
The app has the same three on its Chain tab: Simulate, Place again and Route again.
Set up the machine
soldermask setup [--check] [--astar] [--parts]| Flag | Does |
|---|---|
| (none) | Report what is installed. Install Lightcycle and fetch the KiCad symbol library if they are missing. |
--check | Report only, and fetch or build nothing |
--astar | Also clone and build the A* router at its pinned commit. Needs git and cargo, and takes minutes. |
--parts | Also take the whole JLCPCB catalogue, so parts resolve offline (below) |
Each line of the report is one thing the build uses:
| Line | Checks |
|---|---|
home, cache | Where data and the cache live |
kicad | kicad-cli, for the DRC, renders and the Gerber cross-check |
router | Lightcycle, the default router |
symbols | The KiCad symbol library |
astar | The A* router |
ngspice | The simulator |
mould, anneal | The compiled core. Without it the results are the same and slower. |
poppler | pdftotext, which reads datasheets. Without it, sheets are fetched and never read. |
jlcapi | Whether JLCPCB API credentials are set, and whether the app is granted the Parts API |
parts | Where parts will come from |
The exit status is 1 while kicad-cli is missing, while neither router is
installed, or when a fetch or a build fails.
The router. Lightcycle comes as a wheel from the private repository
soldermask-org/lightcycle, at the version this soldermask pins. setup
downloads the wheel for your machine with your gh login, or with a token in
GH_TOKEN or GITHUB_TOKEN. Wheels exist for macOS and for Linux on x86-64
and ARM.
No wheel for your machine
Where no wheel fits or none can be downloaded, setup builds Lightcycle
from the repository with cargo. Without cargo, the router line says
to sign in with gh auth login or to install Rust from
rustup.rs.
The symbol library. setup fetches the archived KiCad symbol library
(about 3 MB) and indexes it. Without it, each pin is resolved from the vendor's
symbol alone. A board still builds, but it can pass or fail differently.
The parts line. A catalogue written from JLCPCB's API is always used. The
jlcparts mirror is used only when its build is whole. A mirror naming under
half of a whole build's 582,650 components is refused, because part of a
catalogue cannot say a part is missing. Lookups then go to jlcsearch, and the
line says so.
The parts catalogue
soldermask setup --partsThis takes the whole catalogue, so a build searches for parts without the network. A part's footprint, symbol, 3D model and datasheet are still fetched the first time a build uses it. Where the catalogue comes from:
| Source | When | What it takes |
|---|---|---|
| JLCPCB's own API | JLCPCB_APP_ID, JLCPCB_ACCESSKEY and JLCPCB_SECRETKEY are set, and the app is granted the Parts API | The listing (about 7.25 million records, just under an hour), then a detail record for every code in stock (about 15 minutes) |
| The jlcparts mirror | Otherwise | The mirror's files |
Both phases resume where they stopped. The catalogue is written under
.cache/jlcparts/. From the API, the parametric index is rebuilt over it too.
A mirror catalogue keeps the index it had, and setup says when that index is
stale and not used.
setup --check says which source the catalogue came from, and when. It also
says whether the app is granted the API, and which record fields this tree
does not read.
Projects
soldermask projects [list|show|fork|revert|rejudge] [NAME] [TARGET] [--dry-run]| Command | Does |
|---|---|
projects list | Every project with its versions, parts, ERC errors, cost and summary. The default. |
projects show NAME | The version table, with the current version starred |
projects fork NAME NEW | Copy a project under a new name |
projects revert NAME vNNN | Make an older version current again. History is never rewritten. |
projects rejudge [NAME] | Run KiCad's DRC again over every stored version, and rewrite the verdict where the answer changed |
Names match by slug or display name.
rejudge is for after a fix to the judge, because a verdict is written
once, at build time. It prints one line per version and needs kicad-cli.
- Only the verdict, a
rejudgedrecord and a note are rewritten. - The first
board.jsonis kept beside it asboard.json.before-rejudge, and never overwritten. - A version built before verdicts existed stays unjudged. Its line says what the DRC finds today.
--dry-runprints the lines and writes nothing.
Serve
soldermask serve [--port 8443] [--host 0.0.0.0] [--http]
[--token X | --no-auth] [--proxy] [--workers 2] [--log-file PATH] [--debug]| Flag | Default | Does |
|---|---|---|
--port, --host | 0.0.0.0:8443 | The address to bind |
--http | Serve plain HTTP. Pages load, but the phone's tilt control needs a secure origin and will not work. | |
--token X | generated once, kept in the cache directory | The access token other devices must present |
--no-auth | No token. Anyone on the network can use the app. | |
--proxy | Behind a reverse proxy: trust X-Forwarded-*, and require the token from every client, including loopback | |
--workers N | 2 | How many builds may run at once. Each one runs a router. |
--log-file PATH | stderr | Append logs to this file |
--debug | Verbose logging |
python serve.py runs the same command. See
Running in production.
MCP server
| Command | Does |
|---|---|
soldermask mcp | Serve the pipeline as tools on stdin and stdout |
soldermask mcp --tools | Print the tool list as JSON and stop |
soldermask mcp --model-calls | Let resolving a part ask this tree's own models. Off by default, so the client is the only model in a run. |
soldermask mcp --http | The same server over HTTP with bearer keys. Flags: --host, --port 8787, --keys FILE, --projects DIR, --builds N, --origin URL. |
soldermask mcp keys add NAME | Issue a key. It prints once; the keys file keeps only its digest. |
soldermask mcp keys list | Every key's name, directory and dates, never the key |
soldermask mcp keys revoke NAME | The key stops working on the next request |
Register the stdio server with claude mcp add soldermask -- soldermask mcp,
or put the same command in any client's mcpServers block. Register the HTTP
server with:
claude mcp add --transport http soldermask https://HOST/mcp --header "Authorization: Bearer sm_..."See MCP server.
Parts
A part's datasheet record holds what the design check applies to it: the external parts its chip requires and its voltage limits.
| Command | Does |
|---|---|
soldermask parts show C50506 | Print the part's record from the disk. Exits 1 if it has none. |
soldermask parts read C50506 | Print the record, reading the sheet first if there is none |
soldermask parts read C50506 --force | Read the sheet again, though a record is on file |
--json | Print the result as JSON instead of lines |
parts read calls two Azure models only with SOLDERMASK_DATASHEET_READER=azure
set, and a third with SOLDERMASK_READER_DRAW on. Otherwise it reads nothing and exits 1. A read takes one to two minutes and
stops at SOLDERMASK_READER_MAX_USD. The output is the same as the MCP tool's. See
Reading a datasheet.
The routability corpus and model
| Command | Does | Main flags |
|---|---|---|
learn status | Routes on disk, from how many boards, how many routed clean, and the shipped model | |
learn generate | Place and route boards into the corpus until the time is up | See below |
learn train | Fit the models, judge them, and ship the best | --epochs 60, --keep rudy|linear|cnn, --out PATH, --recipe lean|full, --seeds N, --router LABEL |
learn report | The shipped model's provenance and held-out scores | |
learn crossval | Hold out every family once | --folds 4, --epochs 60, --seed 0, --out |
learn ablate | Train the network with one input taken away at a time | --only, --seeds, --epochs 60, --out |
learn relabel | Route again every example the router never counted | --rules, --edge, --hours 2, --workers |
learn backfill | Route again every example with no record of where its copper went | --hours 2, --workers |
learn redraw | Draw every example's maps again from its stored placement. No route runs. |
train, relabel and redraw rewrite the shipped model or the corpus.
generatelabels with the A* router underkicad-cliby default (--router astar), into.cache/corpus-astar.--router freeroutingneeds Java and the freerouting jar, and only reproduces the older labels.trainneeds torch (pip install -e ".[learn]"). Without it, only the two logistic baselines are fitted.train --router LABELfits only on the examples one router labelled, such asfreerouting-2.4.1.SOLDERMASK_CORPUSkeeps the corpus somewhere other than.cache/corpus.SOLDERMASK_ROUTABILITYpoints the app at another model file.
learn generate
| Flag | Default | Does |
|---|---|---|
--hours H | 1 | How long to run |
--workers N | 4 | Boards routed at once |
--seed N | 0 | The run's seed |
--per-board N | 40 | Placements tried of each board on disk |
--synthetic N | 400 | Boards drawn from the catalogue |
--synthetic-variants N | 3 | Further anneals of each synthetic board, from other seeds |
--kinds LIST | every kind | Comma-separated transform kinds to draw, such as anneal |
--router astar|freerouting | astar | Which router labels the examples |
--boards DIR | every DSN in the repository | Only the DSNs under this directory |
--max-boards N | A fixed sample of this many boards, so a budget routes fewer boards several ways | |
--max-parts N | Only boards with at most this many parts |
See Routability.
Evaluation and by-hand repair
python -m soldermask.evaluate [options]
python -m soldermask.repair --design PATH --out DIR [options]evaluate flag | Default | Does |
|---|---|---|
--backends | gemini,claude | The models to run |
--n N | every prompt | How many prompts to run |
--out DIR | eval | Where results go |
--repair N | 0 | Revise up to N times. 0 is a single shot, the control. |
--designs DIR | Replay saved designs instead of calling the model. With --repair 0, the run is deterministic. | |
--no-route | Skip the router. Faster, but pass@1 then ignores routing. | |
--wire | Add the wiring turn | |
--tier ABCD | Run only these difficulty tiers | |
--rescore DIR… | Score a stored run again under today's pass rule. Builds nothing. |
repair flag | Does |
|---|---|
--design PATH | The design to measure |
--out DIR | Where the rounds accumulate |
--prompt TEXT | What the board was asked for |
--route | Also place and route, so the full pass rule applies |
--reset | Start the log again |
See Repair loop and evaluation.
Version and releases
| Command | Does |
|---|---|
soldermask version [--json] | Print the version and the project format |
soldermask release note "TEXT" [--kind KIND] | Add a line under Unreleased. Kinds: Added, Changed (default), Fixed, Removed, Security, Deprecated. |
soldermask release show | What is waiting under Unreleased |
soldermask release bump major|minor|patch | Cut a release: bump the version, roll the changelog, commit and tag. Flags: --no-git, --allow-empty, --dry-run. |
Docs
| Command | Does |
|---|---|
soldermask docs | Build docs/ into site/, which the app serves at /docs |
soldermask docs serve | Run MkDocs' live-reload server, for editing |
Both need a checkout, because an install does not carry docs/.
Environment variables
The ones the command line reads most. Configuration lists them all.
| Variable | Does |
|---|---|
NO_COLOR | Turn colour off |
FORCE_COLOR | Turn colour on, even into a pipe |
COLORTERM | truecolor or 24bit gives the 24-bit orange; otherwise the nearest of 256 colours |
SOLDERMASK_BACKEND | The default model backend |
SOLDERMASK_ROUTER | The router for a design that names none: lightcycle (the default) or krt |
SOLDERMASK_PROJECTS, SOLDERMASK_CACHE | Where projects and the cache live |
SOLDERMASK_CORPUS | Where the routability corpus lives |
SOLDERMASK_ROUTABILITY | Use this routability model file |
JLCPCB_APP_ID, JLCPCB_ACCESSKEY, JLCPCB_SECRETKEY | JLCPCB API credentials, for the catalogue, stock and price |
GH_TOKEN, GITHUB_TOKEN | A GitHub token setup downloads Lightcycle with, when gh is not signed in |
Colour is on when output goes to a terminal. The banner prints in full when the window is at least 84 columns wide, and as one line otherwise.