CLI reference
The Nearglass command line tool, every subcommand and flag with its default.
Taken from the nearglass --help output of the 0.1.0-rc.1 Linux x86_64 build,
cross-checked against crates/nearglass-cli, crates/nearglass-ingest/src/cli.rs and
crates/nearglass-token/src/cli.rs on commit 79b96c7 of the SDK repository.
nearglass <command> --help always lists the flags of the build you have.
nearglass <command> [flags]
publish One stream to a relay: a file, an SRT or RTMP encoder, or a camera with --encoder mpp
ingest The ingest gateway: RTMP(S), SRT and WHIP in, MoQ out, many streams
token Issuer keys and role tokens, for a self-hosted relaynearglass --version prints the version. -h and --help work on every command.
| Command | Use it to | Guides |
|---|---|---|
publish | send one stream from a file, one encoder or a camera, with nothing else to run | OBS and SRT, Quickstart |
ingest | run the gateway that takes RTMP, RTMPS, SRT and WHIP from many encoders | Configuration |
token | make an issuer key pair and mint tokens for a relay you run | Viewer tokens |
Environment
| Variable | What |
|---|---|
RUST_LOG | log filter for publish and ingest. Default info,quinn=warn. Logs go to stderr. token logs nothing |
TLS_DISABLE_VERIFY | the same as --tls-disable-verify, for publish and ingest |
Every flag value is a plain argument. Keys are never flags: they are read
from files (--secret-key-file, --control-api-key-file, --token-file), so
they stay out of the process list and shell history.
Nearglass publish
Sends one stream to a relay. Give where it goes (one of three ways) and what goes (exactly one of four).
nearglass publish --api https://api.nearglass.com --secret-key-file sk.txt --stream st_... --file film.ts --loop
nearglass publish --descriptor pub.json --srt-listen 0.0.0.0:9000
nearglass publish --relay https://relay.nearglass.com/ --namespace warp/cam --token-file pub.tok --rtmp-listen 0.0.0.0:1935Ctrl-C or SIGTERM ends the stream cleanly, so the relay frees the stream's name at once.
Where it goes
| Flag | Default | What |
|---|---|---|
--api <URL> | none | the control API, for example https://api.nearglass.com. The API names the relays and the namespace and mints a publisher token for every connection. Needs --secret-key-file and --stream |
--secret-key-file <FILE> | none | a file holding your secret key (sk_...) |
--stream <ID> | none | the stream's id (st_...) |
--token-ttl <SECONDS> | 3600 | lifetime of each publisher token asked of the API |
--descriptor <FILE> | none | a file holding the API's answer to POST /v1/streams/{id}/publisher-tokens. Cannot be combined with --api |
--relay <URL> | none | a relay, by hand (self-hosting). Repeat for a failover list. Needs --namespace. Cannot be combined with --api or --descriptor |
--namespace <NAME> | none | the broadcast namespace, / separated (with --relay) |
--token-file <FILE> | none | a publisher token file, base64url (with --relay; make one with nearglass token mint --role publisher) |
With --api or --descriptor, a self-signed relay certificate named by the
API (relay_cert_sha256) is pinned, unless you give --tls-root or
--tls-disable-verify.
What goes
Give exactly one of --file, --srt-listen, --rtmp-listen and --encoder.
| Flag | Default | What |
|---|---|---|
--file <FILE> | none | an H.264 file to replay in real time: MPEG-TS, or Annex B (paced by its SPS, or --fps when it has no timing) |
--loop | off | replay the file again and again. Needs --file |
--srt-listen <ADDR> | none | take one SRT encoder on this address (MPEG-TS with H.264). Prints the address to send to |
--rtmp-listen <ADDR> | none | take one RTMP encoder on this address. Prints the address and stream key |
--stream-key <KEY> | a new one, printed | the stream key the encoder must send, for --srt-listen and --rtmp-listen |
--srt-latency-ms <MS> | 120 | SRT latency on our side, in milliseconds |
--encoder <NAME> | none | capture a camera and encode it in hardware. The only value is mpp (Rockchip RK3588 and RK3576, a V4L2 camera on the VEPU) |
--encoder mpp exists only in the Linux arm64 build with Rockchip MPP; any
other build stops with "this build has no hardware encoder".
The file should be H.264 with a keyframe about every second and no B-frames. It is not decoded or re-encoded.
Camera and file settings
Used with --encoder, except --fps and --seconds, which also apply to
the other sources as noted.
| Flag | Default | What |
|---|---|---|
--track <NAME> | video | video track name |
--device <PATH> | /dev/video11 | V4L2 capture device (multiplanar, NV12 or NV16) |
--format <FORMAT> | NV12 | pixel format: NV12 or NV16 |
--size <WxH> | 1920x1080 | requested capture size. The driver may pick another |
--fps <N> | 60 | frames per second. With --file: the rate for an Annex B file with no timing in its SPS (an MPEG-TS file carries its own) |
--bitrate <BPS> | 8000000 | target bitrate in bits per second, constant bitrate |
--gop <FRAMES> | one a second | frames between IDR frames, each a MoQ group |
--crop <MODE> | full | part of the sensor: full (the whole view, scaled), center (1:1, narrower) or driver |
--profile <PROFILE> | high | H.264 profile: baseline, main or high |
--seconds <N> | 0 | stop after this long. 0 runs until stopped |
TLS flags
publish and ingest share these.
| Flag | Default | What |
|---|---|---|
--tls-root <FILE> | system roots | trust this PEM root. Repeat for several. For a relay with a private CA |
--tls-disable-verify | off | skip certificate checks. Local development only. Also TLS_DISABLE_VERIFY |
--tls-cert <FILE> | none | a PEM certificate chain. Repeat for several; needs a --tls-key for each (the counts must match) |
--tls-key <FILE> | none | the PEM private key for a --tls-cert |
--tls-cert and --tls-key come from the transport library that the relay
shares. Both commands connect to the relay as a client, and in the code these
two flags are only loaded and checked for matching counts; they do not change
that connection. --tls-root uses the first certificate in each file.
Nearglass ingest
The ingest gateway. It takes video from many encoders over RTMP, RTMPS, SRT and WHIP, and sends it to the relay as MoQ. Give where the stream keys come from (a keys file, or the control API) and at least one listener.
nearglass ingest --relay https://relay.nearglass.com/ --control-api https://api.nearglass.com/ \
--control-api-key-file ingest.key --rtmp 0.0.0.0:1935 --srt 0.0.0.0:9000The gateway needs --relay, exactly one of --keys and --control-api, and
at least one of --rtmp, --rtmps, --srt, --whip and --framed. It logs
a JSON line to stderr every 10 s with frame counts, drops and its own time
per frame.
Relay and keys
| Flag | Default | What |
|---|---|---|
--relay <URL> | required | the relay's URL. Repeat for a failover list |
--keys <FILE> | none | the stream keys file (format) |
--token-file <FILE> | none | a publisher token for the streams' namespaces. Only with --keys |
--control-api <URL> | none | the control API, in place of --keys and --token-file: stream keys and each stream's publisher token come from it |
--control-api-key-file <FILE> | none | the gateway's ingest key (ik_...), in a file. Needed with --control-api |
Listeners
| Flag | Default | What |
|---|---|---|
--rtmp <ADDR> | off | RTMP listen address |
--rtmps <ADDR> | off | RTMPS (RTMP over TLS) listen address. Needs --rtmps-cert and --rtmps-key |
--rtmps-cert <FILE> | none | the gateway's TLS certificate chain for RTMPS (PEM) |
--rtmps-key <FILE> | none | its private key (PEM) |
--srt <ADDR> | off | SRT listen address (UDP) |
--srt-latency-ms <MS> | 120 | our side of the SRT latency. The session uses the larger of the two sides' values; four times the round trip is the guidance |
--srt-quiet-ms <MS> | 0 | SRT: complete an unstuffed frame after its stream has been quiet this long. 0 is off |
--whip <ADDR> | off | WHIP listen address (HTTPS; plain HTTP only on loopback, for tests). Needs --whip-ip |
--whip-ip <IP> | none | the IP encoders reach this gateway at (the WHIP ICE candidate) |
--whip-bind-ip <IP> | 0.0.0.0 | local IP the WHIP sessions' UDP sockets bind to |
--whip-cert <FILE> | --rtmps-cert | WHIP's TLS certificate chain (PEM) |
--whip-key <FILE> | --rtmps-key | its private key (PEM) |
--framed <ADDR> | off | framed TCP listen address, for the warp-pub tool's framed output (tests and LAN) |
A WHIP address off loopback without a certificate is refused: the stream key
travels in the Authorization header and must not cross the network in
clear.
Output
| Flag | Default | What |
|---|---|---|
--hls-origin <URL> | none | the LL-HLS packager on this host, as RTMP with its app (for example rtmp://127.0.0.1:1937/hls). Every stream also goes there as <app>/<stream name> |
--uplink-stale-ms <MS> | 1000 | frames older than this when written are dropped |
--aac-opus-frame-ms <MS> | 20 | Opus packet length for audio transcoded from AAC: 10 or 20 |
The TLS flags above (--tls-root, --tls-disable-verify, --tls-cert,
--tls-key) apply to the gateway's connection to the relay.
Nearglass ingest keygen
Makes a stream key for a keys file. Prints the key (give it to the customer once) and the keys-file entry, which holds only the key's hash.
nearglass ingest keygen --name studio-a --namespace warp/ingest/studio-a| Flag | Default | What |
|---|---|---|
--name <NAME> | required | the stream's name, for logs and status |
--namespace <NAME> | required | the broadcast namespace, / separated |
--protocols <LIST> | rtmp,rtmps,srt,whip | comma separated protocols the key may use |
Nearglass token
Issuer keys and role tokens for a relay you run yourself. The managed service does this for you through the control API. Tokens use ES256.
Nearglass token keygen
Makes a new issuer key pair. It refuses to overwrite a file that exists. The private key is created readable by its owner only on Unix. Keep it out of git and logs: the relay needs only the public key.
| Flag | Default | What |
|---|---|---|
--private <FILE> | required | where to write the private key (PKCS#8 PEM) |
--public <FILE> | required | where to write the public key |
Nearglass token mint
Mints one token and prints it on stdout.
nearglass token mint --key issuer.key.pem --role viewer --namespace warp/excavator-1 --ttl 600
nearglass token mint --key issuer.key.pem --role controller --turn t42 --namespace warp/excavator-1 --ttl 90 --token-id turn:t42| Flag | Default | What |
|---|---|---|
--key <FILE> | required | the issuer's private key (PKCS#8 PEM) |
--role <ROLE> | required | publisher, viewer or controller |
--namespace <NAME> | required | the broadcast namespace, / separated |
--turn <ID> | none | the turn id. Required for controller, refused for the other roles |
--ttl <SECONDS> | required | lifetime in seconds, at most 7 days |
--issuer <NAME> | nearglass-token | the issuer claim. Must match the relay's scope config |
--audience <NAME> | nearglass-relay | the audience claim. Must match the relay's scope config |
--subject <NAME> | nearglass | the sub claim: who the token is for |
--token-id <ID> | none | the token id (cti). The relay allows one live session per id and can close sessions by it. random makes a fresh one |
--format <FORMAT> | base64url | base64url or hex |
Exit status
A command that fails prints the error on stderr and exits non-zero. A flag used wrongly (a missing required flag, two flags that cannot be combined) exits with status 2 and a usage message.