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.
curl -sSf https://moqtap.com/install.sh | sh 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
- Inline URL in command
MOQTAP_RELAYenv var.moqtap.toml(walks up directories)- User config (~/.config/moqtap/)
URL schemes
quic://— native QUICmoqt://— native QUIC (alias)wt://— WebTransporthttps://— WebTransport
Install
macOS / Linux
curl -sSf https://moqtap.com/install.sh | sh Windows (PowerShell)
irm https://moqtap.com/install.ps1 | iex Homebrew
brew install moqtap/tap/moqtap npm
npm install -g moqtap winget
winget install moqtap.moqtap 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 17. 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.
How do I install moqtap?
Quick install: curl -sSf https://moqtap.com/install.sh | sh (macOS/Linux) or irm https://moqtap.com/install.ps1 | iex (Windows). Also via Homebrew, npm (npm install -g moqtap), winget, pre-built binaries from GitHub, or build from source with Cargo.
Is the CLI free?
Yes. The moqtap CLI is free and open source (MIT licensed).