wayvnc/wayvncctl.scd

161 lines
4.0 KiB
Markdown

wayvncctl(1)
# NAME
wayvncctl - A command line control client for wayvnc(1)
# SYNOPSIS
*wayvncctl* [options] [command [--parameter value ...]]
# OPTIONS
*-S, --socket=<path>*
Set wayvnc control socket path. Default: $XDG_RUNTIME_DIR/wayvncctl
or /tmp/wayvncctl-$UID
*-w, --wait*
Wait for wayvnc to start up if it's not already running. Default: Exit
immediately with an error if wayvnc is not running.
*-r,--reconnect*
If disconnected while waiting for events, wait for wayvnc to restart and
re-register for events. Default: Exit when wayvnc exits.
*-j, --json*
Produce json output to stdout.
*-V, --version*
Show version info.
*-v,--verbose*
Be more verbose.
*-h, --help*
Get help about the wayvncctl command itself (lists these options). Does
not connect to the wayvncctl control socket.
# DESCRIPTION
*wayvnc(1)* allows runtime interaction via a unix socket json-ipc mechanism.
This command line utility provides easy interaction with those commands.
This command is largely self-documenting:
- 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.
# ASYNCHRONOUS EVENTS
While *wayvncctl* normally terminates after sending one request and receiving
the corresponding reply, the *event-receive* command acts differently. Instead
of exiting immediately, *wayvncctl* 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.
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","hostname":null,"username":null,"connection_count":1}}
{"method":"client-disconnected","params":{"id":"0x10ef670","hostname":null,"username":null,"connection_count":0}}
```
The default human-readible output is a multi-line yaml-like format, with two
newline characters between each event:
```
$ wayvncctl event-receive
client-connected:
id: 0x10ef670
hostname: 192.168.1.18
connection_count: 1
client-disconnected:
id: 0x10ef670
hostname: 192.168.1.18
connection_count: 0
```
## SPECIAL LOCAL EVENT TYPES
Especially useful when using _--wait_ or _--reconnect_ mode, wayvncctl will
generate 2 additional events not documented in *wayvnc(1)*:
*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 paramerers.
*wayvnc-shutdown*
Sent when the wayvnc control connection is dropped, usually due to
wayvnc exiting.
No paramerers.
# 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:
```
$ 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:
```
#!/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:
_XDG_RUNTIME_DIR_
Specifies the default location for the wayvncctl control socket.
# SEE ALSO
*wayvnc(1)*