Skip to main content
moq-cli is a command-line tool for publishing media to Media over QUIC relays from various sources and formats.

​
Overview

moq-cli makes it easy to:
  • Publish media files to MoQ relays
  • Stream from cameras and microphones
  • Convert existing media formats (fMP4, HLS) to MoQ
  • Test and debug MoQ broadcasts

​
Installation

cargo install moq-cli
Or build from source: 
git clone https://github.com/moq-dev/moq
cd moq/rs/moq-cli
cargo build --release
The binary is installed as moq (not moq-cli).

​
Quick Start

Publish a video file to a relay: 
moq publish https://relay.example.com/my-app/stream input.mp4

​
Commands

​
publish

Publish media to a relay: 
moq publish [OPTIONS] <URL> <INPUT>
​
URL
string
required
Relay URL including the broadcast pathExamples:
  • https://localhost:4443/anon/my-stream
  • https://cdn.moq.dev/anon/test
​
INPUT
string
required
Input source (file path, URL, or device)Examples:
  • video.mp4 - Local file
  • http://example.com/video.mp4 - HTTP URL
  • https://example.com/playlist.m3u8 - HLS stream
  • - - Stdin

​
Options

​
--format
string
Input format overrideSupported formats:
  • mp4 - MP4/fMP4 file
  • hls - HLS playlist
  • auto (default) - Auto-detect from extension
​
--jwt
string
JWT authentication tokenExample:
moq publish --jwt <token> <url> <input>
​
--insecure
Skip TLS certificate verification (development only)
​
--backend
string
QUIC backend to useOptions:
  • quinn (default)
  • quiche
  • iroh

​
Examples

​
Publish Local MP4 File

moq publish https://localhost:4443/anon/video video.mp4

​
Publish from HTTP URL

moq publish https://localhost:4443/anon/remote \
  http://example.com/video.mp4

​
Publish HLS Stream

moq publish https://localhost:4443/anon/live \
  https://example.com/live/playlist.m3u8

​
Publish with Authentication

Generate a token and publish: 
# Generate token
TOKEN=$(moq-token --key dev/root.jwk --root my-app)

# Publish with token
moq publish --jwt $TOKEN \
  https://relay.example.com/my-app/stream \
  video.mp4

​
Publish to Localhost (Development)

# Use --insecure for self-signed certificates
moq publish --insecure \
  https://localhost:4443/anon/test \
  video.mp4

​
Publish via Iroh P2P

moq publish --backend iroh \
  iroh://<ENDPOINT_ID>/anon/test \
  video.mp4

​
Publish from Stdin

Pipe media from another process: 
ffmpeg -i input.mov -f mp4 -movflags frag_keyframe+empty_moov - | \
  moq publish https://localhost:4443/anon/stream -

​
Input Formats

moq-cli supports various input formats through the moq-mux library:

​
MP4 / fMP4

Fragmented MP4 files are recommended for streaming: 
# Create fragmented MP4 with ffmpeg
ffmpeg -i input.mov \
  -f mp4 \
  -movflags frag_keyframe+empty_moov+default_base_moof \
  output.mp4

# Publish it
moq publish https://relay.example.com/stream output.mp4

​
HLS

Publish from HLS playlists (live or VOD): 
moq publish https://relay.example.com/stream \
  https://example.com/live/playlist.m3u8
The CLI will:
  1. Download the playlist
  2. Parse segments
  3. Convert to MoQ format
  4. Publish to relay

​
Raw Streams

For custom formats, pipe through stdin: 
cat video.h264 | moq publish <url> --format h264 -

​
Configuration

moq-cli uses the same configuration as moq-native:
  • RUST_LOG - Set log level (debug, info, warn, error)
  • MOQ_BACKEND - Default QUIC backend
# Enable debug logging
RUST_LOG=debug moq publish <url> <input>

# Use specific backend
MOQ_BACKEND=quinn moq publish <url> <input>

​
Features

moq-cli supports different QUIC backends: 
# Default: Quinn + Iroh + WebSocket
cargo install moq-cli

# Quinn only
cargo install moq-cli --no-default-features --features quinn

# With all backends
cargo install moq-cli --features iroh,quinn,quiche,websocket

​
Scripting

Use moq-cli in shell scripts: 
#!/bin/bash

RELAY="https://relay.example.com"
TOKEN=$(moq-token --key key.jwk --root my-app)

# Publish multiple files
for file in videos/*.mp4; do
  name=$(basename "$file" .mp4)
  moq publish --jwt "$TOKEN" "$RELAY/my-app/$name" "$file"
done

​
Error Handling

moq-cli returns appropriate exit codes:
  • 0 - Success
  • 1 - General error
  • 2 - Connection error
  • 3 - Authentication error
Check errors in scripts: 
if moq publish <url> <input>; then
  echo "Published successfully"
else
  echo "Failed to publish" >&2
  exit 1
fi

​
Troubleshooting

​
Connection Refused

Error: connection refused
Ensure the relay is running: 
# Check if relay is listening
netstat -an | grep 4443

​
Certificate Verification Failed

Error: invalid certificate
For development with self-signed certs: 
moq publish --insecure <url> <input>
For production, ensure valid TLS certificate.

​
Authentication Failed

Error: unauthorized
Check your token: 
# Verify token works
moq-token --verify --key key.jwk --token <token>

​
Format Not Supported

Error: unsupported format
Convert to fragmented MP4: 
ffmpeg -i input.mov -f mp4 -movflags frag_keyframe output.mp4

​
Resources

​
Next Steps

moq-mux

Learn about media format conversion

moq-relay

Set up your own relay

moq-token

Generate authentication tokens

Authentication

Learn about JWT tokens

Build docs developers (and LLMs) love

Get started for freeTalk to us