.\" Generated by scdoc 1.11.5
.\" Complete documentation for this program is not available as a GNU info page
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.nh
.ad l
.\" Begin generated content:
.TH "wayvncctl" "1" "2026\-07\-19"
.PP
.SH NAME
.PP
wayvncctl \- A command line control client for wayvnc(1)
.PP
.SH SYNOPSIS
.PP
\fBwayvncctl\fR [options] [command [\-\-parameter value .\&.\&.\&]]
.PP
.SH OPTIONS
.PP
\fB\-S, \-\-socket=<path>\fR
.RS 4
Set wayvnc control socket path.\& Default: $XDG_RUNTIME_DIR/wayvncctl
or /tmp/wayvncctl\-$UID
.PP
.RE
\fB\-w, \-\-wait\fR
.RS 4
Wait for wayvnc to start up if it'\&s not already running.\& Default: Exit
immediately with an error if wayvnc is not running.\&
.PP
.RE
\fB\-r, \-\-reconnect\fR
.RS 4
If disconnected while waiting for events, wait for wayvnc to restart and
re\-register for events.\& Default: Exit when wayvnc exits.\&
.PP
.RE
\fB\-j, \-\-json\fR
.RS 4
Produce JSON output to stdout.\&
.PP
.RE
\fB\-V, \-\-version\fR
.RS 4
Show version info.\&
.PP
.RE
\fB\-v, \-\-verbose\fR
.RS 4
Be more verbose.\&
.PP
.RE
\fB\-h, \-\-help\fR
.RS 4
Get help about the wayvncctl command itself (lists these options).\& Does
not connect to the wayvncctl control socket.\&
.PP
.RE
.SH DESCRIPTION
.PP
\fBwayvnc(1)\fR allows runtime interaction via a unix socket json\-ipc mechanism.\&
This command line utility provides easy interaction with those commands.\&
.PP
This command is largely self\-documenting:
.PP
.PD 0
.IP \(bu 4
Running \fBwayvncctl \-\-help\fR lists all supported IPC commands.\&
.IP \(bu 4
Running \fBwayvncctl command\-name \-\-help\fR returns a description of the given
command and its available parameters.\&
.IP \(bu 4
Running \fBwayvncctl event\-receive \-\-help\fR includes a list of all supported event
names.\&
.IP \(bu 4
Running \fBwayvncctl event\-receive \-\-show=event\-name\fR returns a
description of the given event and expected data fields.\&
.PD
.PP
.SH ASYNCHRONOUS EVENTS
.PP
While \fBwayvncctl\fR normally terminates after sending one request and receiving
the corresponding reply, the \fBevent\-receive\fR command acts differently.\& Instead
of exiting immediately, \fBwayvncctl\fR waits for any events from the server,
printing each 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.\&
.PP
In \fI\-\-json\fR mode, each event is printed on one line, with a newline character at
the end, for ease in scripting:
.PP
.nf
.RS 4
$ 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}}
.fi
.RE
.PP
The default human\-readable output is a multi\-line YAML\-like format, with two
newline characters between each event:
.PP
.nf
.RS 4
$ 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

.fi
.RE
.PP
.SS SPECIAL LOCAL EVENT TYPES
.PP
Especially useful when using \fI\-\-wait\fR or \fI\-\-reconnect\fR mode, wayvncctl will
generate 2 additional events not documented in \fBwayvnc(1)\fR:
.PP
\fBwayvnc\-startup\fR
.RS 4
Sent when a successful wayvnc control connection is established and
event registration has succeeded, both upon initial startup and on
subsequent registrations with \fI\-\-reconnect\fR.\&
.PP
No parameters.\&
.PP
.RE
\fBwayvnc\-shutdown\fR
.RS 4
Sent when the wayvnc control connection is dropped, usually due to
wayvnc exiting.\&
.PP
No parameters.\&
.PP
.RE
.SH EXAMPLES
.PP
Get help on the "output\-set" IPC command:
.PP
.nf
.RS 4
$ wayvncctl output\-set \-\-help
Usage: wayvncctl [options] output\-set <output\-name> [params]
\&.\&.\&.
.fi
.RE
.PP
Cycle to the next active output:
.PP
.nf
.RS 4
$ wayvncctl output\-cycle
.fi
.RE
.PP
Get JSON\-formatted version information:
.PP
.nf
.RS 4
$ wayvncctl \-\-json version
{"wayvnc":"v0\&.5\&.0","neatvnc":"v0\&.5\&.1","aml":"v0\&.2\&.2"}
.fi
.RE
.PP
A script that takes an action for each client connect and disconnect event:
.PP
.nf
.RS 4
#!/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)
.fi
.RE
.PP
.SH ENVIRONMENT
.PP
The following environment variables have an effect on wayvncctl:
.PP
\fIXDG_RUNTIME_DIR\fR
.RS 4
Specifies the default location for the wayvncctl control socket.\&
.PP
.RE
.SH SEE ALSO
.PP
\fBwayvnc(1)\fR