Send a Tested D-Bus Message with dbus-send

Before you fire a D-Bus method at a real service, run dbus-send against a safe call first to see the reply shape. This guide calls the standard ListNames method, inspects the reply, then shows how to adapt the command for other messages without guessing at argument types.

Allow about ten minutes. You need the dbus-bin package and a running user session bus; the examples are ordinary, unprivileged commands. This guide describes the installed D-Bus 1.14.10 command from Ubuntu package dbus-bin 1.14.10-4ubuntu4.1. The local manpage is the authority for the syntax shown here. D-Bus services and their policy vary by host, so a command that is syntactically valid can still be refused by the destination.

1. Check the command and choose a bus

First confirm which executable your shell will run and view its accepted command shape:

$ command -v dbus-send
/home/linuxbrew/.linuxbrew/bin/dbus-send
$ dbus-send --help
Usage: dbus-send [--help] [--system | --session | --bus=ADDRESS | --peer=ADDRESS] [--sender=NAME] [--dest=NAME] [--type=TYPE] [--print-reply[=literal]] [--reply-timeout=MSEC] <destination object path> <message name> [contents ...]

The command uses the per-user session bus by default. Write --session explicitly in scripts and examples so the choice is visible. Use --system only when the service is on the system bus. A system-bus call can need policy permission, and running dbus-send with sudo does not automatically give you the same user session bus or the same D-Bus identity.

Checkpoint: confirm the package providing the command is installed:

$ dpkg-query -W -f='${Package} ${Version}\n' dbus-bin
dbus-bin 1.14.10-4ubuntu4.1

2. Call a read-only standard method

org.freedesktop.DBus is the bus daemon's standard service. Its object path is /org/freedesktop/DBus, and its ListNames method returns the names currently registered on that bus. Ask for a reply so the call is useful as a smoke test:

$ dbus-send --session \
    --dest=org.freedesktop.DBus \
    --print-reply \
    /org/freedesktop/DBus \
    org.freedesktop.DBus.ListNames
method return time=... sender=org.freedesktop.DBus -> destination=:1.42 serial=...
   array [
      string "org.freedesktop.DBus"
      string ":1.42"
   ]

The serial number and the list of names are host-specific. The useful result is a successful method return containing an array of strings. If no session bus is available, the command reports a connection error. Start or enter a normal graphical or login session, then retry; do not invent a bus address.

--print-reply makes this a method call and waits for the response. Without it, the default message type is a signal, which is not the right shape for requesting a method result. The default reply timeout is implementation-defined and is typically 25 seconds. You can set it explicitly in milliseconds, for example --reply-timeout=5000 for five seconds.

3. Read the command's message shape

Every invocation needs an object path and a message name. The message name is written as INTERFACE.MEMBER, even though D-Bus carries the interface and member as separate protocol fields. In the working example:

Most useful calls need --dest. If you omit it, the message has no destination, so it is not a directed request. The destination must own the name you specify at the time of the call. Check the available names with the read-only command above rather than assuming an application is installed.

To address a signal instead, set --type=signal. Signals do not normally wait for a reply. Sending one can still affect every listener, so treat a signal example as an operational action, not as a harmless way to test syntax.

4. Add typed arguments carefully

Arguments after the message name are type-prefixed values. The installed command accepts string, signed and unsigned 16, 32 and 64-bit integers, double, byte, boolean and objpath. It also accepts non-empty arrays, dictionaries and variants. Shell quoting happens before dbus-send sees the value, so quote a complete argument when it contains spaces.

$ dbus-send --session \
    --dest=org.example.Service \
    --print-reply \
    /org/example/Object \
    org.example.Interface.SetLabel \
    string:"label for review"
Error org.freedesktop.DBus.Error.ServiceUnknown: The name org.example.Service was not provided by any .service files

This is a shape example with an intentionally fictional destination. It demonstrates one string argument, but it cannot succeed until a real service owns the name and documents the method. Do not substitute a real mutating method merely to obtain a successful reply.

For a method that really documents arguments, follow its signature exactly. For example, the syntax for representative values is int32:47, boolean:true, objpath:/org/example/Object, array:string:"one","two" and variant:int32:-8. Empty containers and nested containers are not supported by this command, even though D-Bus itself has a broader type system.

5. Diagnose failures without changing state

Start with the error category, then check the destination, bus and signature. ServiceUnknown usually means no connection owns the requested name. An unknown object or member means the service does not expose the path or method you supplied. AccessDenied is a D-Bus policy decision, not a signal to keep adding privileges.

For a quick, non-mutating check, list names on the exact bus you intend to use and look for the destination:

$ dbus-send --system --dest=org.freedesktop.DBus --print-reply \
    /org/freedesktop/DBus org.freedesktop.DBus.ListNames \
    | grep -F 'org.example.Service'
$ printf 'pipeline status: %s\n' "$?"
pipeline status: 1

An empty result and status 1 mean the name was not found by grep; they do not prove the service is broken. The command above only reads the system bus. It does not start a service or alter its configuration.

Keep the bus choice, destination, object path, member and argument signature together when copying a command. A common distraction is changing several of them at once, then treating the next error as evidence about the wrong part. Change one field, rerun the read-only check, and keep the original command available for comparison.

6. Treat mutating calls as service operations

A successful D-Bus method can stop a service, change a setting, mount a device or alter another user's desktop state. dbus-send has no general undo facility because the destination owns the operation and its recovery rules. Before sending anything that is not clearly read-only, read the service documentation, record the current state, and find its documented reversal. Test against a disposable account or host where possible.

Warning: do not paste untrusted text into a shell command, especially a destination, object path or argument containing shell metacharacters. Quote shell values, but remember quoting only protects the shell. It does not authorise the D-Bus call or make the destination trustworthy. Avoid --sender unless the service specifically requires it: that option requests a well-known name and releases it when dbus-send exits.

Done means