# 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.

```bash
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.

```bash
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.

```bash
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:**
```yaml
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.

```bash
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:
1. Parses all modules in the file
2. Builds a module instantiation graph
3. Calculates total submodule counts (including nested)
4. Sorts by priority: fewer dependencies first, then by submodule complexity

**Output format:**
```yaml
- 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.

```bash
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).

```bash
./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:

```json
[
  {
    "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)