CLI Reference

Usage

moqtap <command> [options]

Global options

Flag	Description
--color <WHEN>	auto (a terminal, and no NO_COLOR), always, or never
--offline	Make no requests to moqtap’s servers; commands that need one fail. Also MOQTAP_OFFLINE=1. inspect still loads its page from moqtap.com

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 object
moqtap peek moqt://relay.example.com data <NAMESPACE> <TRACK> latest

# Record the session
moqtap peek moqt://relay.example.com -o peek.moqtrace

Flag	Description
-j, --json	Output as JSON
--raw	Write the first object’s payload bytes to stdout, for piping. With data only
-k, --insecure	Skip TLS certificate verification
--draft <VERSION>	Force a MoQT draft (07-23) instead of detecting it
-t, --timeout <SECS>	Connection and subscribe timeout (default 10)
--strict	No fallbacks: no transport fallback for quic://, no guessing of catalog names
-v, --verbose	Show transport and draft negotiation, TLS mode, per-message progress and timing
-o, --output <FILE>	Write a .moqtrace recording of the session (- for stdout; the report then goes to stderr)

namespaces with no prefix asks for every namespace. Drafts 07-15 require a prefix.

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

# 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

# Throttle the client's link
moqtap intercept -u moqt://relay.example.com --link 3g

# Impair browser tabs through the extension, recording each session
moqtap intercept --bridge --record-dir captures

The listener accepts both raw QUIC and WebTransport clients and detects each session’s draft.

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)
--draft <VERSION>	Draft to assume for clients on drafts 07-14 until their CLIENT_SETUP arrives (07-23). Clients on 15-23 pick their draft by ALPN
-s, --scenario <FILE> Pro	Degradation scenario to run against the traffic — see below
--link <LINK>	Throttle the client’s link like a browser’s developer tools: offline, 3g or 4g. Free, with no sign-in. Serves one client at a time. Cannot be combined with --scenario
--bridge	Let the browser extension send a tab’s WebTransport sessions through this run, impaired with the tab’s profile, each on its own link. Free, with no sign-in. See Impairing a Browser Tab
--record-dir <DIR>	With --bridge: record each of the extension’s sessions to its own .moqtrace file in DIR
--seed <N>	With --scenario or --bridge: seed for the random network impairments. Defaults to a random value, printed in the run header; pass it back to repeat a run
-o, --output <PATH>	Record the -u relay’s sessions to a .moqtrace file (- for stdout)
--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
-k, --insecure	Skip TLS verification for the upstream relay
--format <FMT>	Output format: text (default) or json
-j, --json	Shorthand for --format 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	Print only errors and warnings; the recording still goes 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.

Running one needs a Pro plan, or Team for a run signed in with MOQTAP_TOKEN. A file with shaping (standing or in a timeline step) or rules needs a Business plan. A refusal names the plan that runs the file.

{
  "$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

Flag	Description
--format <FMT>	text (default) or json
--hex	Show hex dumps of raw bytes and payloads when the recording has them

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)

share <FILE>

Upload a .moqtrace recording to the active organisation’s library, where every member can open it, and print its address. Needs a sign-in. Payload bytes and authorization tokens are removed first unless you keep them.

moqtap share session.moqtrace

# a link anyone holding it can open, for 14 days
moqtap share session.moqtrace --link --expires 14

Flag	Description
--link	Also make a link anyone holding it can open, and print that instead of the library address
--expires <DAYS>	With --link: how long the link works, in days (1-90, default 7)
--include-payloads	Keep object payload bytes in the shared copy
--include-auth	Keep authorization token values in the shared copy

scenario

Write a starter scenario file, check one without running it, or list your scenarios. Writing and checking need no plan; running a scenario with intercept --scenario does. 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

# write one to your scenarios directory, for the browser extension
moqtap scenario new --name bad-wifi --preset wifi

# list the scenarios in your scenarios directory
moqtap scenario list

# 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 --name <NAME>	Write it to your scenarios directory as NAME.json instead, where intercept --bridge offers it to the browser extension as NAME. 1-64 of A-Z a-z 0-9 - _
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
list	List the scenarios in your scenarios directory; its path is the first line 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. It also names the plan the file needs.

intercept --bridge offers each scenario in your scenarios directory to the browser extension by name (Pro plan or above), when the scenario has only a network and network timeline steps.

login, logout, whoami, org

Sign in to moqtap, and pick the organisation that share uploads to and whose plan scenario runs use.

moqtap login
moqtap whoami
moqtap org list
moqtap org switch acme
moqtap logout

On a desktop, login opens the browser and also prints a code for signing in from another device; whichever finishes first wins. Over SSH, with no display, in CI, or with --device, only the code is offered. In CI, a personal access token in MOQTAP_TOKEN takes the place of a sign-in.

Command	Description
login --device	Sign in with a code typed on another device, and open nothing here
login --no-open	Print the sign-in URL instead of opening a browser
login --org <ORGANISATION>	The organisation to make active: its slug, or personal
login --insight	Also ask to read Insight sessions (moqtap insight). Needs a browser on this machine
logout	Sign out, removing the stored sign-in and revoking it on the server
logout --all	Also sign out of any other moqtap server this machine is signed in to
whoami	Show who you are signed in as, your organisations and the active plan
org list	List the organisations this sign-in covers; * marks the active one
org switch <ORGANISATION>	Make an organisation active, by slug, or personal

insight

Read the player sessions moqtap Insight recorded for a project. Needs a sign-in with the insight:read scope (moqtap login --insight), or a personal access token in MOQTAP_TOKEN.

moqtap insight sessions --since 2h --findings
moqtap insight session <ID>
moqtap insight export <ID> -o session.moqtrace
moqtap insight tail

Command	Description
-p, --project <PROJECT>	The project, by id or name. Defaults to MOQTAP_PROJECT, else the active organisation’s only project
-j, --json	Print JSON instead of text, one object per line where there are many
sessions	List sessions, newest start first. Filters include --state live|ended|lost, --findings, --release, --env, --browser, --relay, --tag KEY=VALUE, --since and --until; -n, --limit (default 50) and --cursor page through them
session <ID>	Show one session: what it was, its connections and its problems
export <ID> -o <FILE>	Download one session as a .moqtrace recording (- for stdout). --records writes its records as NDJSON instead; -f replaces the file
tail [ID]	Follow new records as they arrive, for one session or the whole project. --since, --cursor, --once

moqtap insight sessions --help lists every filter.

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. -j, --json prints JSON.

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

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. Your user config.toml: ~/.config/moqtap/config.toml (Linux), ~/Library/Application Support/moqtap/config.toml (macOS) or %APPDATA%\moqtap\config\config.toml (Windows)

moqtap prints where the relay URL came from.

URL schemes

Scheme	Transport
moqt://	Auto-detect (tries QUIC, falls back to WebTransport)
https://	Auto-detect (tries QUIC, falls back to WebTransport)
quic://	QUIC; falls back to WebTransport with a warning, unless --strict
wt://	WebTransport only

Exit codes

Code	Meaning
0	Success
1	Error
2	Invalid command line
3	Not signed in, or the sign-in or MOQTAP_TOKEN was refused: sign in again
4	moqtap’s servers could not be reached, or --offline is set: try again online
5	Not covered by the plan, or by your role in the organisation
6	The TLS handshake with moqtap’s servers was refused
130	Interrupted while the plan was being checked