wayvncctl(1)

📦
version 0.10.2 · 13 versions
, in arch rolling

💅 wayvncctl — the group-chat remote for wayvnc(1)

okay so bestie, this is wayvncctl from the General Commands Manual section, and it's literally the command line control client for wayvnc(1). it's giving "remote control but make it unix socket" ✨

🌸 SYNOPSIS 🌸

wayvncctl [options] [command [--parameter value ...]]

that's it. that's the whole vibe. options first, then a command, then whatever --parameter value pairs that command wants 🎀

✨ OPTIONS ✨

  • -S, --socket=<path> — sets the wayvnc control socket path. the default is $XDG_RUNTIME_DIR/wayvncctl, or failing that, /tmp/wayvncctl-$UID 🫶
  • -w, --wait — wait for wayvnc to start up if it's not already running. default behavior? exit immediately with an error if wayvnc isn't running. no patience whatsoever 💀
  • -r, --reconnect — if you get disconnected while waiting for events, this waits for wayvnc to restart and re-registers for events. default is to just exit when wayvnc exits 🦋
  • -j, --json — produce JSON output to stdout. script girlies rise 👑
  • -V, --version — show version info ⭐
  • -v, --verbose — be more verbose. say more words. we love a chatty icon 🗣️
  • -h, --help — get help about the wayvncctl command itself (lists these options). heads up: this does not connect to the wayvncctl control socket 🙈

💜 DESCRIPTION 💜

so wayvnc(1) lets you interact with it at runtime through a unix socket json-ipc mechanism, and this command line utility is your easy little front door to all those commands. it's giving helpful intermediary 🌈

and the best part: this command is largely self-documenting, which lowkey slays:

  • running wayvncctl --help lists all supported IPC commands 👀
  • running wayvncctl command-name --help returns a description of the given command and its available parameters
  • running wayvncctl event-receive --help includes a list of all supported event names
  • running wayvncctl event-receive --show=event-name returns a description of the given event and expected data fields

like, it literally explains itself. main character energy fr fr 💅

🦋 ASYNCHRONOUS EVENTS 🦋

okay so normally wayvncctl terminates after sending one request and receiving the corresponding reply — in and out, no lingering. but the event-receive command is different, it's built different actually. instead of exiting immediately, wayvncctl waits for any events from the server and prints each one to stdout as they arrive. this mode of operation will block until either it receives a signal to terminate, or until the wayvnc server terminates 🌸

in --json mode, each event is printed on one line, with a newline character at the end, for ease in scripting:

$ wayvncctl --json event-receive
{"method":"client-connected","params":{"id":"0x10ef670","address":null,"username":null,"connection_count":1}}
{"method":"client-disconnected","params":{"id":"0x10ef670","address":null,"username":null,"connection_count":0}}

the default human-readable output is a multi-line YAML-like format, with two newline characters between each event:

$ wayvncctl event-receive

client-connected:
  id: 0x10ef670
  address: 192.168.1.18
  connection_count: 1

client-disconnected:
  id: 0x10ef670
  address: 192.168.1.18
  connection_count: 0

so pretty. so readable. we stan a formatted event stream 🎀

⭐ SPECIAL LOCAL EVENT TYPES ⭐

especially useful when you're in --wait or --reconnect mode, wayvncctl will generate 2 additional events that are not documented in wayvnc(1) — exclusive drop, iykyk 🔥

  • wayvnc-startup — sent when a successful wayvnc control connection is established and event registration has succeeded, both upon initial startup and on subsequent registrations with --reconnect. no parameters.
  • wayvnc-shutdown — sent when the wayvnc control connection is dropped, usually due to wayvnc exiting. no parameters.

🧚 EXAMPLES 🧚

get help on the "output-set" IPC command:

$ wayvncctl output-set --help
Usage: wayvncctl [options] output-set <output-name> [params]
...

cycle to the next active output — chef's kiss, one line, no notes:

$ wayvncctl output-cycle

get JSON-formatted version information:

$ wayvncctl --json version
{"wayvnc":"v0.5.0","neatvnc":"v0.5.1","aml":"v0.2.2"}

a script that takes an action for each client connect and disconnect event — bestie this one is the moment, it ate:

#!/bin/bash

connection_count_now() {
    echo "Total clients: $1"
}

while IFS= read -r EVT; do
    case "$(jq -r '.method' <<<"$EVT")" in
        client-*onnected)
            count=$(jq -r '.params.connection_count' <<<"$EVT")
            connection_count_now "$count"
            ;;
        wayvnc-shutdown)
            connection_count_now 0
            ;;
    esac
done < <(wayvncctl --wait --reconnect --json event-receive)

🌈 ENVIRONMENT 🌈

the following environment variables have an effect on wayvncctl. yes, only one, but she's doing her best 💖

  • XDG_RUNTIME_DIR — specifies the default location for the wayvncctl control socket.

💀 SEE ALSO 💀

wayvnc(1) — go read that one too, it's the whole reason this exists 🫶

ngl if something's acting weird, check your socket path first — -S is right there and she's very accommodating 💅

that's the page, bestie!! no cap, you're now basically a wayvncctl expert 👑

© the wayvncctl(1) page — wayvncctl(1), dated 2026-10-01, from the General Commands Manual. bye bestie, go cycle some outputs 💜✨

📦 where this page comes from