WPEXEC(1)

📦
version 0.5.18 · 3 versions
, in arch rolling

💅 wpexec(1) — the WirePlumber manual, but make it make sense

okay so real talk, this is the wpexec page from the WirePlumber manual set, and honestly? she's a little icon. let's get into it 🫶

✨ NAME ✨

wpexec — the WirePlumber Script Interpreter. yes that's her whole job and she ate 💅

🎀 SYNOPSIS 🎀

wpexec SCRIPT [ARGUMENTS]

🦋 DESCRIPTION 🦋

okay so wpexec is literally the WirePlumber script interpreter. what it does is run one single Lua script against a PipeWire daemon that's already running — and it does not spin up a whole full session manager to do it. no cap. ✨

which is exactly why she's the tool of choice for:

  • developing and testing scripts
  • one-off queries
  • small standalone policy scripts that run alongside the main WirePlumber instance

when you invoke it, here's the whole vibe: wpexec connects to PipeWire, activates the plugins that the script requires through Core.require_api(), and then runs the script. that's the pipeline. 🧚

and she keeps running until one of these happens:

  • the script calls Core.quit()
  • the connection to PipeWire is lost
  • it gets interrupted with SIGINT, SIGTERM or SIGHUP

the scripts that 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. iykyk 🌈

💖 ARGUMENTS 💖

  • SCRIPT — the path to the Lua script you wanna execute. that's the one. 👑
  • ARGUMENTS — an optional SPA-JSON object that gets passed to the script as its argument (...). heads up bestie: passing anything that is not a JSON object is an error. not a vibe. 💀

🔥 EXAMPLES 🔥

run a script, simple as:

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

run a script with arguments (look at her go):

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

run a script straight from a build tree, without installing anything:

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

and ok this part is genuinely iconic — a script can also be made directly executable by giving it the appropriate shebang line, exactly like the examples in tests/examples do:

#!/usr/bin/wpexec

main character energy fr fr 👑

🌸 ENVIRONMENT 🌸

wpexec honours the same environment variables as wireplumber(1) — and most usefully WIREPLUMBER_DEBUG. see Debug Logging for the deets. 🍓

⭐ EXIT STATUS ⭐

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

  • 0 (EX_OK) — success. slay. ✅
  • 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/>

👑 Author

The WirePlumber Developers

2020-2025, Collabora & contributors

and that's the whole page bestie 💅 mwah! this was WirePlumber wpexec(1), version 0.5.18, dated Sep 30, 2026 — go forth and run exactly one script 🦋✨

📦 where this page comes from