Discovery Tools

The discovery tools form the first step in any D-Bus interaction. They answer the questions “what services exist?”, “what does this object expose?”, and “what objects does this service own?“.

list_services

List well-known D-Bus service names on a bus.

Parameters

Parameter	Type	Default	Description
bus	string	required	"session" or "system"
include_unique	bool	false	Include unique connection names like :1.42

Return format

Markdown list with a count header, sorted alphabetically.

## D-Bus session bus — 47 services

- `org.freedesktop.DBus`
- `org.freedesktop.Notifications`
- `org.freedesktop.portal.Desktop`
- `org.kde.KWin`
- `org.mpris.MediaPlayer2.firefox`

When include_unique is true, unique connection names (those starting with :) are included in the list alongside well-known names.

Example

list_services(bus="session")

---

introspect

Introspect a D-Bus object to see its interfaces, methods, properties, and signals. Reports progress from 0 to 4 as it connects, introspects, formats, and completes.

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"
include_standard	bool	false	Include standard D-Bus interfaces (Peer, Introspectable, Properties, ObjectManager)

Return format

Markdown document listing each interface with its methods (including in/out argument signatures), properties (with D-Bus type signature and access mode), signals, and child nodes.

## `org.freedesktop.Notifications` at `/org/freedesktop/Notifications`

### Interface: `org.freedesktop.Notifications`

**Methods:**
- `GetCapabilities() -> capabilities: as`
- `Notify(app_name: s, replaces_id: u, app_icon: s, summary: s, body: s, actions: as, hints: a{sv}, expire_timeout: i) -> id: u`
- `CloseNotification(id: u)`
- `GetServerInformation() -> name: s, vendor: s, version: s, spec_version: s`

**Signals:**
- `NotificationClosed(id: u, reason: u)`
- `ActionInvoked(id: u, action_key: s)`

Standard interfaces (org.freedesktop.DBus.Peer, org.freedesktop.DBus.Introspectable, org.freedesktop.DBus.Properties, org.freedesktop.DBus.ObjectManager) are hidden by default. Set include_standard to true to show them.

Example

introspect(
    bus="session",
    service="org.freedesktop.Notifications",
    object_path="/org/freedesktop/Notifications"
)

---

list_objects

Recursively walk the D-Bus object tree for a service using breadth-first search, bounded by depth and node count.

Parameters

Parameter	Type	Default	Description
bus	string	required	"session" or "system"
service	string	required	Service name
root_path	string	"/"	Starting path for the walk
max_depth	int	20	Maximum tree depth to descend

Bounds

The walk enforces two safety limits:

Limit	Value	Behavior when hit
MAX_TREE_NODES	500	Walk stops, output marked as truncated
TOTAL_WALK_TIMEOUT	60 seconds	Walk stops with a warning logged via context

Progress is reported as (nodes_visited, None) during the walk, so clients that support progress tracking can display a counter.

Return format

Sorted list of object paths. Each path shows its non-standard interfaces (standard org.freedesktop.DBus.* interfaces are omitted for clarity). When limits are hit, the header indicates truncation.

## Object tree for `org.freedesktop.systemd1` on system bus — 412 objects

- `/` -- `org.freedesktop.systemd1.Manager`
- `/org/freedesktop/systemd1/job/12345`
- `/org/freedesktop/systemd1/unit/bluetooth_2eservice` -- `org.freedesktop.systemd1.Unit`, `org.freedesktop.systemd1.Service`
- `/org/freedesktop/systemd1/unit/docker_2eservice` -- `org.freedesktop.systemd1.Unit`, `org.freedesktop.systemd1.Service`

When truncated:

## Object tree for `org.bluez` on system bus — 500 objects (truncated at 500)

Example

list_objects(bus="system", service="org.freedesktop.systemd1")

Walk a subtree to narrow results:

list_objects(
    bus="system",
    service="org.freedesktop.systemd1",
    root_path="/org/freedesktop/systemd1/unit",
    max_depth=2
)