WPEXEC(1) WirePlumber WPEXEC(1)

wpexec - WirePlumber Script Interpreter

wpexec SCRIPT [ARGUMENTS]

wpexec is the WirePlumber script interpreter. It runs a single Lua script against a running PipeWire daemon, without starting a full session manager.

This makes it the tool of choice for developing and testing scripts, for one-off queries and for small standalone policy scripts that run alongside the main WirePlumber instance.

When invoked, wpexec connects to PipeWire, activates the plugins that the script requires through Core.require_api() <#Core.require_api>, and then runs the script. It keeps running until the script calls Core.quit() <#Core.quit>, the connection to PipeWire is lost, or it is interrupted with SIGINT, SIGTERM or SIGHUP.

Scripts run under wpexec have access to the same Lua API <#scripting-lua-api> as scripts loaded by the daemon, with the exception of a few functions that only make sense inside the daemon.

The path to the Lua script to execute.
ARGUMENTS
An optional SPA-JSON object that is passed to the script as its argument (...). Passing anything that is not a JSON object is an error.

Run a script:

$ wpexec ./get-default-sink-volume.lua

Run a script with arguments:

$ wpexec ./interactive.lua '{ option1 = "value1", option2 = "value2" }'

Run a script from a build tree, without installing:

$ ./wp-uninstalled.sh wpexec tests/examples/interactive.lua

A script may also be made directly executable by giving it the appropriate shebang line, as the examples in tests/examples do:

#!/usr/bin/wpexec

wpexec honours the same environment variables as wireplumber(1), most usefully WIREPLUMBER_DEBUG; see Debug Logging <#daemon-logging>.

Exit codes follow the conventions of sysexits.h(3head):

0 (EX_OK)
Success.
64 (EX_USAGE)
Command line usage error, including a malformed ARGUMENTS object.
69 (EX_UNAVAILABLE)
Could not connect to PipeWire.
70 (EX_SOFTWARE)
Internal software error, including an error raised by the script.

wireplumber(1), wpctl(1), pipewire(1), sysexits.h(3head)

WirePlumber Documentation: https://pipewire.pages.freedesktop.org/wireplumber/

The WirePlumber Developers

2020-2025, Collabora & contributors

September 3, 2026 0.5.17