Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/devyn/nu_plugin_dbus

Nushell plugin for interacting with D-Bus
https://github.com/devyn/nu_plugin_dbus

Last synced: 3 months ago
JSON representation

Nushell plugin for interacting with D-Bus

Host: GitHub
URL: https://github.com/devyn/nu_plugin_dbus
Owner: devyn
License: mit
Created: 2024-01-29T20:27:03.000Z (12 months ago)
Default Branch: main
Last Pushed: 2024-10-16T06:54:48.000Z (3 months ago)
Last Synced: 2024-10-18T01:29:02.189Z (3 months ago)
Language: Rust
Size: 104 KB
Stars: 13
Watchers: 1
Forks: 1
Open Issues: 0
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

awesome-nu - nu_plugin_dbus - Bus. (Plugins)

README

# nu_plugin_dbus

[Nushell](https://nushell.sh/) plugin for interacting with [D-Bus](https://dbus.freedesktop.org/)

With the commands provided by this plugin, you can interact with many of the desktop-oriented
systems on UNIX-like systems that use D-Bus, including Linux and FreeBSD. You can control media
players, on-screen displays, power policies, and even administer services.

Nushell provides a particularly nice environment for interacting with D-Bus, as both support typed
structured data, and interacting with this on a traditional UNIX command line with tools like
`dbus-send` and `busctl` is cumbersome and tricky to automate.

This plugin automatically determines the correct input types through D-Bus introspection when
available, unlike either of the aforementioned tools, making it easier to interact with objects on
the bus without having to implement boilerplate from documentation.

## Install with Cargo

From within nushell:

```nushell
cargo install --locked nu_plugin_dbus
plugin add ~/.cargo/bin/nu_plugin_dbus
plugin use dbus # or restart nu
```

## Usage

Commands for interacting with D-Bus

Search terms: dbus

Usage:
> dbus

Subcommands:
dbus call - Call a method and get its response
dbus get - Get a D-Bus property
dbus get-all - Get all D-Bus properties for the given object
dbus introspect - Introspect a D-Bus object
dbus list - List all available connection names on the bus
dbus set - Set a D-Bus property

Flags:
-h, --help - Display the help message for this command

# `dbus call`

Call a method and get its response

Returns an array if the method call returns more than one value.

Search terms: dbus

Usage:
> dbus call {flags} ...(args)

Flags:
-h, --help - Display the help message for this command
--session - Send to the session message bus (default)
--system - Send to the system message bus
--started - Send to the bus that started this process, if applicable
--bus - Send to the bus server at the given address
--peer - Send to a non-bus D-Bus server at the given address. Will not call the Hello method on initialization.
--timeout - How long to wait for a response
--signature - Signature of the arguments to send, in D-Bus format.
If not provided, they will be determined from introspection.
If --no-introspect is specified and this is not provided, they will be guessed (poorly)
--no-flatten - Always return a list of all return values
--no-introspect - Don't use introspection to determine the correct argument signature
--dest (required parameter) - The name of the connection to send the method to

Parameters:
object : The path to the object to call the method on
interface : The name of the interface the method belongs to
method : The name of the method to send
...args : Arguments to send with the method call

Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ any │
╰───┴─────────┴────────╯

Examples:
Ping the D-Bus server itself
> dbus call --dest=org.freedesktop.DBus /org/freedesktop/DBus org.freedesktop.DBus.Peer Ping

Show a notification on the desktop for 5 seconds
> 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

# `dbus get`

Get a D-Bus property

Search terms: dbus

Usage:
> dbus get {flags}

Parameters:
object : The path to the object to read the property from
interface : The name of the interface the property belongs to
property : The name of the property to read

Examples:
Get the currently playing song in Spotify
> dbus get --dest=org.mpris.MediaPlayer2.spotify /org/mpris/MediaPlayer2 org.mpris.MediaPlayer2.Player Metadata
╭──────────────┬───────────────────────────────────────────────────────╮
│ xesam:title │ Birdie │
│ xesam:artist │ [list 1 item] │
│ xesam:album │ Love Your Love │
│ xesam:url │ https://open.spotify.com/track/51748BvzeeMs4PIdPuyZmv │
╰──────────────┴───────────────────────────────────────────────────────╯

# `dbus get-all`

Get all D-Bus properties for the given object

Search terms: dbus

Usage:
> dbus get-all {flags}

Parameters:
object : The path to the object to read the property from
interface : The name of the interface the property belongs to

Input/output types:
╭───┬─────────┬────────╮
│ # │ input │ output │
├───┼─────────┼────────┤
│ 0 │ nothing │ record │
╰───┴─────────┴────────╯

Examples:
Get the current player state of Spotify
> dbus get-all --dest=org.mpris.MediaPlayer2.spotify /org/mpris/MediaPlayer2 org.mpris.MediaPlayer2.Player
╭────────────────┬────────╮
│ CanPlay │ true │
│ Volume │ 0.43 │
│ PlaybackStatus │ Paused │
╰────────────────┴────────╯

# `dbus introspect`

Introspect a D-Bus object

Returns information about available nodes, interfaces, methods, signals, and properties on the given object path

Search terms: dbus

Usage:
> dbus introspect {flags}

Parameters:
object : The path to the object to introspect

Examples:
Look at the MPRIS2 interfaces exposed by Spotify
> dbus introspect --dest=org.mpris.MediaPlayer2.spotify /org/mpris/MediaPlayer2 | explore

Get methods exposed by KDE Plasma's on-screen display service
> dbus introspect --dest=org.kde.plasmashell /org/kde/osdService | get interfaces | where name == org.kde.osdService | get 0.methods

List objects exposed by KWin
> dbus introspect --dest=org.kde.KWin / | get children | select name

# `dbus list`

List all available connection names on the bus

These can be used as arguments for --dest on any of the other commands.

Search terms: dbus

Usage:
> dbus list {flags} (pattern)

Parameters:
pattern : An optional glob-like pattern to filter the result by (optional)

Input/output types:
╭───┬─────────┬──────────────╮
│ # │ input │ output │
├───┼─────────┼──────────────┤
│ 0 │ nothing │ list │
╰───┴─────────┴──────────────╯

Examples:
List all names available on the bus
> dbus list

List top-level freedesktop.org names on the bus (e.g. matches `org.freedesktop.PowerManagement`, but not `org.freedesktop.Management.Inhibit`)
> dbus list org.freedesktop.*
╭───┬───────────────────────────────╮
│ 0 │ org.freedesktop.DBus │
│ 1 │ org.freedesktop.Flatpak │
│ 2 │ org.freedesktop.Notifications │
╰───┴───────────────────────────────╯

List all MPRIS2 media players on the bus
> dbus list org.mpris.MediaPlayer2.**
╭───┬────────────────────────────────────────────────╮
│ 0 │ org.mpris.MediaPlayer2.spotify │
│ 1 │ org.mpris.MediaPlayer2.kdeconnect.mpris_000001 │
╰───┴────────────────────────────────────────────────╯

# `dbus set`

Set a D-Bus property

Search terms: dbus

Usage:
> dbus set {flags}

Flags:
-h, --help - Display the help message for this command
--session - Send to the session message bus (default)
--system - Send to the system message bus
--started - Send to the bus that started this process, if applicable
--bus - Send to the bus server at the given address
--peer - Send to a non-bus D-Bus server at the given address. Will not call the Hello method on initialization.
--timeout - How long to wait for a response
--signature - Signature of the value to set, in D-Bus format.
If not provided, it will be determined from introspection.
If --no-introspect is specified and this is not provided, it will be guessed (poorly)
--dest (required parameter) - The name of the connection to write the property on

Parameters:
object : The path to the object to write the property on
interface : The name of the interface the property belongs to
property : The name of the property to write
value : The value to write to the property

Input/output types:
╭───┬─────────┬─────────╮
│ # │ input │ output │
├───┼─────────┼─────────┤
│ 0 │ nothing │ nothing │
╰───┴─────────┴─────────╯

Examples:
Set the volume of Spotify to 50%
> dbus set --dest=org.mpris.MediaPlayer2.spotify /org/mpris/MediaPlayer2 org.mpris.MediaPlayer2.Player Volume 0.5