CLI Reference

This page provides a complete reference for all command-line options in stg.

Global Options

-h, --help — Print the help message for a command or subcommand
-V, --version — Print the version of stg

`stg generate`

Generate a testbench and optionally compile it.

stg generate [OPTIONS] [VERILOG_FILES...] --out <OUT> --type <TYPE>

Verilog files can be specified as positional arguments or with --verilog. Both are equivalent.

File and Module Options

[VERILOG_FILES...] or --verilog <VERILOG> — (Required) Path to DUT Verilog file(s).
- Single: stg generate dut.v ... or --verilog dut.v
- Multiple: stg generate dut1.v dut2.v ... or --verilog dut1.v --verilog dut2.v
--module <MODULE> — DUT module name(s). Strongly recommended when a file contains multiple modules. For multi-DUT, use comma-separated names (--module dut0,dut1) or repeat the flag (--module dut0 --module dut1). A single name is used for all DUTs.
--golden <GOLDEN> — Path to the golden reference (Verilog file or C++/SystemC header).
--golden-module <GOLDEN_MODULE> — Golden module name (for Verilog golden files with multiple modules).
--out <OUT> — (Required) Output testbench path (e.g., tb.sv or tb.cpp).
--out-exe <OUT_EXE> — Compile and output an executable. If provided, STG compiles automatically.
--out-header <OUT_HEADER> — Output path for golden model header template (CC/SC stage 1).

Design Type and Signal Options

--type <TYPE> — (Required) Design type:
- combinational — Pure combinational logic
- seq_clocked — Sequential design with clock
- seq_done — Sequential design with done/valid signal
--clock <CLOCK> — Clock signal name (for seq_clocked and seq_done).
--reset <RESET> — Reset signal name.
--reset-active <RESET_ACTIVE> — Reset polarity: high, low, or unknown.
--done <DONE> — Done/valid signal name (for seq_done).
--control-signals [<NAMES>...] — Signals to enumerate exhaustively.
--data-signals [<NAMES>...] — Signals to sample randomly.

Test Generation Options

--random-samples <N> — Random samples per control vector. Default: 1024.
--max-enumeration <N> — Max control signal width to enumerate (2^N). Default: 26.
--timeout <NS> — Simulation timeout in nanoseconds. Default: 1000000000.
--debug — Enable debug output with detailed signal values.
--exit-on-error — Exit immediately on first mismatch.
--print-on-error — On each mismatch, log all input values and internal DUT states to a JSON file (error_log.json). In CC/SC mode, internal signals are accessed via Verilator’s --public-flat-rw; in SV mode, only input/output ports are logged. When combined with --exit-on-error, only the first error is recorded.

Compilation and Verilator Options

--verilator — Use Verilator instead of iverilog.
--verilator-mpi — Enable MPI for parallel test execution.
--verilator-jobs <N> — Parallel Verilator compilation jobs. Default: 4.
--verilator-coverage — Enable coverage instrumentation.
--verilator-ignore-warnings — Ignore common width warnings.
--compile-flags <FLAGS> — Additional compiler flags.
--emplace-module — Embed DUT and golden modules in the testbench file (SV mode only).

C++/SystemC Options

--cc — Generate a C++ testbench using Verilator.
--sc — Generate a SystemC testbench using Verilator.

Other Options

--config <CONFIG> — Load options from a YAML configuration file.

`stg generate-fsm`

Generate an FSM-coverage-enhanced C++ testbench using DFS over the state graph.

stg generate-fsm [OPTIONS] [VERILOG_FILES...] --golden <GOLDEN> --out <OUT>

Required Options

[VERILOG_FILES...] or --verilog <VERILOG> — DUT Verilog file(s).
--golden <GOLDEN> — Golden reference Verilog file.
--out <OUT> — Output testbench path (.cpp).

Common Options

--module <MODULE> — DUT module name. Default: first module in file.
--golden-module <GOLDEN_MODULE> — Golden module name. Default: first module in file.
--out-exe <OUT_EXE> — Also compile to executable.
--clock <CLOCK> — Clock signal name. Default: clk.
--reset <RESET> — Reset signal name. Default: rst.
--reset-active <RESET_ACTIVE> — Reset polarity: high or low. Default: low.
--fsm-method <METHOD> — FSM extraction method: lm or deterministic. Default: lm.
--state-analysis <FILE> — Load/save FSM analysis JSON (caching).

FSM / LM Options

--lm-provider <PROVIDER> — LLM provider: gemini, openai, openrouter.
--lm-name <MODEL> — Model name (e.g., gemini-2.5-flash).
--lm-endpoint <URL> — Custom API endpoint.
--dfs-passes <N> — DFS passes with random data. Default: 5.
--transition-timeout <N> — Clock cycles to wait for transition conditions. Default: 100.
--random-samples <N> — Extra random samples after DFS. Default: 32.

Debugging and Error Options

--debug — Enable debug output.
--exit-on-error — Exit the testbench immediately on first mismatch.
--print-on-error — On each mismatch, log all input values and internal DUT states to a JSON file (error_log.json). Internal signals are accessed via Verilator’s --public-flat-rw. When combined with --exit-on-error, only the first error is recorded.

Compilation Options

--verilator-coverage — Enable coverage instrumentation.
--line-coverage-check — (generate-fsm only) Require runtime line/block counter increments when validating transitions. Auto-enables Verilator --coverage during compile.
--compile-flags <FLAGS> — Extra flags passed to Verilator.
--verilator-jobs <N> — Parallel compile jobs.

`stg identify`

Classify signals in a Verilog module.

stg identify [OPTIONS] [VERILOG_FILE] --type <TYPE> --out <OUT>

[VERILOG_FILE] or --verilog <VERILOG> — (Required) Path to Verilog file.
--module <MODULE> — Module name to identify signals from.
--type <TYPE> — (Required) Design type (combinational, seq_clocked, seq_done).
--out <OUT> — (Required) Output path for signal list (YAML).
--config <CONFIG> — YAML configuration file.
--control-signals [<NAMES>...] — Explicitly define control signals.
--data-signals [<NAMES>...] — Explicitly define data signals.

Output format:

clock_inputs: [clk]
reset_inputs: [rst_n]
done_outputs: []
control_inputs: [op, mode]
data_inputs: [a, b, data_in]
outputs: [result, valid]
reset_active_high: false

`stg parse`

Parse Verilog files and generate a module priority list based on the instantiation hierarchy.

stg parse [VERILOG_FILES...] --out <OUT>

[VERILOG_FILES...] or --verilog <VERILOG> — (Required) Verilog file(s) to parse. Multiple files are concatenated before parsing.
--out <OUT> — (Required) Output path for module list (YAML).

The command:

Parses all modules in the file
Builds a module instantiation graph
Calculates total submodule counts (including nested)
Sorts by priority: fewer dependencies first, then by submodule complexity

Output format:

- name: submodule_a
  submodule_count: 0
  ports:
    - name: in
      direction: input
      width: 8
    - name: out
      direction: output
      width: 8
- name: top_module
  submodule_count: 5
  ports:
    - name: clk
      direction: input
      width: 1
    - name: data_out
      direction: output
      width: 32

`stg compile`

Compile a user-provided testbench with DUT and golden model.

stg compile [OPTIONS] [VERILOG_FILES...] --golden <GOLDEN> --testbench <TESTBENCH> --out-exe <OUT_EXE>

[VERILOG_FILES...] or --verilog <VERILOG> — (Required) DUT Verilog file(s).
--module <MODULE> — DUT module name.
--golden <GOLDEN> — (Required) Golden reference file.
--testbench <TESTBENCH> — (Required) Testbench file (.sv or .cpp).
--out-exe <OUT_EXE> — (Required) Output executable path.
--compile-flags <FLAGS> — Additional compiler flags.
--emplace-module — Embed DUT and golden modules in testbench.
--verilator — Use Verilator for compilation.
--verilator-mpi — Enable MPI support.
--verilator-ignore-warnings — Ignore common Verilator warnings.
--verilator-jobs <N> — Parallel Verilator jobs.
--verilator-coverage — Enable coverage analysis.
--cc — For C++ testbenches.
--sc — For SystemC testbenches.

Runtime Arguments

These arguments are passed to the compiled testbench executable (not to stg):

+STATS_FILE=<PATH> — Custom path for the statistics JSON output. Default: test_stats.json.
+ERROR_LOG_FILE=<PATH> — Custom path for the error log JSON output (when --print-on-error is enabled). Default: error_log.json.
+SEED=<N> — Random seed for reproducible test generation (generate-fsm only).

./tb_exe +STATS_FILE=my_results.json +ERROR_LOG_FILE=my_errors.json

Error Log Format

When --print-on-error is enabled, the error log JSON has the following format:

[
  {
    "id": 0,
    "input": {"a": "0x5", "b": "0x3", "op": "0x2"},
    "internal": {"u_alu.state": "0x1", "u_ctrl.counter": "0xa"}
  },
  {
    "id": 42,
    "input": {"a": "0xff", "b": "0x1", "op": "0x0"},
    "internal": {"u_alu.state": "0x3", "u_ctrl.counter": "0x0"}
  }
]

id — Test case counter (incremented on every output comparison, not just errors)
input — All input port values at the time of the mismatch (hex)
internal — Internal register/signal values using hierarchical dot notation (CC/SC mode only; empty {} in SV mode)