wpexec(1) — WirePlumber 0.5.17 documentation

# wpexec(1)

## SYNOPSIS

wpexec SCRIPT [ARGUMENTS]

## DESCRIPTION

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()`, and then runs the script. It keeps running until the script calls `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 as scripts loaded by the daemon, with the exception of a few functions that only make sense inside the daemon.

## ARGUMENTS

SCRIPT

  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.

## EXAMPLES

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

## ENVIRONMENT

wpexec honours the same environment variables as wireplumber(1), most usefully WIREPLUMBER_DEBUG; see Debug Logging.

## EXIT STATUS

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.

## SEE ALSO

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

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