WPCTL(1)

💅 WPCTL(1) — WirePlumber Control CLI, bestie edition ✨

okay so this is wpctl, the command-line control tool from the WirePlumber fam (that's the PipeWire session manager, iykyk) 🎀

---

🌸 SYNOPSIS 🌸

wpctl [COMMAND] [COMMAND_OPTIONS]

---

✨ DESCRIPTION ✨

wpctl is literally a command-line control tool for WirePlumber, the PipeWire session manager. It gives you a whole interface to inspect, control, and configure audio and video devices, nodes, and their properties inside a PipeWire media server 🦋

So like, WirePlumber handles the audio and video routing, the device configuration, and the session policies — all that backstage main-character work. And wpctl is your little front-row pass to talk to all of it: change volume levels, set default devices, peek at object properties, tweak settings. No cap, it's giving backstage access 💅

---

👑 COMMANDS 👑

🫶 status

wpctl status [-k|--nick] [-n|--name]

Shows you the current state of everything in PipeWire — devices, sinks, sources, filters, and streams. You get a whole hierarchical view of the audio/video system. It's the vibe check for your entire setup �

Options:

• -k, --nick — display device and node nicknames instead of descriptions 🏷️
• -n, --name — display device and node names instead of descriptions 🏷️

🫶 list

wpctl list [audio|video] [devices|sinks|sources]

Shows a machine-readable list of PipeWire objects, and you can filter by media type and object type if you want. Every line of output has tab-separated fields: the object ID, the name, the media type/object type, and a * marker if that node is the current default ⭐

Arguments:

• audio|video (optional) — filter by media type 🎧📹
• devices|sinks|sources (optional) — filter by object type (heads up: this one requires you to specify the media type first) 🚨

🫶 get-volume

wpctl get-volume ID

Shows volume info about the node you point at — the current volume level and the mute state 🔉

Arguments:

• ID — node ID or a special identifier (go look at SPECIAL IDENTIFIERS below, bestie) 🧚

🫶 inspect

wpctl inspect ID [-r|--referenced] [-a|--associated]

Shows you the detailed tea on the specified object — all the properties and metadata ☕✨

Arguments:

• ID — object ID or special identifier 🔍

Options:

• -r, --referenced — show objects that are referenced in properties 🔗
• -a, --associated — show associated objects 🧩

🫶 set-default

wpctl set-default ID

Sets the specified device node to be the default target of its kind (capture or playback) for new streams that need auto-connection 👑

The selection is remembered across restarts, in the default-nodes state file <#state-locations>, and it takes precedence over the automatic, priority-based selection that WirePlumber would otherwise make. Use clear-default to undo it 💀

Arguments:

• ID — sink or source node ID 🎯

🫶 set-volume

wpctl set-volume ID VOL[%][-|+] [-p|--pid] [-l LIMIT|--limit LIMIT]

Sets the volume of the specified node 🔊

Arguments:

• ID — node ID, special identifier, or PID (with --pid) 🪪
• VOL[%][-|+] — the volume specification:
  • VOL — set volume to a specific value (1.0 = 100%) 💯
  • VOL% — set volume to a percentage (50% = 0.5) 🍰
  • VOL+ — increase volume by value ⬆️
  • VOL- — decrease volume by value ⬇️
  • VOL%+ — increase volume by percentage 📈
  • VOL%- — decrease volume by percentage 📉

Options:

• -p, --pid — treat ID as a process ID and affect all nodes associated with it 🧬
• -l LIMIT, --limit LIMIT — limit the final volume to below this value (floating point, 1.0 = 100%) 🚧

Examples:

Set volume to 50%: wpctl set-volume @DEFAULT_SINK@ 0.5

Increase volume by 10%: wpctl set-volume 42 10%+

Set volume for all nodes of PID 1234: wpctl set-volume --pid 1234 0.8

🫶 set-mute

wpctl set-mute ID 1|0|toggle [-p|--pid]

Changes the mute state of the specified node 🤫

Arguments:

• ID — node ID, special identifier, or PID (with --pid) 🪪
• 1|0|toggle — mute state: 1 (mute), 0 (unmute), or toggle the current state 🔁

Options:

• -p, --pid — treat ID as a process ID and affect all nodes associated with it 🧬

🫶 set-profile

wpctl set-profile ID INDEX

Sets the profile of the specified device to the index you give it 🎛️

Arguments:

• ID — device ID or special identifier 🪪
• INDEX — profile index (integer, 0 typically means 'off') 🚫

🫶 set-route

wpctl set-route ID INDEX

Sets the route of the specified device to the index you give it 🛤️

Arguments:

• ID — device node ID or special identifier 🪪
• INDEX — route index (integer, 0 typically means 'off') 🚫

🫶 clear-default

wpctl clear-default [ID]

Clears the default configured node. If you don't give it an ID, it clears all the default nodes 🧹

This forgets the current and all previous set-default selections of that kind, so WirePlumber goes back to choosing the default node automatically, based on the priority.session property of each node. It's needed whenever a configured priority appears to have no effect — because a saved selection outranks any priority. The saved selections are listed in the "Default Configured Devices" section of status 📋

Arguments:

• ID (optional) — settings ID to clear (0-2 for Audio/Sink, Audio/Source, Video/Source). If omitted, clears all defaults 🌈

🫶 settings

wpctl settings [KEY] [VAL] [-d|--delete] [-s|--save] [-r|--reset]

Shows, changes, or removes WirePlumber settings ⚙️

Arguments:

• KEY (optional) — setting key name 🔑
• VAL (optional) — setting value (JSON format) 📦

Options:

• -d, --delete — delete the saved setting value (no KEY means delete all) 🗑️
• -s, --save — save the setting value (no KEY means save all, no VAL means current value) 💾
• -r, --reset — reset the setting to its default value 🔄

Behavior:

• No arguments: show all settings 👀
• KEY only: show specific setting value 🔍
• KEY and VAL: set specific setting value ✍️

🫶 set-log-level

wpctl set-log-level [ID] LEVEL

Sets the log level of a client 📝

Arguments:

• ID (optional) — client ID. If omitted, applies to WirePlumber. Use 0 for the PipeWire server. 🖥️
• LEVEL — log level (e.g., 0, 1, 2, 3, 4, 5, E, W, N, I, D, T). Use - to unset the log level. 🎚️

🫶 reset

wpctl reset [-c|--wireplumber-config] [-p|--pipewire-config] [-a|--all]
[-n|--no-restart] [-d|--dry-run] [-y|--yes]

Resets WirePlumber (and optionally PipeWire) to defaults by removing state and configuration files 🧼 By default, only the WirePlumber state directory (~/.local/state/wireplumber) is removed. WirePlumber is automatically stopped before removal and restarted afterwards — unless you give --no-restart. A confirmation prompt is shown before any files are deleted, unless you give --yes ⚠️

This command does not require a running PipeWire session 🚫🎧

Options:

• -c, --wireplumber-config — also remove WirePlumber user configuration files (~/.config/wireplumber) 🗂️
• -p, --pipewire-config — also remove PipeWire user configuration files (~/.config/pipewire) and restart the PipeWire service 🔄
• -a, --all — remove all state and configuration files (equivalent to combining -c and -p) 💥
• -n, --no-restart — do not stop or restart services after removing files 🛑
• -d, --dry-run — show which files would be deleted without actually deleting anything or restarting services 👻
• -y, --yes — proceed without prompting for confirmation ✅

---

🧚 SPECIAL IDENTIFIERS 🧚

Instead of numeric IDs, wpctl accepts these special identifiers for commonly used defaults:

• @DEFAULT_SINK@, @DEFAULT_AUDIO_SINK@ — the current default audio sink (playback device) 🔊
• @DEFAULT_SOURCE@, @DEFAULT_AUDIO_SOURCE@ — the current default audio source (capture device) 🎙️
• @DEFAULT_VIDEO_SOURCE@ — the current default video source (camera) 📹

These identifiers get resolved at runtime to the appropriate node IDs ✨

---

💀 EXIT STATUS 💀

wpctl returns these exit codes, so you know what's up:

• 0 — success 🎉
• 1 — general error (e.g., invalid arguments, connection failure) 😬
• 2 — could not connect to PipeWire 😭
• 3 — command-specific error (e.g., object not found) 🕵️

---

🌈 EXAMPLES 🌈

Display system status:

wpctl status

Set default audio sink:

wpctl set-default 42

Set volume to 75% on default sink:

wpctl set-volume @DEFAULT_SINK@ 75%

Increase volume by 5% on a specific node:

wpctl set-volume 42 5%+

Mute the default source:

wpctl set-mute @DEFAULT_SOURCE@ 1

Toggle mute on default sink:

wpctl set-mute @DEFAULT_SINK@ toggle

Inspect a device with associated objects:

wpctl inspect --associated 30

Show all WirePlumber settings:

wpctl settings

Set a specific setting:

wpctl settings bluetooth.autoswitch true

Save all current settings:

wpctl settings --save

Set log level for WirePlumber to debug:

wpctl set-log-level D

Set log level for a specific client:

wpctl set-log-level 42 W

List all audio sinks:

wpctl list audio sinks

Reset WirePlumber state (dry run):

wpctl reset --dry-run

Reset WirePlumber state and config without prompting:

wpctl reset --wireplumber-config --yes

Reset everything (WirePlumber and PipeWire state and config):

wpctl reset --all

---

🍓 NOTES 🍓

Object IDs can be found using the status command — the hierarchical display shows IDs for devices, nodes, and other objects 👀

Volume values are floating-point numbers where 1.0 represents 100% volume. Values can exceed 1.0 to introduce volume amplification 🔥 (yes bestie, that's how you go past 100%)

When using the --pid option, wpctl will find all audio nodes associated with the specified process ID and apply the operation to all of them 🧬💅

---

🦋 SEE ALSO 🦋

wireplumber(1), wpexec(1), pipewire(1), pw-cli(1), pw-dump(1)

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

Author

The WirePlumber Developers 👑

Copyright

2020-2025, Collabora & contributors ©️

---

and that's the whole page, bestie — version 0.5.18, dated Sep 30, 2026, brought to you by the WirePlumber girlies. go forth and slay your audio routing 💜✨🎀