wayvncctl(1) General Commands Manual wayvncctl(1)

# [NAME](#NAME)

wayvncctl - A command line control client for [wayvnc(1)](/man/enterprise-packages/wayvnc/wayvnc.1)

# [SYNOPSIS](#SYNOPSIS)

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

# [OPTIONS](#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](#DESCRIPTION)

[**wayvnc(1)**](/man/enterprise-packages/wayvnc/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](#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","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
```

## [SPECIAL LOCAL EVENT TYPES](#SPECIAL_LOCAL_EVENT_TYPES)

Especially useful when using *--wait* or *--reconnect* mode, wayvncctl will generate 2 additional events not documented in [**wayvnc(1)**](/man/enterprise-packages/wayvnc/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 parameters.

**wayvnc-shutdown**

Sent when the wayvnc control connection is dropped, usually due to wayvnc exiting.

No parameters.

# [EXAMPLES](#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](#ENVIRONMENT)

The following environment variables have an effect on wayvncctl:

*XDG\_RUNTIME\_DIR*

Specifies the default location for the wayvncctl control socket.

# [SEE ALSO](#SEE_ALSO)

[**wayvnc(1)**](/man/enterprise-packages/wayvnc/wayvnc.1)

2026-10-30

---

Document: wayvncctl(1) from wayvnc 0.10.2-r2 (Chainguard OS)