JOINUS-D Command Line Interface (CLI)

JOINUS-D 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

JOINUS-D [OPTION]...
JOINUS-D -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.
—	--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.

Unlike the windowed application, the CLI does not run a simulator or open any plot window — it only converts. There is no -r/--run or -p/--plot equivalent (see Limits and errors for what the CLI does and does not do).

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 Preferences (or, for circuit expansion, the "Replace .include by Subcircuits" 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 for this run only. Unlike the windowed application (which reads these from AppConfig::conversion()), the CLI builds its own one-off ConversionParams from the command line each time — there's no global state to save and restore, so using these flags never touches your saved Preferences or affects any other run.

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

.include /home/user/joinus-d/subcircuits/MySubcircuit.cir

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

.SUBCKT MySubcircuit 0 1 2

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

Conversion modes

JOINUS-D 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.

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:

JOINUS-D -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:

JOINUS-D -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!. This check runs before the -h/-v short-circuit below, so JOINUS-D -h followed by more than 15 junk arguments raises this error instead of printing help.
• -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.
• There is no -r/--run (simulate) or -p/--plot option: the CLI only converts. Running a simulator and viewing plots requires the windowed application.

Examples

Display the help menu:

JOINUS-D -h
JOINUS-D --help

Display the current version:

JOINUS-D -v

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

JOINUS-D -i circuit.lp -o netlist.cir

Convert to a SPICE netlist for the JSIM simulator instead:

JOINUS-D -i circuit.lp -o netlist.cir -j

Convert to a named subcircuit:

JOINUS-D -i circuit.lp -o netlist.cir -s MySubcircuit

Convert to an unnamed subcircuit (defaults to unnamed):

JOINUS-D -i circuit.lp -o netlist.cir -s

Convert while grouping components by type:

JOINUS-D -i circuit.lp -o netlist.cir -g

Combine subcircuit conversion, JSIM simulator, and component grouping:

JOINUS-D --input circuit.lp --output netlist.cir --subcircuit MySubcircuit --jsim --group

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

JOINUS-D -i circuit.lp -o netlist.cir -wf

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

JOINUS-D -i circuit.lp -o netlist.cir -wc

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

JOINUS-D -i netlist.cir -o circuit.lp

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

JOINUS-D -i circuit.lp -o netlist.cir --vcc 3.3m

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

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

Convert without a header for this run only:

JOINUS-D -i circuit.lp -o netlist.cir --no-header

Convert with the circuit expanded, for this run only:

JOINUS-D -i circuit.lp -o netlist.cir -e

Notes

• The windowed application is documented in the JOINUS-D User Manual.
• JOINUS-D's CLI is the same as L2SPICE's, minus the -r/--run and -p/--plot (simulate/plot) options — JOINUS-D's CLI only converts.
• The exact behavior is implemented in console/console_app.cpp (flag parsing and dispatch); the -h/--help text lives in assets/settings/help.txt.