---
name: wavecli-waveform
description: Use this skill when the user asks to read, inspect, understand, explain, search, summarize, or query VCD/FST waveform files, signal hierarchies, time ranges, value changes, or IEEE 754 float encodings with the local wavecli tool. Trigger on requests about waveform understanding, signal lookup, timing/value inspection, VCD/FST analysis, or converting float32/float16/bfloat16 values.
---

# wavecli waveform skill

Use this skill when the task is about **reading or understanding waveforms**.
Typical triggers:

- "看一下这个 vcd/fst 波形"
- "帮我理解这个信号怎么变化"
- "列出模块里的 signals"
- "查询某个时间范围内的值"
- "解释这个波形文件里发生了什么"
- "把 hex/bin 转成 float32/float16/bfloat16"
- "用 wavecli 分析 waveform"

This skill is designed to work for both **Codex** and **Claude** style agents.
The core assumption is simple: if you have shell access, run `wavecli` commands and inspect the returned JSON or text.

## What `wavecli` does

`wavecli` is a local CLI for:

- inspecting `VCD` and `FST` waveform files
- listing hierarchical signals
- getting waveform time ranges
- querying signal value changes in a time window
- converting IEEE 754 values between float / hex / binary

Default output is **JSON**.
Use `--format text` when a human-readable terminal view is better.

## Installation

You should be able to install and use the CLI from this file alone.

### Prerequisites

- Rust toolchain with Cargo installed
- a local checkout of the `wavecli` repository

### Install to local PATH

From the repository root:

```bash
cargo install --path .
```

This installs the binary to Cargo's bin directory, usually:

```bash
$HOME/.cargo/bin/wavecli
```

### If `wavecli` is not found

Temporarily add Cargo bin to `PATH`:

```bash
export PATH="$HOME/.cargo/bin:$PATH"
```

Persist it in Bash:

```bash
echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
```

### Development use without installing

From the repository root:

```bash
cargo run -- --help
cargo run -- info tests/fixtures/test.vcd
```

## Basic command map

### 1. File metadata

```bash
wavecli info <file>
```

Example:

```bash
wavecli info ./trace.vcd
```

Returns JSON like:

```json
{
  "file": "./trace.vcd",
  "format": "vcd",
  "signal_count": 28,
  "file_size_bytes": 3018,
  "time_range": {
    "start": 0,
    "end": 196,
    "total": 196
  }
}
```

### 2. List signals

```bash
wavecli signals <file> [--module <path>] [--depth <n>] [--limit <n>] [--pattern <expr>] [--regex]
```

Examples:

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

### 3. Get time range

```bash
wavecli range <file>
```

Example:

```bash
wavecli range ./trace.fst --format text
```

### 4. Query signal values

```bash
wavecli values <file> <signal>... --start <n> --end <n> [--radix bin|hex|dec] [--limit <n>]
```

Examples:

```bash
wavecli values ./trace.vcd Dout --start 0 --end 30
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
```

Typical JSON result:

```json
{
  "file": "./trace.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" }
      ]
    }
  ]
}
```

### 5. Float conversions

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

Examples:

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

## Recommended workflow for agents

When the user asks to understand a waveform, prefer this order:

1. Run `wavecli info <file>` to confirm format, signal count, and time range.
2. Run `wavecli signals <file>` with a narrow `--pattern` or `--module`.
3. Run `wavecli values <file> ... --start ... --end ...` on the specific signals.
4. Summarize the behavior in plain language.

Do **not** dump huge waveforms at once if a narrower query will answer the question.

## Output strategy

- Use default JSON when you want structured downstream reasoning.
- Use `--format text` when you want to show a concise terminal view to the user.
- Errors are printed to `stderr` and return a non-zero exit code.

## Claude / Codex compatibility

This skill is intentionally tool-agnostic.

### In Codex

Use shell commands directly, for example:

```bash
wavecli info /path/to/file.vcd
wavecli signals /path/to/file.vcd --pattern clk
wavecli values /path/to/file.vcd clk --start 0 --end 100
```

### In Claude

If terminal or local command execution is available, run the same `wavecli` commands.
If a terminal tool is not available, ask the user to run the command and paste the JSON/text output.

Suggested fallback wording:

- "Please run `wavecli info <file>` and paste the JSON output."
- "Please run `wavecli signals <file> --pattern <name>` and share the result."
- "Please run `wavecli values <file> <signal> --start <n> --end <n>` and paste the output."

## Good defaults

- start with `info`
- prefer JSON unless a text table is easier to read
- use `--pattern` before broad signal listing
- limit value queries to a bounded time window
- use `--limit` to avoid oversized outputs

## Troubleshooting

### `command not found: wavecli`

Install it:

```bash
cargo install --path .
```

Or call it from Cargo directly:

```bash
cargo run -- info <file>
```

### Unsupported file format

Current intended public scope is `VCD` and `FST`.
If the file is another format, convert it first or confirm it is really a VCD/FST file.

### No signals found

Try one of these:

```bash
wavecli signals <file> --limit 0
wavecli signals <file> --pattern <partial-name>
wavecli signals <file> --module <scope>
```

### Too much output

Narrow the query:

```bash
wavecli signals <file> --pattern <name> --limit 20
wavecli values <file> <signal> --start 100 --end 200 --limit 20
```

## Minimal examples to remember

```bash
wavecli info file.vcd
wavecli signals file.vcd --pattern clk
wavecli range file.fst
wavecli values file.vcd clk --start 0 --end 100
wavecli float float-to-hex 3.14 --type float16
```