soldermaskdocs

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

FromCommand
GitHubuv tool install "git+https://github.com/ashwinsk01/soldermask.git@integration"
A checkoutpip 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

CommandDoes
soldermask "<prompt>"Build a board from a sentence (below)
soldermask --design FILEBuild a board from a design file, with no model
soldermask setupFetch what the install cannot carry, and name what is missing
soldermask projectsList, show, fork and revert saved boards, and judge them again
soldermask serveRun the app
soldermask mcpServe the pipeline as MCP tools, for another model to drive
soldermask partsShow a part's datasheet record, or read its datasheet (below)
soldermask learnThe routability corpus and model
soldermask docsBuild this manual, so the app can serve it at /docs
soldermask versionPrint the version
soldermask releaseAdd a changelog note, or cut a release
soldermask bannerPrint the brand mark

Every subcommand except version and banner takes --help.

Common tasks

  1. Build a board from a sentence:

    soldermask "a 5V to 3.3V regulator breakout with a power LED"
  2. Build from a design file you wrote, with no model call:

    soldermask --design my_design.json --out build/
  3. Save the build as a version of a project:

    soldermask "a 5V to 3.3V regulator breakout" --project LDO
  4. 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
  5. 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

FlagDefaultDoes
promptWhat board to build, in words
--design PATHLoad a design JSON and skip the model
--out DIRbuildWhere the fab files, KiCad files and pictures go
--project NAMEAlso save the build as a new version of this project. A missing project is created.
--from NAMEStart from this project's current version. The prompt becomes an edit.
--qty N1, 10, 25, 100A quantity to price and stock-check. Repeat it for several.
--version, -VPrint the version and exit

How much to run

FlagDoes
--place-only (--no-route)Stop after placing. Nothing is routed.
--route-onlyRoute the --from version's placement again. Needs --from and takes no prompt.
--sim-onlyResolve and simulate only. Writes sim.json to --out and saves no version.
--no-simSkip the ngspice simulation. The board says it was not simulated.
--no-renderSkip 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.

FlagDefaultDoes
--seed Nthe project's rules.seed, else 1The anneal seed. The same design, pins and seed give the same placement.
--router NAMElightcycleWhich router lays the copper first (see the table below)
--no-pourRoute ground as tracks instead of pouring it
--no-precedentPlace from scratch, even when the corpus holds a board like this one. Precedents are still listed.
--no-markLeave the maker's mark off the silkscreen, the Gerbers and the KiCad file
--layers 2|4the design's own, else 2Copper 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.
--routerRouterTrack / clearance
lightcycleLightcycle, this tree's own router (the default)0.127 / 0.127 mm
krtThe A* router0.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

FlagDefaultDoes
--backend NAMEclaude-code, or SOLDERMASK_BACKENDWhich model designs the board: claude-code, gemini, claude or groq
--model IDthe backend's ownUse another model id
--effort LEVELhighReasoning effort, for claude-code, claude and groq
--repair N0Feed the pipeline's findings back to the model and revise, up to N times
--wireA 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.

  1. While it runs. For a prompt, the design line lists each search, pin read and check the designer makes. Then build prints each stage as it starts.
  2. When it returns. One section a stage, from parts to saved, summarised from the finished build.

Then come three sections:

  1. board: a picture of the board, seen from the front.
  2. VERDICT: whether this is a working board.
  3. what this board does NOT guarantee: the gaps, printed last so they stay on screen.
VerdictMeans
passesEvery 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 JUDGEDNothing that ran failed, but a check the verdict needs did not run. The lines under it say which.
DID NOT PASSA 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 statusMeans
0Built, with no ERC errors and a KiCad file that passed its check
1ERC errors, a KiCad file that failed its check, or a build that could not start (for example, no such project)
2The model's credentials are missing

A failed verdict does not change the exit status.

What it writes

File in --outWhat it is
design.jsonThe design that was built
Gerbers, drill, BOM, CPLThe fab package
<board>.dsnThe placed board as a Specctra design, which other routers read
board.svgA drawing of the board
inventory.jsonStock and prices at each quantity
routing.jsonWhat the router did: the placements it tried, the one kept, the nets left short and the pour
<board>.kicad_pcb, <board>.kicad_proThe KiCad board, and its project with the rule it was routed at
models/*.stepThe 3D models KiCad renders with. A --project build writes models/*.wrl instead.
meshes.jsonThe vendor 3D meshes the viewer draws
<board>.kicad_schThe schematic
sim.jsonThe simulation, when the circuit was simulated
<board>-3d.png, <board>.glbKiCad's raytrace and 3D model, unless --no-render
inspector.htmlA standalone viewer with the 3D models inside it
wire.jsonWhat the wiring turn changed, with --wire
repair.jsonThe 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 design

Use --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]
FlagDoes
(none)Report what is installed. Install Lightcycle and fetch the KiCad symbol library if they are missing.
--checkReport only, and fetch or build nothing
--astarAlso clone and build the A* router at its pinned commit. Needs git and cargo, and takes minutes.
--partsAlso take the whole JLCPCB catalogue, so parts resolve offline (below)

Each line of the report is one thing the build uses:

LineChecks
home, cacheWhere data and the cache live
kicadkicad-cli, for the DRC, renders and the Gerber cross-check
routerLightcycle, the default router
symbolsThe KiCad symbol library
astarThe A* router
ngspiceThe simulator
mould, annealThe compiled core. Without it the results are the same and slower.
popplerpdftotext, which reads datasheets. Without it, sheets are fetched and never read.
jlcapiWhether JLCPCB API credentials are set, and whether the app is granted the Parts API
partsWhere 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 --parts

This 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:

SourceWhenWhat it takes
JLCPCB's own APIJLCPCB_APP_ID, JLCPCB_ACCESSKEY and JLCPCB_SECRETKEY are set, and the app is granted the Parts APIThe listing (about 7.25 million records, just under an hour), then a detail record for every code in stock (about 15 minutes)
The jlcparts mirrorOtherwiseThe 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]
CommandDoes
projects listEvery project with its versions, parts, ERC errors, cost and summary. The default.
projects show NAMEThe version table, with the current version starred
projects fork NAME NEWCopy a project under a new name
projects revert NAME vNNNMake 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 rejudged record and a note are rewritten.
  • The first board.json is kept beside it as board.json.before-rejudge, and never overwritten.
  • A version built before verdicts existed stays unjudged. Its line says what the DRC finds today.
  • --dry-run prints 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]
FlagDefaultDoes
--port, --host0.0.0.0:8443The address to bind
--httpServe plain HTTP. Pages load, but the phone's tilt control needs a secure origin and will not work.
--token Xgenerated once, kept in the cache directoryThe access token other devices must present
--no-authNo token. Anyone on the network can use the app.
--proxyBehind a reverse proxy: trust X-Forwarded-*, and require the token from every client, including loopback
--workers N2How many builds may run at once. Each one runs a router.
--log-file PATHstderrAppend logs to this file
--debugVerbose logging

python serve.py runs the same command. See Running in production.

MCP server

CommandDoes
soldermask mcpServe the pipeline as tools on stdin and stdout
soldermask mcp --toolsPrint the tool list as JSON and stop
soldermask mcp --model-callsLet resolving a part ask this tree's own models. Off by default, so the client is the only model in a run.
soldermask mcp --httpThe same server over HTTP with bearer keys. Flags: --host, --port 8787, --keys FILE, --projects DIR, --builds N, --origin URL.
soldermask mcp keys add NAMEIssue a key. It prints once; the keys file keeps only its digest.
soldermask mcp keys listEvery key's name, directory and dates, never the key
soldermask mcp keys revoke NAMEThe 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.

CommandDoes
soldermask parts show C50506Print the part's record from the disk. Exits 1 if it has none.
soldermask parts read C50506Print the record, reading the sheet first if there is none
soldermask parts read C50506 --forceRead the sheet again, though a record is on file
--jsonPrint 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

CommandDoesMain flags
learn statusRoutes on disk, from how many boards, how many routed clean, and the shipped model
learn generatePlace and route boards into the corpus until the time is upSee below
learn trainFit the models, judge them, and ship the best--epochs 60, --keep rudy|linear|cnn, --out PATH, --recipe lean|full, --seeds N, --router LABEL
learn reportThe shipped model's provenance and held-out scores
learn crossvalHold out every family once--folds 4, --epochs 60, --seed 0, --out
learn ablateTrain the network with one input taken away at a time--only, --seeds, --epochs 60, --out
learn relabelRoute again every example the router never counted--rules, --edge, --hours 2, --workers
learn backfillRoute again every example with no record of where its copper went--hours 2, --workers
learn redrawDraw every example's maps again from its stored placement. No route runs.

train, relabel and redraw rewrite the shipped model or the corpus.

  • generate labels with the A* router under kicad-cli by default (--router astar), into .cache/corpus-astar. --router freerouting needs Java and the freerouting jar, and only reproduces the older labels.
  • train needs torch (pip install -e ".[learn]"). Without it, only the two logistic baselines are fitted.
  • train --router LABEL fits only on the examples one router labelled, such as freerouting-2.4.1.
  • SOLDERMASK_CORPUS keeps the corpus somewhere other than .cache/corpus.
  • SOLDERMASK_ROUTABILITY points the app at another model file.

learn generate

FlagDefaultDoes
--hours H1How long to run
--workers N4Boards routed at once
--seed N0The run's seed
--per-board N40Placements tried of each board on disk
--synthetic N400Boards drawn from the catalogue
--synthetic-variants N3Further anneals of each synthetic board, from other seeds
--kinds LISTevery kindComma-separated transform kinds to draw, such as anneal
--router astar|freeroutingastarWhich router labels the examples
--boards DIRevery DSN in the repositoryOnly the DSNs under this directory
--max-boards NA fixed sample of this many boards, so a budget routes fewer boards several ways
--max-parts NOnly 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 flagDefaultDoes
--backendsgemini,claudeThe models to run
--n Nevery promptHow many prompts to run
--out DIRevalWhere results go
--repair N0Revise up to N times. 0 is a single shot, the control.
--designs DIRReplay saved designs instead of calling the model. With --repair 0, the run is deterministic.
--no-routeSkip the router. Faster, but pass@1 then ignores routing.
--wireAdd the wiring turn
--tier ABCDRun only these difficulty tiers
--rescore DIR…Score a stored run again under today's pass rule. Builds nothing.
repair flagDoes
--design PATHThe design to measure
--out DIRWhere the rounds accumulate
--prompt TEXTWhat the board was asked for
--routeAlso place and route, so the full pass rule applies
--resetStart the log again

See Repair loop and evaluation.

Version and releases

CommandDoes
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 showWhat is waiting under Unreleased
soldermask release bump major|minor|patchCut a release: bump the version, roll the changelog, commit and tag. Flags: --no-git, --allow-empty, --dry-run.

See Versioning and releases.

Docs

CommandDoes
soldermask docsBuild docs/ into site/, which the app serves at /docs
soldermask docs serveRun 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.

VariableDoes
NO_COLORTurn colour off
FORCE_COLORTurn colour on, even into a pipe
COLORTERMtruecolor or 24bit gives the 24-bit orange; otherwise the nearest of 256 colours
SOLDERMASK_BACKENDThe default model backend
SOLDERMASK_ROUTERThe router for a design that names none: lightcycle (the default) or krt
SOLDERMASK_PROJECTS, SOLDERMASK_CACHEWhere projects and the cache live
SOLDERMASK_CORPUSWhere the routability corpus lives
SOLDERMASK_ROUTABILITYUse this routability model file
JLCPCB_APP_ID, JLCPCB_ACCESSKEY, JLCPCB_SECRETKEYJLCPCB API credentials, for the catalogue, stock and price
GH_TOKEN, GITHUB_TOKENA 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.

On this page