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

# wpctl(1)

WirePlumber Control CLI

## NAME

wpctl - WirePlumber Control CLI

## SYNOPSIS

**wpctl** \[*COMMAND*\] \[*COMMAND\_OPTIONS*\]

## DESCRIPTION

**wpctl** is a command-line control tool for WirePlumber, the PipeWire session manager. It provides an interface to inspect, control, and configure audio and video devices, nodes, and their properties within a PipeWire media server.

WirePlumber manages audio and video routing, device configuration, and session policies. **wpctl** allows users to interact with these components, change volume levels, set default devices, inspect object properties, and modify settings.

## COMMANDS

### status

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

Displays the current state of objects in PipeWire, including devices, sinks, sources, filters, and streams. Shows a hierarchical view of the audio/video system.

- **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**\]

Displays a machine-readable list of PipeWire objects, optionally filtered by media type and object type. Each line of output contains tab-separated fields: object ID, name, media type/object type, and a **\*** marker if the node is the current default.

- **Arguments:**

  - **audio**\|**video** (optional)

    Filter by media type

  - **devices**\|**sinks**\|**sources** (optional)

    Filter by object type (requires media type to be specified first)

### get-volume

**wpctl get-volume** *ID*

Displays volume information about the specified node, including current volume level and mute state.

- **Arguments:**

  - ***ID***

    Node ID or special identifier (see SPECIAL IDENTIFIERS)

### inspect

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

Displays detailed information about the specified object, including all 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 require auto-connection.

The selection is remembered across restarts, in the **default-nodes** state file \<#state-locations\>, and 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*\[**%**\]\[**-**\|**+**\]

    Volume specification:

    - •

      *VOL* - Set volume to specific value (1.0 = 100%)

    - •

      *VOL***%** - Set volume to 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 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 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 given index.

- **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 given index.

- **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 no ID is specified, clears all default nodes.

This forgets the current and all previous **set-default** selections of that kind, so that WirePlumber goes back to choosing the default node automatically, based on the **priority.session** property of each node. It is needed whenever a configured priority appears to have no effect, since 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 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 **--no-restart** is given. A confirmation prompt is shown before any files are deleted, unless **--yes** is given.

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 are resolved at runtime to the appropriate node IDs.

## EXIT STATUS

**wpctl** returns the following exit codes:

- **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.

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)](/wireplumber/1.md), [**wpexec**(1)](/wpexec/1.md), [**pipewire**(1)](/pipewire/1.md), [**pw-cli**(1)](/pw-cli/1.md), [**pw-dump**(1)](/pw-dump/1.md)

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

## Author

The WirePlumber Developers

## Copyright

2020-2025, Collabora & contributors