Nushell plugin for interacting with D-Bus
Improve docs
+120
-57
+111
-54
README.md
+111
-54
README.md
···
1
1
# nu_plugin_dbus
2
2
3
+
[Nushell](https://nushell.sh/) plugin for interacting with [D-Bus](https://dbus.freedesktop.org/)
4
+
5
+
With the commands provided by this plugin, you can interact with many of the desktop-oriented
6
+
systems on UNIX-like systems that use D-Bus, including Linux and FreeBSD. You can control media
7
+
players, on-screen displays, power policies, and even administer services.
8
+
9
+
Nushell provides a particularly nice environment for interacting with D-Bus, as both support typed
10
+
structured 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
+
13
+
This plugin automatically determines the correct input types through D-Bus introspection when
14
+
available, unlike either of the aforementioned tools, making it easier to interact with objects on
15
+
the bus without having to implement boilerplate from documentation.
16
+
3
17
## Install with Cargo
4
18
5
19
Run: `cargo install --locked nu_plugin_dbus`
···
18
32
Subcommands:
19
33
dbus call - Call a method and get its response
20
34
dbus get - Get a D-Bus property
21
-
dbus get-all - Get all D-Bus property for the given objects
35
+
dbus get-all - Get all D-Bus properties for the given object
22
36
dbus introspect - Introspect a D-Bus object
23
37
dbus list - List all available connection names on the bus
24
-
dbus set - Get all D-Bus property for the given objects
25
-
26
-
Flags:
27
-
-h, --help - Display the help message for this command
28
-
29
-
## `dbus introspect`
30
-
31
-
Introspect a D-Bus object
32
-
33
-
Returns information about available nodes, interfaces, methods, signals, and properties on the given object path
34
-
35
-
Search terms: dbus
36
-
37
-
Usage:
38
-
> dbus introspect {flags} <object>
38
+
dbus set - Set a D-Bus property
39
39
40
40
Flags:
41
41
-h, --help - Display the help message for this command
42
-
--session - Send to the session message bus (default)
43
-
--system - Send to the system message bus
44
-
--started - Send to the bus that started this process, if applicable
45
-
--bus <String> - Send to the bus server at the given address
46
-
--peer <String> - Send to a non-bus D-Bus server at the given address. Will not call the Hello method on initialization.
47
-
--timeout <Duration> - How long to wait for a response
48
-
--dest (required parameter) <String> - The name of the connection that owns the object
49
42
50
-
Parameters:
51
-
object <string>: The path to the object to introspect
52
-
53
-
Examples:
54
-
Look at the MPRIS2 interfaces exposed by Spotify
55
-
> dbus introspect --dest=org.mpris.MediaPlayer2.spotify /org/mpris/MediaPlayer2 | explore
56
-
57
-
Get methods exposed by KDE Plasma's on-screen display service
58
-
> dbus introspect --dest=org.kde.plasmashell /org/kde/osdService | get interfaces | where name == org.kde.osdService | get 0.methods
59
-
60
-
List objects exposed by KWin
61
-
> dbus introspect --dest=org.kde.KWin / | get children | select name
62
-
63
-
## `dbus call`
43
+
# `dbus call`
64
44
65
45
Call a method and get its response
66
46
···
92
72
method <string>: The name of the method to send
93
73
...args <any>: Arguments to send with the method call
94
74
75
+
Input/output types:
76
+
╭───┬─────────┬────────╮
77
+
│ # │ input │ output │
78
+
├───┼─────────┼────────┤
79
+
│ 0 │ nothing │ any │
80
+
╰───┴─────────┴────────╯
81
+
95
82
Examples:
96
83
Ping the D-Bus server itself
97
84
> dbus call --dest=org.freedesktop.DBus /org/freedesktop/DBus org.freedesktop.DBus.Peer Ping
···
99
86
Show a notification on the desktop for 5 seconds
100
87
> 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
101
88
102
-
## `dbus get`
89
+
# `dbus get`
103
90
104
91
Get a D-Bus property
105
92
···
123
110
interface <string>: The name of the interface the property belongs to
124
111
property <string>: The name of the property to read
125
112
113
+
Input/output types:
114
+
╭───┬─────────┬────────╮
115
+
│ # │ input │ output │
116
+
├───┼─────────┼────────┤
117
+
│ 0 │ nothing │ any │
118
+
╰───┴─────────┴────────╯
119
+
126
120
Examples:
127
121
Get the currently playing song in Spotify
128
122
> dbus get --dest=org.mpris.MediaPlayer2.spotify /org/mpris/MediaPlayer2 org.mpris.MediaPlayer2.Player Metadata
···
133
127
│ xesam:url │ https://open.spotify.com/track/51748BvzeeMs4PIdPuyZmv │
134
128
╰──────────────┴───────────────────────────────────────────────────────╯
135
129
136
-
## `dbus get-all`
130
+
# `dbus get-all`
137
131
138
-
Get all D-Bus property for the given objects
132
+
Get all D-Bus properties for the given object
139
133
140
134
Search terms: dbus
141
135
···
156
150
object <string>: The path to the object to read the property from
157
151
interface <string>: The name of the interface the property belongs to
158
152
153
+
Input/output types:
154
+
╭───┬─────────┬────────╮
155
+
│ # │ input │ output │
156
+
├───┼─────────┼────────┤
157
+
│ 0 │ nothing │ record │
158
+
╰───┴─────────┴────────╯
159
+
159
160
Examples:
160
161
Get the current player state of Spotify
161
162
> dbus get-all --dest=org.mpris.MediaPlayer2.spotify /org/mpris/MediaPlayer2 org.mpris.MediaPlayer2.Player
···
165
166
│ PlaybackStatus │ Paused │
166
167
╰────────────────┴────────╯
167
168
168
-
## `dbus set`
169
+
# `dbus introspect`
170
+
171
+
Introspect a D-Bus object
169
172
170
-
Get all D-Bus property for the given objects
173
+
Returns information about available nodes, interfaces, methods, signals, and properties on the given object path
171
174
172
175
Search terms: dbus
173
176
174
177
Usage:
175
-
> dbus set {flags} <object> <interface> <property> <value>
178
+
> dbus introspect {flags} <object>
176
179
177
180
Flags:
178
181
-h, --help - Display the help message for this command
···
182
185
--bus <String> - Send to the bus server at the given address
183
186
--peer <String> - Send to a non-bus D-Bus server at the given address. Will not call the Hello method on initialization.
184
187
--timeout <Duration> - How long to wait for a response
185
-
--signature <String> - Signature of the value to set, in D-Bus format.
186
-
If not provided, it will be determined from introspection.
187
-
If --no-introspect is specified and this is not provided, it will be guessed (poorly)
188
-
--dest (required parameter) <String> - The name of the connection to write the property on
188
+
--dest (required parameter) <String> - The name of the connection that owns the object
189
189
190
190
Parameters:
191
-
object <string>: The path to the object to write the property on
192
-
interface <string>: The name of the interface the property belongs to
193
-
property <string>: The name of the property to write
194
-
value <any>: The value to write to the property
191
+
object <string>: The path to the object to introspect
192
+
193
+
Input/output types:
194
+
╭───┬─────────┬────────╮
195
+
│ # │ input │ output │
196
+
├───┼─────────┼────────┤
197
+
│ 0 │ nothing │ record │
198
+
╰───┴─────────┴────────╯
195
199
196
200
Examples:
197
-
Set the volume of Spotify to 50%
198
-
> dbus set --dest=org.mpris.MediaPlayer2.spotify /org/mpris/MediaPlayer2 org.mpris.MediaPlayer2.Player Volume 0.5
201
+
Look at the MPRIS2 interfaces exposed by Spotify
202
+
> dbus introspect --dest=org.mpris.MediaPlayer2.spotify /org/mpris/MediaPlayer2 | explore
199
203
200
-
## `dbus list`
204
+
Get methods exposed by KDE Plasma's on-screen display service
205
+
> dbus introspect --dest=org.kde.plasmashell /org/kde/osdService | get interfaces | where name == org.kde.osdService | get 0.methods
206
+
207
+
List objects exposed by KWin
208
+
> dbus introspect --dest=org.kde.KWin / | get children | select name
209
+
210
+
# `dbus list`
201
211
202
212
List all available connection names on the bus
203
213
···
220
230
Parameters:
221
231
pattern <string>: An optional glob-like pattern to filter the result by (optional)
222
232
233
+
Input/output types:
234
+
╭───┬─────────┬──────────────╮
235
+
│ # │ input │ output │
236
+
├───┼─────────┼──────────────┤
237
+
│ 0 │ nothing │ list<string> │
238
+
╰───┴─────────┴──────────────╯
239
+
223
240
Examples:
224
241
List all names available on the bus
225
242
> dbus list
···
238
255
│ 0 │ org.mpris.MediaPlayer2.spotify │
239
256
│ 1 │ org.mpris.MediaPlayer2.kdeconnect.mpris_000001 │
240
257
╰───┴────────────────────────────────────────────────╯
258
+
259
+
# `dbus set`
260
+
261
+
Set a D-Bus property
262
+
263
+
Search terms: dbus
264
+
265
+
Usage:
266
+
> dbus set {flags} <object> <interface> <property> <value>
267
+
268
+
Flags:
269
+
-h, --help - Display the help message for this command
270
+
--session - Send to the session message bus (default)
271
+
--system - Send to the system message bus
272
+
--started - Send to the bus that started this process, if applicable
273
+
--bus <String> - Send to the bus server at the given address
274
+
--peer <String> - Send to a non-bus D-Bus server at the given address. Will not call the Hello method on initialization.
275
+
--timeout <Duration> - How long to wait for a response
276
+
--signature <String> - Signature of the value to set, in D-Bus format.
277
+
If not provided, it will be determined from introspection.
278
+
If --no-introspect is specified and this is not provided, it will be guessed (poorly)
279
+
--dest (required parameter) <String> - The name of the connection to write the property on
280
+
281
+
Parameters:
282
+
object <string>: The path to the object to write the property on
283
+
interface <string>: The name of the interface the property belongs to
284
+
property <string>: The name of the property to write
285
+
value <any>: The value to write to the property
286
+
287
+
Input/output types:
288
+
╭───┬─────────┬─────────╮
289
+
│ # │ input │ output │
290
+
├───┼─────────┼─────────┤
291
+
│ 0 │ nothing │ nothing │
292
+
╰───┴─────────┴─────────╯
293
+
294
+
Examples:
295
+
Set the volume of Spotify to 50%
296
+
> dbus set --dest=org.mpris.MediaPlayer2.spotify /org/mpris/MediaPlayer2 org.mpris.MediaPlayer2.Player Volume 0.5
297
+
+9
-3
src/main.rs
+9
-3
src/main.rs
···
1
1
use nu_plugin::{serve_plugin, MsgPackSerializer, Plugin, EvaluatedCall, LabeledError};
2
-
use nu_protocol::{PluginSignature, Value, SyntaxShape, PluginExample, Span};
2
+
use nu_protocol::{PluginSignature, Value, SyntaxShape, PluginExample, Span, Type};
3
3
4
4
mod config;
5
5
mod client;
···
34
34
.accepts_dbus_client_options()
35
35
.accepts_timeout()
36
36
.usage("Introspect a D-Bus object")
37
+
.input_output_type(Type::Nothing, Type::Record(vec![]))
37
38
.extra_usage("Returns information about available nodes, interfaces, methods, \
38
39
signals, and properties on the given object path")
39
40
.required_named("dest", SyntaxShape::String,
···
69
70
.accepts_timeout()
70
71
.usage("Call a method and get its response")
71
72
.extra_usage("Returns an array if the method call returns more than one value.")
73
+
.input_output_type(Type::Nothing, Type::Any)
72
74
.named("signature", SyntaxShape::String,
73
75
"Signature of the arguments to send, in D-Bus format.\n \
74
76
If not provided, they will be determined from introspection.\n \
···
110
112
.accepts_dbus_client_options()
111
113
.accepts_timeout()
112
114
.usage("Get a D-Bus property")
115
+
.input_output_type(Type::Nothing, Type::Any)
113
116
.required_named("dest", SyntaxShape::String,
114
117
"The name of the connection to read the property from",
115
118
None)
···
139
142
.is_dbus_command()
140
143
.accepts_dbus_client_options()
141
144
.accepts_timeout()
142
-
.usage("Get all D-Bus property for the given objects")
145
+
.usage("Get all D-Bus properties for the given object")
146
+
.input_output_type(Type::Nothing, Type::Record(vec![]))
143
147
.required_named("dest", SyntaxShape::String,
144
148
"The name of the connection to read the property from",
145
149
None)
···
164
168
.is_dbus_command()
165
169
.accepts_dbus_client_options()
166
170
.accepts_timeout()
167
-
.usage("Get all D-Bus property for the given objects")
171
+
.usage("Set a D-Bus property")
172
+
.input_output_type(Type::Nothing, Type::Nothing)
168
173
.named("signature", SyntaxShape::String,
169
174
"Signature of the value to set, in D-Bus format.\n \
170
175
If not provided, it will be determined from introspection.\n \
···
196
201
.accepts_timeout()
197
202
.usage("List all available connection names on the bus")
198
203
.extra_usage("These can be used as arguments for --dest on any of the other commands.")
204
+
.input_output_type(Type::Nothing, Type::List(Type::String.into()))
199
205
.optional("pattern", SyntaxShape::String,
200
206
"An optional glob-like pattern to filter the result by")
201
207
.plugin_examples(vec![