.\" Generated by scdoc 1.11.3
.\" 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" "2024-08-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-readible 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 paramerers.\&
.PP
.RE
\fBwayvnc-shutdown\fR
.RS 4
Sent when the wayvnc control connection is dropped, usually due to
wayvnc exiting.\&
.PP
No paramerers.\&
.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