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