L2SPICE Command Line Interface (CLI)¶

L2SPICE can be driven from the command line, without opening the windowed application. This is useful for scripting and batch conversions.

The CLI is activated automatically whenever the executable is called with at least one argument (argc > 1); with no arguments, the windowed application starts instead.

Usage¶

1 2	`L2SPICE [OPTION]... L2SPICE -i [FILE] -o [FILE] [OPTION]...`

Options¶

Flag	Long form	Argument	Description
`-h`	`--help`	—	Displays the help menu and exits.
`-v`	`--version`	—	Displays the current application version and exits.
`-i`	`--input`	`FILE`	Input file. Required for any conversion.
`-o`	`--output`	`FILE`	Output file. Required for any conversion.
`-s`	`--subcircuit`	`[NAME]` (optional)	Converts the circuit to a subcircuit. If `NAME` is omitted, the subcircuit is named `unnamed`.
`-g`	`--group`	—	Groups components by type in the generated netlist.
`-j`	`--jsim`	—	Converts for the JSIM simulator. By default (no `-j`), converts for JoSIM.
`-wc`	`--without-console`	—	Suppresses console output of the conversion result.
`-wf`	`--without-file`	—	Suppresses writing the result to the output file.
`-r`	`--run`	—	After a LibrePCB → SPICE conversion, runs the configured simulator (JoSIM/JSIM) on the result.
`-p`	`--plot`	—	Only meaningful together with `-r`. Also opens the FrugalPlot window with the simulation results.
—	`--vcc`	`VALUE`	Overrides the VCC value (e.g. `2.5m`) for this conversion only.
—	`--header`	`TEMPLATE`	Overrides the header template for this conversion only, and forces the header on regardless of the saved preference.
—	`--no-header`	—	Forces the header off for this conversion only.
`-e`	`--expand`	—	Inlines referenced subcircuits into the netlist for this conversion only, instead of `.include`-ing them. Only affects JoSIM output — JSIM always inlines them regardless of this flag.

-h/--help and -v/--version short-circuit the command: if either is present, all other flags are ignored.

Per-run setting overrides (`--vcc`, `--header`, `--no-header`, `-e`)¶

VCC value, header (on/off + template), and circuit expansion are normally persistent preferences — set once in Settings > Preferences (or, for circuit expansion, the "Expand circuit" checkbox in the Conversion Parameters panel) and reused for every conversion after that, GUI or CLI.

These four flags let a single CLI invocation override one of those values without touching the saved preference: the original value is restored immediately after the conversion finishes, so it's safe to use in scripts without affecting subsequent runs or the windowed application.

--vcc VALUE overrides the VCC value used in the generated netlist.
--header TEMPLATE overrides the header template text, and also forces the header on for this run (even if "include header" is off in your saved preferences) — otherwise supplying a template would have no visible effect.
--no-header forces the header off for this run, overriding the saved "include header" preference.
-e/--expand forces circuit expansion on for this run.

--header and --no-header are mutually exclusive; if both are given, --header takes precedence.

What "expand" actually does: when the circuit uses a subcircuit (e.g. a superconductor mock component), the producer normally writes a .include <path-to-subcircuit-file> line pointing at the external .cir file — the netlist stays small, but that file has to travel with it. -e/--expand instead reads the subcircuit file's content and pastes it directly into the netlist (recursively, so a subcircuit that references another subcircuit gets pulled in too), producing one self-contained file with no external dependencies. This only has an effect on JoSIM output — JSIM output is always fully expanded regardless of this flag, so -e is a no-op together with -j.

For a circuit that uses a subcircuit called MySubcircuit, the relevant line(s) of the generated netlist look like this:

Without -e (JoSIM default) — a reference to the external file:

1	`.include /home/user/l2spice/subcircuits/MySubcircuit.cir`

With -e — the contents of MySubcircuit.cir pasted in directly:

.SUBCKT MySubcircuit 0 1 2

*circuit*
... component lines ...
.ENDS

Conversion modes¶

L2Spice picks the conversion direction from the file extensions of -i and -o:

LibrePCB → SPICE: input file has the .lp extension. Output is written as a SPICE netlist (JoSIM or JSIM, depending on -j).
Back-annotation, SPICE → LibrePCB: input file has the .cir extension and output file has the .lp extension. The existing .lp file (given as -o) is updated in place using the values from the .cir netlist.

Any other combination of extensions is rejected with an explanatory message and a non-zero exit code.

Running the simulator (`-r` / `-p`)¶

-r/--run is only applied on a LibrePCB → SPICE conversion (it is ignored for back-annotation). It uses the simulator executable path configured in Settings > Preferences (same setting the windowed app uses for its "Execute" button), runs it on the freshly generated netlist, and writes:

the simulation output (.dat/.csv) into a simulation/ folder next to the output file,
a log file (<name>_logs.txt) in the same folder.

By itself, -r is headless: no window is opened, so it's safe to use in scripts and CI. Add -p/--plot to also open the FrugalPlot window with the results, exactly as the windowed app's Simulate (F10) action does — this requires a display and blocks the process until the window is closed, so only use it interactively.

If the simulator path isn't configured, or the simulator run fails, an error is printed and the process returns exit code 1.

Flag argument parsing — caveat¶

-i, -o, and -s all consume the token immediately following them as their argument. There is no check that this token isn't itself another flag. For example:

1	`L2SPICE -i circuit.lp -s -o netlist.cir`

parses -o as the subcircuit name (not as the --output flag), which is almost certainly not what you want. Always give -s an explicit name or place it last among the option flags:

1	`L2SPICE -i circuit.lp -o netlist.cir -s MySubcircuit`

Limits and errors¶

No more than 15 arguments are accepted (argc <= 16, which includes the program name); exceeding this raises Too many input parameters!.
-i and -o are both mandatory for a conversion (not needed for -h/-v); omitting either raises Input and output files must be provided!.
An unsupported combination of input/output extensions prints an explanatory message and returns exit code 1.
If the output file cannot be written, Cannot save the output file is printed and the process returns exit code 1.
On success, Converted successfully! is printed and the process returns exit code 0.
Note: the "too many parameters" and "missing input/output" checks raise a C++ exception that is not currently caught by the CLI, so the process aborts rather than exiting cleanly. Avoid relying on a specific exit code for these two cases in scripts — check stderr/output instead.

Examples¶

Display the help menu:

1 2	`L2SPICE -h L2SPICE --help`

Display the current version:

1	`L2SPICE -v`

Convert a LibrePCB circuit to a SPICE netlist (JoSIM by default):

1	`L2SPICE -i circuit.lp -o netlist.cir`

Convert to a SPICE netlist for the JSIM simulator instead:

1	`L2SPICE -i circuit.lp -o netlist.cir -j`

Convert to a named subcircuit:

1	`L2SPICE -i circuit.lp -o netlist.cir -s MySubcircuit`

Convert to an unnamed subcircuit (defaults to unnamed):

1	`L2SPICE -i circuit.lp -o netlist.cir -s`

Convert while grouping components by type:

1	`L2SPICE -i circuit.lp -o netlist.cir -g`

Combine subcircuit conversion, JSIM simulator, and component grouping:

1	`L2SPICE --input circuit.lp --output netlist.cir --subcircuit MySubcircuit --jsim --group`

Convert without writing an output file (print to console only):

1	`L2SPICE -i circuit.lp -o netlist.cir -wf`

Convert without console output (write to file only, e.g. for scripting):

1	`L2SPICE -i circuit.lp -o netlist.cir -wc`

Back-annotate an edited SPICE netlist into the original LibrePCB circuit:

1	`L2SPICE -i netlist.cir -o circuit.lp`

Convert and run the simulator, headless (no window — safe for scripts/CI):

1	`L2SPICE -i circuit.lp -o netlist.cir -r`

Convert, run the simulator, and open the plot window with the results:

1	`L2SPICE -i circuit.lp -o netlist.cir -r -p`

Convert with a one-off VCC value, without changing the saved preference:

1	`L2SPICE -i circuit.lp -o netlist.cir --vcc 3.3m`

Convert with a custom header for this run only (forces the header on):

1	`L2SPICE -i circuit.lp -o netlist.cir --header "%2 converted for CI on %1"`

Convert without a header for this run only:

1	`L2SPICE -i circuit.lp -o netlist.cir --no-header`

Convert with the circuit expanded, for this run only:

1	`L2SPICE -i circuit.lp -o netlist.cir -e`

For a description of the windowed application, see the L2SPICE user manual.