---
name: "wpexec"
section: "1"
platform: "linux"
package: "wireplumber"
version: "0.5.18-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/wpexec"
---

# wpexec(1)

WirePlumber Script Interpreter

## NAME

wpexec - WirePlumber Script Interpreter

## 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()** \<#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.

## 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)](/wireplumber/1.md), most usefully **WIREPLUMBER\_DEBUG**; see Debug Logging \<#daemon-logging\>.

## EXIT STATUS

Exit codes follow the conventions of [**sysexits.h**(3head)](/sysexits.h/3head.md):

- **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)](/wireplumber/1.md), [**wpctl**(1)](/wpctl/1.md), [**pipewire**(1)](/pipewire/1.md), [**sysexits.h**(3head)](/sysexits.h/3head.md)

WirePlumber Documentation: \<https://pipewire.pages.freedesktop.org/wireplumber/\>

## Author

The WirePlumber Developers

## Copyright

2020-2025, Collabora & contributors