moqtap CLI

Real-time MoQT traffic inspection, debugging, and discovery. Intercept traffic between client and relay, or peek directly into a relay to probe, discover, and inspect — all from the terminal.

Two modes, one tool

Intercept to observe existing sessions passively. Peek to actively query a relay and inspect what it's serving.

Intercept

A transparent proxy that sits between your MoQT client and relay. See control messages, stream lifecycle, objects, datagrams, and errors.

  • Live frame-by-frame decoding
  • Color-coded directional output (C→R / R→C)
  • Session recording to .moqtrace files
  • Filtering by control, data, or session ID
  • JSON output for piping to jq
  • WebTransport support (listen and upstream)

Peek

A lightweight MoQT client that connects directly to a relay to probe its capabilities, discover namespaces and tracks, and retrieve sample data.

  • Relay info & draft version detection
  • Namespace discovery
  • Track enumeration via catalog
  • Data retrieval (latest group or object)
  • Media format detection (JSON, fMP4, LOC, MSF)
  • Pipeable raw output and JSON mode

Intercept mode

MoQT Client ──QUIC──▶ moqtap ──QUIC──▶ MoQT Relay
↓ parses every frame ↓ prints to terminal ↓ writes .moqtrace
moqtap intercept -l 0.0.0.0:4443 -u relay:4443
12:34:56.789 #1 NEW 192.168.1.5:54321 connected
12:34:56.790 #1 C→R SETUP CLIENT_SETUP versions=[4278190087]
12:34:56.791 #1 R→C SETUP SERVER_SETUP version=4278190087
12:34:56.800 #1 C→R CTRL SUBSCRIBE req=1 ns=live track=video
12:34:56.801 #1 R→C CTRL SUBSCRIBE_OK req=1 alias=1
12:34:56.810 #1 R→C UNI subgroup track=1 group=0 subgroup=0
12:34:56.811 #1 R→C OBJ status=Normal len=1234
12:34:56.900 #1 C→R DGRAM track=1 group=1 object=0 payload=56B

Peek mode

Connect directly to a relay. Probe, discover, inspect — with a subcommand hierarchy that's easy to remember.

peek subcommands
moqtap peek # relay info + draft version
moqtap peek namespaces # discover published namespaces
moqtap peek tracks live/stream1 # list tracks in a namespace
moqtap peek data live/stream1 video # fetch latest group
moqtap peek data live/stream1 video latest # fetch latest object
moqtap peek data live/stream1 video latest --raw # pipe raw bytes

Relay URL resolved from inline argument, MOQTAP_RELAY env, or .moqtap.toml config.

Relay configuration

.moqtap.toml
relay = "quic://relay.example.com:4443"
insecure = true # dev only
Priority order
  1. Inline URL in command
  2. MOQTAP_RELAY env var
  3. .moqtap.toml (walks up directories)
  4. User config (~/.config/moqtap/)
URL schemes
  • quic:// — native QUIC
  • moqt:// — native QUIC (alias)
  • wt:// — WebTransport
  • https:// — WebTransport

Frequently asked questions

What is the moqtap CLI?
moqtap is a command-line tool for debugging MoQT deployments. It has two modes: intercept (a transparent proxy that observes traffic between your client and relay) and peek (a lightweight client that connects directly to a relay to probe, discover, and inspect). Together they give you passive observation and active querying in one tool.
What is intercept mode?
Intercept mode runs a transparent proxy between your MoQT client and relay. It forwards all bytes unmodified while parsing every frame inline — printing a structured, timestamped, color-coded view of protocol activity. It never participates in MoQT state management and never alters protocol behavior.
What is peek mode?
Peek mode connects directly to a relay as a minimal MoQT client. It probes relay capabilities, discovers namespaces, enumerates tracks via catalog, and retrieves sample data from individual tracks — with automatic media format detection (JSON, fMP4, LOC, MSF). It connects, queries, and disconnects.
How do I configure the relay URL?
moqtap resolves the relay from: (1) inline URL in the command, (2) MOQTAP_RELAY environment variable, (3) .moqtap.toml in the current directory or any parent, (4) user-level config at ~/.config/moqtap/config.toml. moqtap prints where the URL was loaded from so there's no ambiguity.
Which MoQT draft versions are supported?
moqtap supports drafts 07 through 20. In peek mode, it auto-detects the draft by offering all supported versions in CLIENT_SETUP and reading the relay's response. You can force a specific draft with --draft.
Is the CLI free?
The moqtap CLI is free to download and use, with paid tiers for scenario features. It is not open source — the source is proprietary. The MoQT protocol libraries it is built on are open source (MIT) and published to crates.io.

See inside the protocol

Every command and flag is in the CLI reference. For MoQT over WebTransport in a page, the WebTransport Inspector brings the same decoding to your browser's DevTools.

CLI reference WebTransport Inspector