---
id: reference/command-model
title: Command Model Contract
summary: Stable semantics for waveform inputs, time values, names, output modes, bounded output, and ordering.
section: reference
see_also:
- reference/machine-output
- commands/overview
- commands/skill
---
# Command Model Contract
This document is normative for the cross-cutting semantics shared across the shipped waveform-inspection commands. It intentionally avoids repeating exact flag lists and defaults. Layered help, the visible `help` subcommand, the `docs` command family, the top-level `skill` helper command, embedded topic rules, and docs export/search behavior are governed by `commands/docs` and `commands/skill` instead. For the precise command-line surface in an installed build, follow `wavepeek -h`, `wavepeek --help`, `wavepeek help <command-path...>`, `wavepeek docs --help`, and `wavepeek skill --help`.
## 1. Waveform Input Model
wavepeek is a stateless CLI. Each invocation opens one waveform dump when needed, executes one command, writes its result, and exits.
All waveform-inspection commands require `--waves <FILE>` and operate on a single dump per invocation. Non-waveform surfaces such as `schema`, `help`, `docs`, and `skill` are outside this document's scope and follow `commands/docs`, `commands/skill`, plus the exact CLI/help surface.
The supported dump formats are VCD (Value Change Dump) and FST (Fast Signal Trace).
## 2. Time Tokens and Normalization
Every explicit time token requires an integer magnitude plus a unit suffix. The accepted suffixes are `zs`, `as`, `fs`, `ps`, `ns`, `us`, `ms`, and `s`. Bare numbers such as `100` are invalid.
When wavepeek parses a time token, it converts that value into the dump's native `time_unit`. All observable timestamps are then rendered back as normalized integer counts in that dump unit. If a requested time cannot be represented exactly at dump precision, the command fails instead of silently rounding.
These rules apply to point sampling (`--at`) and to window boundaries (`--from`, `--to`).
## 3. Time Windows and Inclusive Boundaries
Commands that accept `--from` and `--to` interpret them as an inclusive time window.
- `--from` plus `--to` means the closed interval from the start token through the end token.
- `--from` without `--to` means from that timestamp through the end of the dump.
- `--to` without `--from` means from the start of the dump through that timestamp.
- Omitting both means the entire dump.
Commands without time-window flags do not participate in this model. `value` uses the same time-token rules but samples one exact timestamp through `--at`.
## 4. Naming, Scopes, and Resolution
wavepeek uses canonical dump-derived paths as the stable naming model. Without `--scope`, signal-like names are interpreted as canonical full paths.
Commands that support `--scope` allow shorter names relative to the selected scope. In those scoped modes, name resolution happens inside the declared scope rather than against the full hierarchy root. Human-readable output may render short or relative names for compactness, but machine-readable output keeps canonical paths where the contract defines them.
The commands that depend on this model are:
- `signal`, which requires an exact scope path and can optionally traverse child scopes.
- `value`, which accepts either canonical paths or scope-relative signal names depending on whether `--scope` is set.
- `change` and `property`, which apply the same scope-relative resolution model to sampled signals, trigger names, and expression references.
Unresolved names are errors. In scoped `change` and `property` mode, canonical full-path tokens are rejected in places where the command contract expects names to stay relative to the selected scope, preventing mixed-resolution queries.
## 5. Human-Readable and Machine-Readable Modes
Waveform commands default to human-readable output. Machine-readable output is enabled explicitly with `--json`.
Human-readable output is optimized for compact operator use and may vary when formatting improvements are made. Machine-readable output is strict and versioned through the JSON schema contract described in `machine-output` and exposed by `wavepeek schema`.
`schema` is a special case: it always prints one JSON Schema document to stdout and never wraps that payload in the normal command envelope. The non-waveform `docs` command family and the human-only `skill` command have their own help and narrative-doc semantics in `commands/docs` and `commands/skill`; only `docs topics --json` and `docs search --json` participate in the stable JSON envelope.
## 6. Bounded Output and Warning Semantics
wavepeek is designed to avoid flooding terminals and LLM context windows. Commands therefore keep output bounded by default through one or more of these mechanisms:
- explicit count limits such as `--max`,
- depth limits such as `--max-depth`,
- the finite size of the requested input set, or
- an inherently finite command shape such as `schema`.
When a command truncates output because of an active limit, it emits a warning. When a command supports disabling a limit explicitly, that opt-out also emits a warning so automation can tell the boundedness contract changed on purpose.
## 7. Deterministic Ordering
Deterministic output is a repository-wide design requirement. Given identical input data and identical command arguments, wavepeek must emit results in a stable order.
The main ordering rules are:
- `scope` traverses hierarchy in pre-order depth-first order with lexicographic child ordering.
- Recursive `signal` queries walk scopes in that same stable order and sort signals deterministically within each visited scope.
- `value` preserves the request order from `--signals`.
- `change` and `property` emit rows in ascending normalized timestamp order.
- When multiple warnings apply, their order is deterministic for a given command contract.
These ordering guarantees are part of the command model because automation depends on predictable, replayable output.