Nushell plugin for interacting with D-Bus
1# nu_plugin_dbus
2
3[Nushell](https://nushell.sh/) plugin for interacting with [D-Bus](https://dbus.freedesktop.org/)
4
5With the commands provided by this plugin, you can interact with many of the desktop-oriented
6systems on UNIX-like systems that use D-Bus, including Linux and FreeBSD. You can control media
7players, on-screen displays, power policies, and even administer services.
8
9Nushell provides a particularly nice environment for interacting with D-Bus, as both support typed
10structured data, and interacting with this on a traditional UNIX command line with tools like
11`dbus-send` and `busctl` is cumbersome and tricky to automate.
12
13This plugin automatically determines the correct input types through D-Bus introspection when
14available, unlike either of the aforementioned tools, making it easier to interact with objects on
15the bus without having to implement boilerplate from documentation.
16
17## Install with Cargo
18
19From within nushell:
20
21```nushell
22cargo install --locked nu_plugin_dbus
23plugin add ~/.cargo/bin/nu_plugin_dbus
24plugin use dbus # or restart nu
25```
26
27## Usage
28
29 Commands for interacting with D-Bus
30
31 Search terms: dbus
32
33 Usage:
34 > dbus
35
36 Subcommands:
37 dbus call - Call a method and get its response
38 dbus get - Get a D-Bus property
39 dbus get-all - Get all D-Bus properties for the given object
40 dbus introspect - Introspect a D-Bus object
41 dbus list - List all available connection names on the bus
42 dbus set - Set a D-Bus property
43
44 Flags:
45 -h, --help - Display the help message for this command
46
47# `dbus call`
48
49 Call a method and get its response
50
51 Returns an array if the method call returns more than one value.
52
53 Search terms: dbus
54
55 Usage:
56 > dbus call {flags} <object> <interface> <method> ...(args)
57
58 Flags:
59 -h, --help - Display the help message for this command
60 --session - Send to the session message bus (default)
61 --system - Send to the system message bus
62 --started - Send to the bus that started this process, if applicable
63 --bus <String> - Send to the bus server at the given address
64 --peer <String> - Send to a non-bus D-Bus server at the given address. Will not call the Hello method on initialization.
65 --timeout <Duration> - How long to wait for a response
66 --signature <String> - Signature of the arguments to send, in D-Bus format.
67 If not provided, they will be determined from introspection.
68 If --no-introspect is specified and this is not provided, they will be guessed (poorly)
69 --no-flatten - Always return a list of all return values
70 --no-introspect - Don't use introspection to determine the correct argument signature
71 --dest (required parameter) <String> - The name of the connection to send the method to
72
73 Parameters:
74 object <string>: The path to the object to call the method on
75 interface <string>: The name of the interface the method belongs to
76 method <string>: The name of the method to send
77 ...args <any>: Arguments to send with the method call
78
79 Input/output types:
80 ╭───┬─────────┬────────╮
81 │ # │ input │ output │
82 ├───┼─────────┼────────┤
83 │ 0 │ nothing │ any │
84 ╰───┴─────────┴────────╯
85
86 Examples:
87 Ping the D-Bus server itself
88 > dbus call --dest=org.freedesktop.DBus /org/freedesktop/DBus org.freedesktop.DBus.Peer Ping
89
90 Show a notification on the desktop for 5 seconds
91 > dbus call --dest=org.freedesktop.Notifications /org/freedesktop/Notifications org.freedesktop.Notifications Notify "Floppy disks" 0 "media-floppy" "Rarely seen" "But sometimes still used" [] {} 5000
92
93# `dbus get`
94
95 Get a D-Bus property
96
97 Search terms: dbus
98
99 Usage:
100 > dbus get {flags} <object> <interface> <property>
101
102 Flags:
103 -h, --help - Display the help message for this command
104 --session - Send to the session message bus (default)
105 --system - Send to the system message bus
106 --started - Send to the bus that started this process, if applicable
107 --bus <String> - Send to the bus server at the given address
108 --peer <String> - Send to a non-bus D-Bus server at the given address. Will not call the Hello method on initialization.
109 --timeout <Duration> - How long to wait for a response
110 --dest (required parameter) <String> - The name of the connection to read the property from
111
112 Parameters:
113 object <string>: The path to the object to read the property from
114 interface <string>: The name of the interface the property belongs to
115 property <string>: The name of the property to read
116
117 Input/output types:
118 ╭───┬─────────┬────────╮
119 │ # │ input │ output │
120 ├───┼─────────┼────────┤
121 │ 0 │ nothing │ any │
122 ╰───┴─────────┴────────╯
123
124 Examples:
125 Get the currently playing song in Spotify
126 > dbus get --dest=org.mpris.MediaPlayer2.spotify /org/mpris/MediaPlayer2 org.mpris.MediaPlayer2.Player Metadata
127 ╭──────────────┬───────────────────────────────────────────────────────╮
128 │ xesam:title │ Birdie │
129 │ xesam:artist │ [list 1 item] │
130 │ xesam:album │ Love Your Love │
131 │ xesam:url │ https://open.spotify.com/track/51748BvzeeMs4PIdPuyZmv │
132 ╰──────────────┴───────────────────────────────────────────────────────╯
133
134# `dbus get-all`
135
136 Get all D-Bus properties for the given object
137
138 Search terms: dbus
139
140 Usage:
141 > dbus get-all {flags} <object> <interface>
142
143 Flags:
144 -h, --help - Display the help message for this command
145 --session - Send to the session message bus (default)
146 --system - Send to the system message bus
147 --started - Send to the bus that started this process, if applicable
148 --bus <String> - Send to the bus server at the given address
149 --peer <String> - Send to a non-bus D-Bus server at the given address. Will not call the Hello method on initialization.
150 --timeout <Duration> - How long to wait for a response
151 --dest (required parameter) <String> - The name of the connection to read the property from
152
153 Parameters:
154 object <string>: The path to the object to read the property from
155 interface <string>: The name of the interface the property belongs to
156
157 Input/output types:
158 ╭───┬─────────┬────────╮
159 │ # │ input │ output │
160 ├───┼─────────┼────────┤
161 │ 0 │ nothing │ record │
162 ╰───┴─────────┴────────╯
163
164 Examples:
165 Get the current player state of Spotify
166 > dbus get-all --dest=org.mpris.MediaPlayer2.spotify /org/mpris/MediaPlayer2 org.mpris.MediaPlayer2.Player
167 ╭────────────────┬────────╮
168 │ CanPlay │ true │
169 │ Volume │ 0.43 │
170 │ PlaybackStatus │ Paused │
171 ╰────────────────┴────────╯
172
173# `dbus introspect`
174
175 Introspect a D-Bus object
176
177 Returns information about available nodes, interfaces, methods, signals, and properties on the given object path
178
179 Search terms: dbus
180
181 Usage:
182 > dbus introspect {flags} <object>
183
184 Flags:
185 -h, --help - Display the help message for this command
186 --session - Send to the session message bus (default)
187 --system - Send to the system message bus
188 --started - Send to the bus that started this process, if applicable
189 --bus <String> - Send to the bus server at the given address
190 --peer <String> - Send to a non-bus D-Bus server at the given address. Will not call the Hello method on initialization.
191 --timeout <Duration> - How long to wait for a response
192 --dest (required parameter) <String> - The name of the connection that owns the object
193
194 Parameters:
195 object <string>: The path to the object to introspect
196
197 Input/output types:
198 ╭───┬─────────┬────────╮
199 │ # │ input │ output │
200 ├───┼─────────┼────────┤
201 │ 0 │ nothing │ record │
202 ╰───┴─────────┴────────╯
203
204 Examples:
205 Look at the MPRIS2 interfaces exposed by Spotify
206 > dbus introspect --dest=org.mpris.MediaPlayer2.spotify /org/mpris/MediaPlayer2 | explore
207
208 Get methods exposed by KDE Plasma's on-screen display service
209 > dbus introspect --dest=org.kde.plasmashell /org/kde/osdService | get interfaces | where name == org.kde.osdService | get 0.methods
210
211 List objects exposed by KWin
212 > dbus introspect --dest=org.kde.KWin / | get children | select name
213
214# `dbus list`
215
216 List all available connection names on the bus
217
218 These can be used as arguments for --dest on any of the other commands.
219
220 Search terms: dbus
221
222 Usage:
223 > dbus list {flags} (pattern)
224
225 Flags:
226 -h, --help - Display the help message for this command
227 --session - Send to the session message bus (default)
228 --system - Send to the system message bus
229 --started - Send to the bus that started this process, if applicable
230 --bus <String> - Send to the bus server at the given address
231 --peer <String> - Send to a non-bus D-Bus server at the given address. Will not call the Hello method on initialization.
232 --timeout <Duration> - How long to wait for a response
233
234 Parameters:
235 pattern <string>: An optional glob-like pattern to filter the result by (optional)
236
237 Input/output types:
238 ╭───┬─────────┬──────────────╮
239 │ # │ input │ output │
240 ├───┼─────────┼──────────────┤
241 │ 0 │ nothing │ list<string> │
242 ╰───┴─────────┴──────────────╯
243
244 Examples:
245 List all names available on the bus
246 > dbus list
247
248 List top-level freedesktop.org names on the bus (e.g. matches `org.freedesktop.PowerManagement`, but not `org.freedesktop.Management.Inhibit`)
249 > dbus list org.freedesktop.*
250 ╭───┬───────────────────────────────╮
251 │ 0 │ org.freedesktop.DBus │
252 │ 1 │ org.freedesktop.Flatpak │
253 │ 2 │ org.freedesktop.Notifications │
254 ╰───┴───────────────────────────────╯
255
256 List all MPRIS2 media players on the bus
257 > dbus list org.mpris.MediaPlayer2.**
258 ╭───┬────────────────────────────────────────────────╮
259 │ 0 │ org.mpris.MediaPlayer2.spotify │
260 │ 1 │ org.mpris.MediaPlayer2.kdeconnect.mpris_000001 │
261 ╰───┴────────────────────────────────────────────────╯
262
263# `dbus set`
264
265 Set a D-Bus property
266
267 Search terms: dbus
268
269 Usage:
270 > dbus set {flags} <object> <interface> <property> <value>
271
272 Flags:
273 -h, --help - Display the help message for this command
274 --session - Send to the session message bus (default)
275 --system - Send to the system message bus
276 --started - Send to the bus that started this process, if applicable
277 --bus <String> - Send to the bus server at the given address
278 --peer <String> - Send to a non-bus D-Bus server at the given address. Will not call the Hello method on initialization.
279 --timeout <Duration> - How long to wait for a response
280 --signature <String> - Signature of the value to set, in D-Bus format.
281 If not provided, it will be determined from introspection.
282 If --no-introspect is specified and this is not provided, it will be guessed (poorly)
283 --dest (required parameter) <String> - The name of the connection to write the property on
284
285 Parameters:
286 object <string>: The path to the object to write the property on
287 interface <string>: The name of the interface the property belongs to
288 property <string>: The name of the property to write
289 value <any>: The value to write to the property
290
291 Input/output types:
292 ╭───┬─────────┬─────────╮
293 │ # │ input │ output │
294 ├───┼─────────┼─────────┤
295 │ 0 │ nothing │ nothing │
296 ╰───┴─────────┴─────────╯
297
298 Examples:
299 Set the volume of Spotify to 50%
300 > dbus set --dest=org.mpris.MediaPlayer2.spotify /org/mpris/MediaPlayer2 org.mpris.MediaPlayer2.Player Volume 0.5
301