wayvncctl(1)

1wayvncctl(1)                General Commands Manual               wayvncctl(1)
2
3
4

NAME

6       wayvncctl - A command line control client for wayvnc(1)
7

SYNOPSIS

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

OPTIONS

12       -S, --socket=<path>
13           Set wayvnc control socket path. Default: $XDG_RUNTIME_DIR/wayvncctl
14           or /tmp/wayvncctl-$UID
15
16       -w, --wait
17           Wait for wayvnc to start up if it's not already running. Default:
18           Exit immediately with an error if wayvnc is not running.
19
20       -r,--reconnect
21           If disconnected while waiting for events, wait for wayvnc to
22           restart and re-register for events. Default: Exit when wayvnc ex‐
23           its.
24
25       -j, --json
26           Produce json output to stdout.
27
28       -V, --version
29           Show version info.
30
31       -v,--verbose
32           Be more verbose.
33
34       -h, --help
35           Get help about the wayvncctl command itself (lists these options).
36           Does not connect to the wayvncctl control socket.
37

DESCRIPTION

39       wayvnc(1) allows runtime interaction via a unix socket json-ipc mecha‐
40       nism. This command line utility provides easy interaction with those
41       commands.
42
43       This command is largely self-documenting:
44
45       •   Running wayvncctl --help lists all supported IPC commands.
46       •   Running wayvncctl command-name --help returns a description of the
47           given command and its available parameters.
48       •   Running wayvncctl event-receive --help includes a list of all sup‐
49           ported event names.
50       •   Running wayvncctl event-receive --show=event-name returns a de‐
51           scription of the given event and expected data fields.
52
53

ASYNCHRONOUS EVENTS

55       While wayvncctl normally terminates after sending one request and re‐
56       ceiving the corresponding reply, the event-receive command acts differ‐
57       ently. Instead of exiting immediately, wayvncctl waits for any events
58       from the server, printing each to stdout as they arrive. This mode of
59       operation will block until either it receives a signal to terminate, or
60       until the wayvnc server terminates.
61
62       In --json mode, each event is printed on one line, with a newline char‐
63       acter at the end, for ease in scripting:
64
65           $ wayvncctl --json event-receive
66           {"method":"client-connected","params":{"id":"0x10ef670","hostname":null,"username":null,"connection_count":1}}
67           {"method":"client-disconnected","params":{"id":"0x10ef670","hostname":null,"username":null,"connection_count":0}}
68
69       The default human-readible output is a multi-line yaml-like format,
70       with two newline characters between each event:
71
72           $ wayvncctl event-receive
73
74           client-connected:
75             id: 0x10ef670
76             hostname: 192.168.1.18
77             connection_count: 1
78
79           client-disconnected:
80             id: 0x10ef670
81             hostname: 192.168.1.18
82             connection_count: 0
83
84
85   SPECIAL LOCAL EVENT TYPES
86       Especially useful when using --wait or --reconnect mode, wayvncctl will
87       generate 2 additional events not documented in wayvnc(1):
88
89       wayvnc-startup
90           Sent when a successful wayvnc control connection is established and
91           event registration has succeeded, both upon initial startup and on
92           subsequent registrations with --reconnect.
93
94           No paramerers.
95
96       wayvnc-shutdown
97           Sent when the wayvnc control connection is dropped, usually due to
98           wayvnc exiting.
99
100           No paramerers.
101

EXAMPLES

103       Get help on the "output-set" IPC command:
104
105           $ wayvncctl output-set --help
106           Usage: wayvncctl [options] output-set <output-name> [params]
107           ...
108
109       Cycle to the next active output:
110
111           $ wayvncctl output-cycle
112
113       Get json-formatted version information:
114
115           $ wayvncctl --json version
116           {"wayvnc":"v0.5.0","neatvnc":"v0.5.1","aml":"v0.2.2"}
117
118       A script that takes an action for each client connect and disconnect
119       event:
120
121           #!/bin/bash
122
123           connection_count_now() {
124               echo "Total clients: $1"
125           }
126
127           while IFS= read -r EVT; do
128               case "$(jq -r '.method' <<<"$EVT")" in
129                   client-*onnected)
130                       count=$(jq -r '.params.connection_count' <<<"$EVT")
131                       connection_count_now "$count"
132                       ;;
133                   wayvnc-shutdown)
134                       connection_count_now 0
135                    ;;
136               esac
137           done < <(wayvncctl --wait --reconnect --json event-receive)
138

ENVIRONMENT

140       The following environment variables have an effect on wayvncctl:
141
142       XDG_RUNTIME_DIR
143           Specifies the default location for the wayvncctl control socket.
144