Menu

Theme

Advanced features · Reference · CHECKED ON 5.0.0

Logisim-evolution command-line reference

Logisim tty (the --tty option) is its text-only mode: --tty table circuit.circ prints a circuit's full truth table without opening a window, and the other formats run the simulation until a pin labelled halt reads 1. Logisim-evolution 5.0.0 has 18 options, listed below with their exact arguments. The installers' own launchers accept them too, so you do not need a separate Java. Option names changed in 3.7.0 (-tty became --tty), so older tutorials may not work.
FOR
TAs, CPU builders and CI users · Logisim-evolution 5.0.0, classic 2.7.1 options at the end
CHECKED
12 Nov 2026
Checked against Logisim-evolution 5.0.0 on 5 machines
On this page

All options

Logisim-evolution 5.0.0 command-line options (from --help, our wording)
-b --test-circuit<path_to_circ>Opens a file and runs the test bench circuit inside it, then exits.The bench is a circuit named logisim_test_verif with output pins test_bench_done_o and test_bench_ok_o. Our four bench files never finished: a folder chooser stayed open (F103). Exit codes 0 (pass) and 255 (fail) are from the code in the jar.Not completed (F103)
--clear-prefsnoneClears the saved preferences at startup.Not run. The preference folders are listed on the Windows and Linux install pages.Not run
-f --test-fpga<circ_input> <circuit_name> <board> [tick frequency] [HDLONLY]Builds the HDL for a board and, without HDLONLY, synthesises and downloads.31 boards in the jar. On a file with no saved I/O mapping it builds the netlist, passes the DRC and stops with exit 255 (F51). Run under Xvfb in our test.Tested (F51)
--fpga-cable<name>Chooses the Intel/Altera Quartus cable for --test-fpga by its exact name from quartus_pgm --list.Needs a board and Quartus; we have neither.Not testable
-g --gates<shape>: ANSI or IECSets the gate symbol style.Another value prints "Argument for --gates option must be “ANSI” or “IEC”." and exits 10 (F108).Tested (error)
-h --helpnonePrints the option summary.Exit 0 (F01, F108).Tested
-l --load<file> [label]Loads a memory image into all RAM and ROM parts, or only those with the label. May be repeated.Works with --tty only. It takes every following word as its own value, so put the circuit before it (F16); before the circuit it prints "Invalid arguments for “--load”" and exits 10. Ignored by a --tty table run without a halt pin (F13).Tested (F13, F16, F108)
-m --geometryWIDTHxHEIGHT[+X+Y]Sets the main window size and position.Not run.Not run
-n --new-file-format<circ_input> <circ_output>Opens a file of any Logisim version and writes it in the current format.Needs a display; a classic file stops at a dialog (F18). Our run on a 5.0.0 file wrote a 4,241-byte file and exited 0 (F92).Tested (F18, F92)
--no-splashnoneHides the splash screen.Used in every window run we made.Used
-o --locale<lang>Sets the interface language.An unsupported value prints the supported locales and exits 10 (F108).Tested (error)
-s --substitute<lib1> <lib2>When loading, replaces library lib1 with lib2.Works when lib1 is written as the circuit file stores the library name; the original library must exist.Tested (F135)
--save<file>Saves RAM contents to an image file after a --tty run.With --tty only. On a circuit with no RAM it prints "No RAM was found for the “--save” option." and exits 255; we did not run it on a circuit with RAM (F92, F108).Partly tested
-t --tty<format>Runs without a window. See the formats below.An unknown format exits 10 and lists the nine names (F108).Tested (F05, F19, F91)
--toplevel-circuit<circuit_name>Uses that circuit instead of the file's main circuit.Printed the truth table of a subcircuit in our test; an unknown name throws a NullPointerException and exits 255 (F92, F108).Tested
-u --user-templateempty, plain or a file nameChooses the template for new projects.Not run.Not run
-v --versionnonePrints the version, build and Java runtime, then exits.Exit 0 (F108).Tested
-w --test-vector<circuit_name> <test_vector> <circ_file>Runs a test vector and prints Passed and Failed counts.Exit 0 even when tests fail; needs a display (F17, F18). See the test vector guide.Tested (F17, F18, F102)

The count is 18, the same as the usage line of --help (F01). GUI equivalents: -g and -o are in File, Preferences, International; -n is opening the file and File, Save As; -w is Simulate, Test Vector…; --clear-prefs has no menu item (F46).

–tty formats

The format is a comma-separated list of these nine names. An unknown name prints the list and exits 10.

The --tty formats on 5.0.0
tableThe full truth table, one row per input combination, column names from the pin labels. With a halt pin it simulates instead (F05, F13).Exits on its own (no halt pin)
table,csvThe same table with commas between the values.Exits
table,hexIdentical to table for 1-bit pins; we did not check wider pins.Exits
binary, hex, csv, tabs aloneNothing on our full adder, which has no halt pin; the run kept going until we killed it at 12 s. They change how other formats print values.No
halthalted due to halt pin, logged at ERROR level, when the halt pin reads 1.Exit 0 at the halt
speed33250 Hz (399 ticks in 12 milliseconds) on a 200-count counter. On a 16-bit counter 5.0.0 ran at 405 to 465 kHz and classic 2.7.1 at 112 to 138 kHz (F19).Exits at the halt pin
statsA component count table: Pin 2, Clock 1, Constant 1, Comparator 1, Counter 1; total 6.Exits at the halt pin
ttyWhat a TTY component prints, and it feeds the keyboard to a Keyboard component. With neither: No TTY or Keyboard component was found. and exit 255.Exit 255 without them

The halt pin

An output pin labelled exactly halt. The run ticks the clock until the pin reads 1, then stops. Our 200-count counter used it (F91).

What “tty” is not

The TTY component in the Input/Output library is a character display. The --tty option shares only the name.

Exit codes

What we saw on 5.0.0
--help, --version0F01, F108
--tty table, and --tty halt at the halt pin0F91
Unknown option, or a value 5.0.0 rejects10F108
--tty tty with no TTY or Keyboard, --save with no RAM255F108
Circuit file missing255F92
--toplevel-circuit with an unknown name (NullPointerException)255F92
--test-vector: pass, fail, load error, circuit not found0 every timeF17, F102
--test-vector with no display1 (HeadlessException)F18
--test-fpga … HDLONLY on a file with no I/O mapping255F51
--test-circuit pass or fail0 or 255, from the code in the jar; not runF103

Recipes

Terminal
java -jar logisim-evolution-5.0.0-all.jar --tty table full-adder.circ
Output: A B Cin S Cout
Output: 0 0   0 0    0
Output: 0 0   1 1    0
Output: 0 1   0 1    0
Output: 0 1   1 0    1
Output: 1 0   0 1    0
Output: 1 0   1 0    1
Output: 1 1   0 0    1
1 1   1 1    1
exit: 0

Classic 2.7.1 prints the outputs for the current inputs and keeps simulating until a halt pin goes high, so without one it never exits (F05).

Truth table as CSV for a spreadsheet

Terminal
java -jar logisim-evolution-5.0.0-all.jar --tty table,csv full-adder.circ
Output: A,B,Cin,S,Cout
Output: 0,0,0,0,0
Output: 0,0,1,1,0
Output: 0,1,0,1,0
Output: 0,1,1,0,1
Output: 1,0,0,1,0
Output: 1,0,1,0,1
Output: 1,1,0,0,1
1,1,1,1,1

Measure simulation speed

Put a halt pin on a counter and run --tty speed. Output: 33250 Hz (399 ticks in 12 milliseconds) on our 200-count counter. The numbers on a 16-bit counter, and the comparison with classic 2.7.1, are in the clock guide (F19).

Run a circuit with a program in a ROM

The circuit goes first, then --load, then the file and the label of the memory:

Terminal
java -jar logisim-evolution-5.0.0-all.jar --tty halt cpu.circ --load program.txt PROG

Images that load and images that fail are in ROM and loading memory and the memory image tool. Do not combine --load with a plain --tty table run: the table is computed before memories load, so the ROM reads zeros (F13).

Save RAM after the run

Add --save ram.txt to a --tty run. We checked only the error case: on a circuit with no RAM it prints No RAM was found for the “--save” option. and exits 255 (F108). Saving from a circuit that has RAM is not tested here.

Run a test vector in CI

Two lines: put xvfb-run -a in front of java, and read Passed: N, Failed: 0 from the output, not the exit code. Details in the autograder recipe.

Convert an old file to the current format

Terminal
xvfb-run -a java -jar logisim-evolution-5.0.0-all.jar -n old.circ new.circ

It needs a display. A classic-format file stops at a compatibility dialog, and the process does not exit after it writes the file, so kill it once the output file exists (F18). See the .circ file.

Generate HDL without synthesis

Terminal
java -jar logisim-evolution-5.0.0-all.jar --test-fpga full-adder.circ main BASYS3 HDLONLY
Output: Building netlist for sheet “main”
Output: Circuit “main” has 8 nets and 0 buses.
Output: Circuit “main” passed DRC check.
Output: The Board BASYS3 has:
Output: 51 Pin(s)
Output: 21 Button(s)
Output: 28 Led(s)
Output: Not all IO components have been mapped to the board “BASYS3”; please map all components to continue!
exit: 255

Map every input and output to the board in the window once and save the file first. Without that the command stops as above (F51). We did not run it on a mapped file, so we do not say where the HDL files are written. The FPGA guide shows the mapping window.

Use the app’s own launcher instead of java -jar

On Windows

Command Prompt
C:\Program Files\logisim-evolution\> logisim-evolution.exe --version

On macOS

Terminal (macOS)
/Applications/Logisim-evolution.app/Contents/MacOS/Logisim-evolution --tty table full-adder.circ

On Linux

Terminal (Linux)
/opt/logisim-evolution/bin/logisim-evolution --tty table full-adder.circ

These launchers accepted the options in our runs (F28, F33), so no separate Java is needed.

Run on a server or in WSL

--tty works with no display. --test-vector and --new-file-format need one: use xvfb-run -a (F18). Java 21 is required for the jar (Java requirements).

Classic Logisim 2.7.1 options

Single dash and no long forms. This is the -help output of logisim-generic-2.7.1.jar:

Classic 2.7.1 options (from -help)
-tty formatRun without graphical interface.
-load fileLoad image file into RAM (works with -tty only).
-sub file1 file2Load file replacing library file1 with file2.
-empty, -plain, -template fileUse the empty template, the standard template, or a file.
-gates shaped|rectangularUse the specified gate style.
-locale strUse the locale given in str.
-accents yes|noUse accented characters or ASCII equivalents.
-nosplash, -version, -helpHide the splash screen; display the version and exit; display the summary and exit.
-clearpropsClear application preferences at startup.

Only -tty table was run on 2.7.1 (F05, F93); the other rows are the help text, not tests. There is no test vector option (F106). More on classic Logisim 2.7.1.

The --test-fpga … HDLONLY form that writes VHDL or Verilog is described in VHDL and Verilog.

Frequently asked questions

What is tty in Logisim?

The text-only mode: --tty runs a circuit without a window and prints results to the terminal. It is not the TTY component from the Input/Output library, which is a character display.

How do I get a truth table from the command line?

java -jar logisim-evolution-5.0.0-all.jar --tty table circuit.circ. In 5.0.0 it prints every input combination and exits; classic 2.7.1 behaves differently (F05).

Why does --load say Invalid arguments?

--load takes every following word as its own value, so the circuit file must come before it: --tty halt circuit.circ --load image.txt label (F16, F108).

Why does my ROM read zeros with --tty table?

The table is computed before memories are loaded, so --load is ignored unless the circuit has a halt pin and runs as a simulation (F13).

Can I run Logisim without a display?

--tty works headless. --test-vector and --new-file-format need a display, so run them under xvfb-run (F18).

Do I need Java to use the command line with the installer?

No. The launcher inside the installed app accepts the same options (F28).

Sources

  1. Logisim-evolution 5.0.0 --help output, logisim.dev lab data: test-data/lab17-2026-11-12-test-vectors/logs/cli-help.txt (F01)
  2. Errors and exit codes, logisim.dev lab data: test-data/FINDINGS.md F17, F18, F92, F103, F108
  3. tty formats, logisim.dev lab data: test-data/lab11-2026-11-11-cli/logs/ (F91)
  4. Classic 2.7.1 -help output, logisim.dev lab data: test-data/lab17-2026-11-12-test-vectors/logs/classic-help.txt

Try: , , ,