NNGCAT(1)

📦
version 1.12.3 · 8 versions
, in fedora 43, fedora 44

🌸 NNGCAT(1) — the NNG Reference Manual, but make it a group chat 🎀

okay bestie, sit DOWN. this is nngcat, and it's the little command-line bestie that gives you access to the Scalability Protocols without you having to write a single line of C. slay.

✨ NAME ✨

nngcat — command line access to Scalability Protocols. yes that's it, that's the whole name, she's simple and she's iconic 💅

🦋 SYNOPSIS 🦋

nngcat --help

nngcat --version

nngcat [OPTION]...

💖 DESCRIPTION 💖

So. The nngcat utility is the way you get command line access to the Scalability Protocols, fr fr. What that means in practice: you can write shell scripts that talk to other peers in a Scalability Protocols topology — sending messages AND receiving messages — no compilation required. it's giving "I just want to vibe with my network from bash" and honestly? valid. 🫶

🌈 OPTIONS 🌈

The possible values for OPTION are described below. buckle up, there's a lot, but I got you.

💡 Tip: The nngcat utility accepts shortened versions of these options, as long as the supplied option is unambiguous. For example --comp can be used in lieu of --compat, but --re may not be used for anything because it could mean any of --req, --rep, or --respondent. so like, be specific, bestie 😭

When using the long form of an option (names prefixed with with --), if the option takes a value then the value may be supplied by appending the option with an equals sign and the value (e.g. --subscribe=times), by appending the option with a colon and the value (e.g. --subscribe:tribune) or by providing the data as the next program argument (e.g. --subscribe herald). three ways, pick your fave 💅

When using short form options (a single letter prefixed with a -), if the option takes a value it may either be immediately appended to the value (e.g. -L5678) or provided as the next program argument (e.g. -L 5678).

⚠️ POSIX style option clustering of single letter options is not supported; each option must be presented as a separate argument to the program. no -abc stacking, she's not that kind of girl 🙈

🍓 Generic Options 🍓

  • -h, --help — Get usage help. the "help me I'm baby" button.
  • -V, --version — Print the version and exit. short and sweet.
  • -v, --verbose — Select verbose operation. she tells you EVERYTHING.
  • -q, --silent — Select silent operation. she tells you NOTHING. 🤫
  • --compat — Compatible mode. This cause nngcat to behave more like the legacy nanocat application. In this mode connections are made asynchronously, and the --pair option selects version 0 of the pair protocol instead of version 1. retro mode activated 👑
  • --subscribe=TOPIC — Subscribe to TOPIC. This option can only be used with the sub protocol. The TOPIC is checked against the first bytes of messages received, and messages are discarded if they do not match. This may be specified multiple times to subscribe to multiple topics. If not specified at all, then a default subscription to everything is assumed. so if you say nothing, you get everything, which is honestly a whole mood ✨
  • --count==COUNT — Limit the number of iterations when looping to COUNT iterations. For protocols that only send, this will only send COUNT messages before exiting. For protocols that only receive, this will only receive COUNT messages before exiting. For protocols that involve a full exchange, this will only perform COUNT exchanges (each exchange is characterized by at most a single send, and one or more receives.) If COUNT is zero, then an infinite number of iterations is performed. zero means forever, no cap 💀

💜 Protocol Selection Options 💜

📌 Note: At least one protocol must be selected. you can't just show up with no protocol, that's not a lewk.
  • --bus, --bus0 — Select the bus version 0 protocol. This protocol can send and receive messages to and from other bus version 0 peers. the group chat of protocols.
  • --req, --req0 — Select the req version 0 protocol. This protocol sends messages to rep version 0 peers and receives replies from them. she asks, she receives. main character energy.
  • --rep, --rep0 — Select the rep version 0 protocol. This protocol receives messages from req version 0 peers and can send replies to them. the one who always answers in the chat.
  • --pub, --pub0 — Select the pub version 0 protocol. This protocol sends messages to sub version peers. she posts, she doesn't read replies. iconic.
  • --sub, --sub0 — Select the sub version 0 protocol. This protocol receives messages from pub version 0 peers, and filters them based on subscriptions set with --subscribe. lurking, but with ✨intention✨.
  • --push, --push0 — Select the push version 0 protocol. This protocol sends messages to pull version 0 peers. A given message is normally only delivered to a single peer. she's not about that broadcasting life.
  • --pull, --pull0 — Select the pull version 0 protocol. This protocol receives messages from push version 0 peers. catches whatever push sends. 🎀
  • --pair0 — Select the pair version 0 protocol. This protocol can send and receive messages with one connected pair version 0 peer. just the two of you, bestie.
  • --pair1 — Select the pair version 1 protocol. This protocol can send and receive messages with one connected pair version 1 peer. It is not supported in --compat mode. (Polyamorous mode is not supported in nngcat, although peers may be using polyamorous mode.) oop — the polyamory is peer-side only, nngcat is monogamous here 🙈
  • --pair — Acts as an alias for --pair1, unless --compat mode is selected, in which case it acts as an alias for --pair0. she adapts to her environment, versatile queen.
  • --surveyor, --surveyor0 — Select the surveyor version 0 protocol. This protocol sends a survey request to respondent version 0 peers, and then receives replies from them. poll the group, collect the tea ☕
  • --respondent, --respondent0 — Select the respondent version 0 protocol. This protocol receives survey requests from surveyor version 0 peers, and can send a reply to them. she always has something to say.

🧚 Peer Selection Options 🧚

📌 Note: At least one peer address must be selected.
💡 Tip: While legacy nanocat only supported one peer, nngcat can support more than one peer on a given connection. glow up fr fr 🔥
  • --connect, --dial=URL — Connect to the peer at the address specified by URL.
  • --bind, --listen=URL — Bind to, and accept connections from peers, at the address specified by URL.
  • -x, --connect-ipc=PATH — Connect to the IPC path specified by PATH. This is the same as --connect=ipc://PATH.
  • -X, --bind-ipc=PATH — Bind to the IPC path specified by PATH. This is the same as --bind=ipc://PATH.
  • -l, --connect-local=PORT — Connect to localhost at the TCP port specified by PORT. This is the same as --connect=tcp://127.0.0.1:PORT.
  • -L, --bind-local=PORT — Bind to the TCP port specified by PORT. This is the same as --bind=tcp://127.0.0.1:PORT.

⭐ Receive Options ⭐

Data messages received can be formatted in different ways. These options can only be specified when using a protocol that receives messages. if your protocol doesn't receive, these do literally nothing, don't waste your time 💀

  • -A, --ascii — The same as specifying --format=ascii.
  • -Q, --quoted — The same as specifying --format=quoted.
  • --hex — The same as specifying --format=hex.
  • --msgpack — The same as specifying --format=msgpack.
  • --raw — The same as specifying --format=raw.
  • --receive-timeout=SEC — Give up receiving messages after SEC seconds pass without any received messages. she waits, but not forever, she has boundaries ✋
  • --recv-maxsz=COUNT — Set the maximum message size socket will accept to COUNT bytes. Messages larger than this will be discarded. The default is 1048576 (1 MB). To eliminate any restriction, use 0. big messages? not on her watch. unless you say 0, then she's chill about it.
  • --format=FORMAT — Format data as indicated. The FORMAT can be any of:
    • no — No output at all. she's giving absolutely nothing and that's on purpose 💅
    • raw — Raw output, every byte received is sent to standard output.
    • ascii — ASCII safe, printable ASCII is emitted verbatim, with other bytes substituted with . (period).
    • quoted — Messages are printed as quoted strings, using C language conventions.
    • hex — Messages are printed as quoted strings, with every byte appearing as an escaped hexadecimal value, such as \x2E.
    • msgpack — Messages are emitted as MessagePack <https://msgpack.org> "bin format" (byte arrays).

💌 Transmit Options 💌

Protocols that support sending data can use these options to select the data. go on, send the message, bestie 📨

  • -D, --data=DATA — Use DATA for the body of outgoing messages.
  • -F, --file=FILE — Use FILE for the body of outgoing messages. If FILE is - the message body will be read from standard input. cute little shortcut, obsessed.
  • -i, --interval=SEC — For protocols that send unsolicited data (as opposed to those that send data only in response to received messages), this will resend the outgoing message at repeating intervals of SEC seconds. she will NOT stop posting. 🌀
  • -d, --delay=SEC — Wait SEC seconds before sending the first outgoing message. This is useful to let connections establish before sending data, thereby avoiding message loss. be patient, let the connection cook first 🍳
  • --send-timeout=SEC — Give up trying to send a message after SEC seconds. no message is worth waiting forever for, periodt.

🔐 TLS Options 🔐

These options are only present if TLS is configured; they are ignored when using addresses that are not secured with TLS. so if you're not doing TLS, these are just sitting there, decorative ✨

  • -k, --insecure — Skip peer validation. yes, that's the dangerous one, that's the "I'm choosing chaos" one, know that going in 💀
  • -E, --cert=FILE — Load own certificate from FILE.
  • --key=FILE — Load own key from FILE. Should be used in conjunction with --cert. If not specified, and --cert is specified, then a single file containing both the private key and the associated certificate is assumed.
  • --cacert=FILE — Load CA certificates from FILE. These CAs ("Certificate Authorities") are used as trust roots when validating certificates presented by peers.

🌙 ZeroTier Options 🌙

These options are only present if ZeroTier is configured; they are ignored otherwise. same deal, only relevant if you signed up 🎀

  • --zt-home=DIRECTORY — Directory for persistent ZeroTier node (key material, etc.) This directory must already exist. Only one program may use a ZeroTier node at a time; file locking is used to prevent this. so like, mkdir first, and don't fight your other programs over it, sharing is not caring here 🙈

🎀 EXAMPLES 🎀

Echo service using request/reply.

$ addr="tcp://127.0.0.1:4567"
$ nngcat --rep --listen=${addr} --data="42" --quoted &
$ nngcat --req --dial=${addr} --data="what is the answer?" --quoted
"what is the answer?"
"42"

Send a chime every hour (3600 seconds).

$ addr=ipc:///grandpa_clock
$ nngcat --pub --listen=${addr} --data "cuckoo" --interval 3600 &
$ nngcat --sub --dial=${addr} --quoted &
"cuckoo"

look at that. a whole working topology in six lines. she ate and left no crumbs 👑

🫶 SEE ALSO 🫶

libnng(3), nng(7), nng_bus(7), nng_pair(7), nng_pub(7), nng_pull(7), nng_push(7), nng_sub(7), nng_rep(7), nng_req(7), nng_respondent(7), nng_surveyor(7)

go read those too, iykyk, the lore goes deep 📚

and that's the whole vibe, bestie 💜 this beauty shipped as part of the NNG Reference Manual — dated 2026-10-13 — and she goes by NNGCAT(1) around these parts. go send a message or something, you got this. 🦋✨

📦 where this page comes from