CLI

The nexsim CLI compiles VHDL files, runs a simulation, and writes the results to a VCD file. Use it with agents, for scripting, batch runs, or when you prefer a terminal workflow.

Basic usage

nexsim design.vhd testbench.vhd --top testbench_entity --run-time 1000

This compiles both files, elaborates the top entity, simulates for 1000 ns, and writes output.vcd.

Opening a viewer

Add --open to launch a waveform viewer after simulation:

# Open with GTKWave
nexsim design.vhd tb.vhd --top tb --run-time 1000 --open gtkwave

# Open with Surfer
nexsim design.vhd tb.vhd --top tb --run-time 1000 --open surfer

If the viewer isn’t installed, nexsim prints instructions for opening the file manually.

Custom output path

nexsim design.vhd tb.vhd --top tb --run-time 1000 --output result.vcd

Default output is output.vcd in the current directory.

Multi-file designs

Pass all source files as arguments. File order doesn’t matter — dependencies are resolved during elaboration.

nexsim pkg.vhd adder.vhd top.vhd top_tb.vhd --top top_tb --run-time 5000

Output

A successful run prints:

Running VHDL simulation for 1000ns...
Simulation completed successfully!
VCD file generated: output.vcd

Signal changes are summarized in the terminal (first 5 per signal).

Error messages

If something goes wrong, nexsim tells you what failed:

• Compilation failed — syntax error or type mismatch in your VHDL
• Elaboration failed — unknown entity, port mismatch, or unresolved component

See the full option reference at CLI Reference.