CLI Reference

Usage

moqtap <command> [options]

Global options

Flag	Description
--json	Output as JSON (where supported)
--insecure	Accept invalid TLS certificates
--draft <VERSION>	Force a specific MoQT draft version
--timeout <MS>	Connection timeout in milliseconds
--strict	Reject non-conformant messages
-v, --verbose	Increase log verbosity
--color <WHEN>	auto (a terminal, and no NO_COLOR), always, or never

Commands

peek [URL]

Lightweight MoQT client for probing relays. Auto-detects transport (QUIC or WebTransport) and draft version.

# Show relay info and draft version
moqtap peek moqt://relay.example.com

# Discover published namespaces
moqtap peek moqt://relay.example.com namespaces

# List tracks in a namespace
moqtap peek moqt://relay.example.com tracks <NAMESPACE>

# Fetch data from a track
moqtap peek moqt://relay.example.com data <NAMESPACE> <TRACK>

# Fetch only the latest group
moqtap peek moqt://relay.example.com data <NAMESPACE> <TRACK> latest

intercept -u <RELAY>

Transparent intercepting proxy. Sits between a MoQT client and an upstream relay, forwarding traffic unmodified while parsing every frame inline.

# QUIC listener (default 127.0.0.1:4443) proxying to upstream relay
moqtap intercept -u moqt://relay.example.com

# WebTransport listener
moqtap intercept -u moqt://relay.example.com --listen-wt

# Record session to a .moqtrace file
moqtap intercept -u moqt://relay.example.com --output session.moqtrace

# Filter to control messages only
moqtap intercept -u moqt://relay.example.com --filter ctrl

# JSON output
moqtap intercept -u moqt://relay.example.com --format json

# Run a degradation scenario against the traffic
moqtap intercept -u moqt://relay.example.com --scenario bad-wifi.json

Flag	Description
-u, --upstream <URL>	Upstream relay URL. Falls back to MOQTAP_RELAY or .moqtap.toml
-l, --listen <ADDR>	Address to listen on for client connections (default 127.0.0.1:4443)
-s, --scenario <FILE> Pro	Degradation scenario to run against the traffic — see below
--seed <N> Pro	Seed for every impairment the scenario draws at random. Defaults to a fresh value each run
--listen-wt	Listen for WebTransport connections instead of QUIC
--output <PATH>	Save session to a .moqtrace file
--filter <TYPE>	Filter output: ctrl (control messages only), data (data streams only)
--session <ID>	Filter to a specific session ID
--cert <PATH>	Custom TLS certificate
--key <PATH>	Custom TLS private key
--format <FMT>	Output format: text (default) or json
--upstream-wt <URL>	Use WebTransport for the upstream connection
--ca-cert <PATH>	Custom CA certificate for the upstream relay. Repeatable
-t, --timeout <SECS>	Upstream connection timeout (default 10)
-q, --quiet	Suppress terminal output; write only to --output

Scenario files Pro

A scenario is a JSON document describing a whole run — the network underneath the session, QUIC transport parameters per leg, egress shaping, rules that act on individual objects, and a timeline that changes any of it part-way through. It is read and checked before the proxy binds: an unknown key, or a version this build does not read, is refused by name rather than partly applied.

{
  "$schema": "https://moqtap.com/schema/scenario/v1.json",
  "version": 1,
  "network": { "preset": "lossy-edge" }
}

See Scenario Files for the format key by key, the seven network presets, and the schema URL that makes one of these autocomplete in an editor.

trace <FILE>

Replay and inspect recorded .moqtrace files.

# Replay a trace file
moqtap trace session.moqtrace

# JSON output
moqtap trace session.moqtrace --format json

# Hex dump mode
moqtap trace session.moqtrace --hex

inspect <FILE>

Open a .moqtrace recording in the browser. Serves the file from a loopback address and frames the moqtrace Inspector against it; the recording is not uploaded.

moqtap inspect session.moqtrace

# print the URL instead of launching a browser
moqtap inspect session.moqtrace --no-open

Flag	Description
--no-open	Print the URL and do not launch a browser
--port <PORT>	Port for the local server (default: whatever the OS hands out)
--inspector-url <URL>	The inspector page to frame. Must be https, or http on loopback

scenario Pro

Write a starter scenario file, or check one without running it. The format itself is documented in Scenario Files.

# write a starter to edit from
moqtap scenario new
moqtap scenario new --preset lossy-edge --full harness.json

# load a file and say what it would do, without starting a proxy
moqtap scenario check harness.json

# check a whole directory, non-zero exit if any file is refused
moqtap scenario check examples/scenarios/*.json

# print the schema this build reads
moqtap scenario schema > v1.json

Flag	Description
new [PATH]	Write a starter scenario. Defaults to ./scenario.json
new --preset <NAME>	Which of the seven named networks the starter puts the path on (default lte)
new --full	Also write one rule and one timeline step, so the shape of both is in front of you
new -f, --force	Overwrite an existing file
check <FILE>...	Check each file in turn; non-zero exit if any was refused
check -q, --quiet	Say nothing about a file that checked out. Refusals are still printed
schema	Print the JSON Schema scenario files are written against, to stdout

check runs everything intercept runs before it accepts a connection — the schema, every rule, and every network profile the file would arm, including the ones that only appear on the timeline — and nothing that needs traffic.

init

Write a .moqtap.toml config file in the current directory. Prompts for the relay URL when stdin is a terminal and --relay was not given.

moqtap init --relay quic://relay.example.com:4443

Flag	Description
--relay <URL>	Relay URL to write into the config
--draft <VERSION>	Force a specific MoQT draft version
--insecure	Skip TLS certificate verification by default
-o, --output <PATH>	Where to write it (default ./.moqtap.toml)
-f, --force	Overwrite an existing config file

cert

Show the TLS certificates used for WebTransport interception, or regenerate them.

moqtap cert
moqtap cert reset

completions <SHELL>

Generate shell completions.

moqtap completions bash
moqtap completions zsh
moqtap completions fish
moqtap completions powershell
moqtap completions elvish

doc

Generate this reference from the binary itself.

moqtap doc markdown          # Markdown to stdout
moqtap doc man --out man     # man pages to a directory

Configuration

moqtap resolves configuration in this order (first match wins):

1. Inline URL argument
2. MOQTAP_RELAY environment variable
3. .moqtap.toml in the current directory or any parent (walks up like .gitignore)
4. ~/.config/moqtap/config.toml (Linux/macOS) or %APPDATA%\moqtap\config.toml (Windows)

URL schemes

Scheme	Transport
moqt://	Auto-detect (tries QUIC, falls back to WebTransport)
https://	Auto-detect (tries QUIC, falls back to WebTransport)
quic://	QUIC only
wt://	WebTransport only

Exit codes

Code	Meaning
0	Success
1	Error
2	Connection error