53
The command line (bspice)
bspice.exe runs the BetterSPICE engine without a window, with the same circuit files. It’s installed next to the app.
53.1Conventions
| Topic | Rule |
|---|---|
| Invocation | bspice <command> [file] [options]. No command prints the usage. |
| Exit codes | 0 success, 1 diagnostics with errors or a failed check, 2 a usage error. |
| Output | Results (JSON, CSV, netlists, tables) on standard output. Diagnostics as one JSON object per line. Progress and summaries on standard error. |
| Options | --name value, --name=value or -o value. Negative numbers work: --start -5. An option a command doesn’t know is an error that lists the ones it does know, never ignored. |
| Numbers | SI suffixes f, p, n, u (or µ), m, k, meg, g, t and mil, case-insensitive (so 1M is milli, 1meg mega). Trailing units are ignored: 5ms. |
| Threads | --threads auto (the default) or --threads N on any command. validate and verify run their files side by side on that many threads, and ngspice runs that overlap go to hidden ngspice worker processes. Auto is every core but one. BSPICE_THREADS=N sets the same thing, and --threads 1 makes runs sequential. Results are the same on any thread count (Threads). |
| Engine | op, tran, ac, dc, noise, pz and loopgain use the built-in engine. Vendor-model runs in ngspice need export-spice and ngspice, or the app. |
53.2Every command
| Command | Options | What it does |
|---|---|---|
validate <file|folder>… | Checks circuits without simulating: ground, floating nets, source loops, pins, parameters. A folder is searched for .bsc files. Exit 1 on any error. | |
op <file> | --out | DC operating point: net names, node voltages, pin currents and power per part. |
tran <file> | --stop, --max-step, --out | Transient. Defaults from the file's sim.simulate, max step stop/1000. |
ac <file> | --source, --fstart (1), --fstop (1 MHz), --ppd (20), --out | AC sweep: magnitude in dB and phase per signal, relative to a 1 V stimulus on the source. |
dc <file> | --source, --start, --stop, --step, --out | DC sweep of a source. |
render <file> | --png (required), --scale (20) | A PNG picture of the schematic. |
export-spice <file> | -o | An ngspice netlist, every model parameter written out. |
ngspice <netlist> | --analysis, --out | Runs a netlist in the bundled ngspice. |
verify <folder|file> | --html, --json, --failures, --all, --grid union|ngspice | Runs circuits in BetterSPICE and ngspice and compares every signal. Exit 1 on any failure. |
verify-vendor | --models, --html | Checks vendor model conversion and pin mapping against direct ngspice runs. |
verify-approx | --models, --json | Measures the behavioural models against reference circuits. |
verify-status | The verification status of every device type, as JSON. | |
report <file> | --html, --fft, --svg | The self-contained HTML report. |
import <file> | --out, --report, --no-supplies, --flat, --schematic, --quiet | KiCad or EasyEDA Pro to .bsc. |
parts list [folder] | --query | Lists part files. |
parts show <file|MPN> | Prints a part file and its problems. | |
parts validate <file|folder>… | Checks part files. | |
parts new --template <kind> | -o | A new part file with TODO markers and datasheet hints. |
parts quick <kind> key=value… | Fits model parameters to datasheet numbers. | |
parts quick defaults <type> [variant] | The typical values of a device type. | |
tline-calc <variant> key=value… | --diff, or <file> --part | The transmission line calculator. |
models … | The model catalogue tools (Commands for the catalogue). | |
mcp | The MCP server for AI agents. | |
serve | --port (47800) | The control API without a window, for the browser version. |
help, version | Usage and version. |
53.3Examples
bspice validate examples bspice op examples\basics\voltage-divider.bsc bspice tran examples\basics\rc-charge.bsc --stop 10m --max-step 10u --out run.csv bspice ac filter.bsc --source V1 --fstart 10 --fstop 100k --ppd 50 --out bode.csv bspice dc divider.bsc --source V1 --start 0 --stop 5 --step 0.1 bspice render board.bsc --png board.png --scale 30 bspice export-spice rc.bsc -o rc.cir bspice ngspice rc.cir --analysis ".tran 1u 5m" --out ng.csv bspice report psu.bsc --html psu-report.html bspice import board.kicad_sch --out board.bsc --report import.json bspice parts new --template ldo -o ap2112.bspart bspice parts validate parts\library bspice parts quick diode vf=0.7 if=10m bspice tline-calc microstrip w=3m h=1.6m er=4.5 len=0.1 bspice verify verification\circuits --html verification\report.html
53.4Output formats
--out omitted or json prints JSON, csv prints CSV, and anything else is a file name (CSV when it ends in .csv). A transient's CSV has a time column and one column per signal, V(net) and I(part). An AC CSV has frequency and a dB and degrees column per signal. An operating point cannot be CSV.
> bspice parts quick diode vf=0.7 if=10m
{"type":"diode","variant":"rectifier","p":{"is":2.93e-9,"n":1.8,"rs":0.0},
"notes":["n = 1.8 assumed; give vf2 at if2 to fit it."]}
> bspice tline-calc microstrip w=3m h=1.6m er=4.5
{"ok":true,"z0":49.66,"epsEff":3.368,"vf":0.545,"td":6.12e-10, ...}
Try it
Check every example before a release
- Run
bspice validate examples. - Run
bspice verify verification\circuits --failures.
You should seeThe first prints a summary such as "validated 523 file(s): 0 with errors". The second lists only failing comparisons, and exits 0 when everything passes.