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