Interaction Tools

The interaction tools operate on specific D-Bus objects once you know their service name, object path, and interface. Use the discovery tools to find those coordinates first.

call_method

Call a D-Bus method and return the result.

Parameters

Parameter	Type	Default	Description
bus	string	required	"session" or "system"
service	string	required	Service name, e.g. "org.freedesktop.Notifications"
object_path	string	required	Object path, e.g. "/org/freedesktop/Notifications"
interface	string	required	Interface name, e.g. "org.freedesktop.Notifications"
method	string	required	Method name, e.g. "Notify"
args	string	"[]"	JSON array of arguments
signature	string	""	D-Bus type signature string; leave empty for no-arg methods

Confirmation

System bus calls require user confirmation before execution. Session bus calls proceed without prompting (they operate within user scope). See Confirmation Flow for details on how confirmation is resolved.

Argument parsing

The args parameter accepts a JSON array string. Each element is deserialized according to the corresponding type in the signature string.

For Variant (v) signatures, two modes are supported:

Auto-wrapping

Simple Python types are automatically wrapped into D-Bus Variants:

Python type	Inferred signature
bool	"b"
str	"s"
int	"i"
float	"d"
list	"as" (array of strings)
dict	"a{sv}" (dict of string to variant)

["hello", true, 42]

Explicit Variant

For complex variant values where auto-inference would produce the wrong type, pass an object with signature and value keys:

[{"signature": "ai", "value": [1, 2, 3]}]

This wraps the array as Variant("ai", [1, 2, 3]) rather than the auto-inferred Variant("as", [1, 2, 3]).

Return format

• Single-element responses are unwrapped from their containing array for cleaner output
• Multi-element responses are returned as a JSON array
• Void methods return the string "Method returned no data (void)."
• All values are JSON-formatted with 2-space indentation

Examples

Send a desktop notification:

call_method(
    bus="session",
    service="org.freedesktop.Notifications",
    object_path="/org/freedesktop/Notifications",
    interface="org.freedesktop.Notifications",
    method="Notify",
    args='["mcdbus", 0, "", "Hello", "World", [], {}, 5000]',
    signature="susssasa{sv}i"
)

Call a no-arg method:

call_method(
    bus="session",
    service="org.freedesktop.Notifications",
    object_path="/org/freedesktop/Notifications",
    interface="org.freedesktop.Notifications",
    method="GetServerInformation"
)

---

get_property

Read a single D-Bus property value.

Parameters

Parameter	Type	Default	Description
bus	string	required	"session" or "system"
service	string	required	Service name
object_path	string	required	Object path
interface	string	required	Interface that owns the property
property_name	string	required	Property name to read

How it works

Calls org.freedesktop.DBus.Properties.Get with the specified interface and property name. The returned Variant is unwrapped and JSON-formatted.

Return format

JSON-formatted property value with 2-space indentation. Returns "No value returned." if the property read yields no data.

Example

get_property(
    bus="session",
    service="org.mpris.MediaPlayer2.firefox",
    object_path="/org/mpris/MediaPlayer2",
    interface="org.mpris.MediaPlayer2.Player",
    property_name="PlaybackStatus"
)

Returns:

"Playing"

---

set_property

Set a D-Bus property value.

Parameters

Parameter	Type	Default	Description
bus	string	required	"session" or "system"
service	string	required	Service name
object_path	string	required	Object path
interface	string	required	Interface that owns the property
property_name	string	required	Property name to set
value	string	required	JSON-encoded value
signature	string	required	D-Bus type signature of the property value (e.g. "b" for boolean)

Confirmation

This tool always requires user confirmation regardless of which bus is targeted. Property mutations are state-changing operations and the confirmation prompt is not skippable. See Confirmation Flow for the full resolution chain.

How it works

1. The value JSON string is parsed
2. The parsed value is wrapped in a Variant with the provided signature
3. After confirmation, org.freedesktop.DBus.Properties.Set is called
4. The operation is audit-logged to stderr with the bus, service, interface, property name, value, and signature

Return format

Confirmation string: Set {interface}.{property_name} = {value}

Example

set_property(
    bus="session",
    service="org.mpris.MediaPlayer2.firefox",
    object_path="/org/mpris/MediaPlayer2",
    interface="org.mpris.MediaPlayer2.Player",
    property_name="Volume",
    value="0.5",
    signature="d"
)

---

get_all_properties

Read all properties on a D-Bus interface.

Parameters

Parameter	Type	Default	Description
bus	string	required	"session" or "system"
service	string	required	Service name
object_path	string	required	Object path
interface	string	required	Interface to read properties from

How it works

Calls org.freedesktop.DBus.Properties.GetAll with the specified interface name. Returns all properties as a formatted table.

Return format

Markdown table with Property and Value columns, sorted alphabetically by property name. Values are JSON-serialized and truncated at 80 characters to keep the table readable.

## Properties of `org.mpris.MediaPlayer2.Player` at `/org/mpris/MediaPlayer2`

| Property | Value |
|----------|-------|
| `CanControl` | `true` |
| `CanGoNext` | `true` |
| `CanGoPrevious` | `true` |
| `CanPause` | `true` |
| `CanPlay` | `true` |
| `Metadata` | `{"xesam:title": "Starman", "xesam:artist": ["David Bowie"], "mpris:le...` |
| `PlaybackStatus` | `"Playing"` |
| `Volume` | `1.0` |

Returns "No properties found." if the interface exposes no properties.

Example

get_all_properties(
    bus="session",
    service="org.mpris.MediaPlayer2.firefox",
    object_path="/org/mpris/MediaPlayer2",
    interface="org.mpris.MediaPlayer2.Player"
)