wavecli

wavecli is a Rust command-line tool for inspecting VCD (Value Change Dump) and FST (Fast Signal Trace) waveform files. It uses wellen directly as the waveform backend and also includes IEEE 754 float conversion helpers.

What It Does

• Reads VCD and FST waveform files
• Prints waveform metadata, signal lists, time ranges, and signal value changes
• Supports substring and regex filtering for signal lookup
• Outputs JSON by default for scripting and automation
• Supports --format text for terminal-friendly output
• Converts between float32, float16, bfloat16 and hex/bin encodings

Installation

Prerequisites

• Rust toolchain with Cargo installed

Build Locally

cargo build

Run directly from the repository during development:

cargo run -- info tests/fixtures/test.vcd

Install to PATH

Install the binary to Cargo's bin directory:

cargo install --path .

After installation, verify it is available:

wavecli --help
wavecli info tests/fixtures/test.vcd

Usage

Output Modes

• Default output: json
• Human-readable output: add --format text
• Errors are written to stderr and return a non-zero exit code

Waveform Commands

Show file metadata

wavecli info ./trace.vcd

List signals

wavecli signals ./trace.vcd --module test.dut --depth 1 --limit 50
wavecli signals ./trace.vcd --pattern Dout --format text
wavecli signals ./trace.vcd --pattern '^test\\.dut\\.' --regex

Show waveform time range

wavecli range ./trace.fst
wavecli range ./trace.vcd --format text

Query signal values

wavecli values ./trace.vcd Dout --start 0 --end 100
wavecli values ./trace.vcd Dout Din --start 0 --end 100 --radix hex
wavecli values ./trace.fst clk --start 0 --end 1000 --limit 20 --format text

Float Conversion Commands

wavecli float hex-to-float 0x40490FDB --type float32
wavecli float float-to-hex 3.14 --type float16 --format text
wavecli float bin-to-float 0100000001001001 --type bfloat16
wavecli float float-to-bin 3.14159 --type float32

Return Data Examples

The following examples are real outputs from the bundled fixtures in tests/fixtures/.

info default JSON output

Command:

wavecli info tests/fixtures/test.vcd

Output:

{
  "file": "tests/fixtures/test.vcd",
  "format": "vcd",
  "signal_count": 28,
  "file_size_bytes": 3018,
  "time_range": {
    "start": 0,
    "end": 196,
    "total": 196
  }
}

signals text output

Command:

wavecli signals tests/fixtures/test.vcd --pattern Dout --format text

Output:

Signals in waveform file (showing 1/1, pattern=Dout):
  test.dut.Dout                            type=reg        size=5

range text output

Command:

wavecli range tests/fixtures/test.vcd --format text

Output:

Time range: 0 to 196 (total: 196 time units)

values default JSON output

Command:

wavecli values tests/fixtures/test.vcd Dout --start 0 --end 30 --limit 2

Output:

{
  "file": "tests/fixtures/test.vcd",
  "format": "vcd",
  "query": {
    "signal_names": [
      "Dout"
    ],
    "start_time": 0,
    "end_time": 30,
    "format": "bin",
    "limit": 2
  },
  "warnings": [],
  "signals": [
    {
      "path": "test.dut.Dout",
      "count": {
        "shown": 2,
        "total": 8
      },
      "changes": [
        {
          "time": 0,
          "value": "bxxxxx"
        },
        {
          "time": 15,
          "value": "b0xxxx"
        }
      ]
    }
  ]
}

float text output

Command:

wavecli float float-to-hex 3.14 --type float16 --format text

Output:

0x4248

Command Summary

• wavecli info <file>
• wavecli signals <file> [--module <path>] [--depth <n>] [--limit <n>] [--pattern <expr>] [--regex]
• wavecli range <file>
• wavecli values <file> <signal>... --start <n> --end <n> [--radix bin|hex|dec] [--limit <n>]
• wavecli float hex-to-float <hex> [--type float32|float16|bfloat16]
• wavecli float float-to-hex <value> [--type float32|float16|bfloat16]
• wavecli float bin-to-float <bin> [--type float32|float16|bfloat16]
• wavecli float float-to-bin <value> [--type float32|float16|bfloat16]

Development

cargo fmt
cargo test