# desktopctl *"A desktop environment for window managers"* Using a window manager (i3/sway/awesome/etc) should not mean that one has to completely reinvent the wheel and manage a strange collection of one-liners to get wifi status or to see if headphones are connected. This project aims to be a solution to this problem. Some of these tools are simple one-liners, some are more complex. The idea is to create a suite of platform-independent (Distro/Desktop Environment independent) tools to get and set system information. Similar in nature to [neofetch](https://github.com/dylanaraps/neofetch), but also allows for *setting* information too (not just *getting*). ### Project status The code is not particularly robust. It can and will fail in non-obvious ways if certain utility programs are not installed. Notably, this program assumes certain permissions are granted to the user. For example, to change the brightness in Archlinux, the user must be part of the `video` group; or to non-interactively change the time zone with `timedatectl` one needs a polkit rule. ### Features * **Session Authentication** Show session authentication status * **Backlight Manager** Get and set backlight * **Battery Manager** Get battery status * **Bluetooth Manager** Get and set Bluetooth * **Colour picker** Colour picker * **CPU frequency** Get CPU frequency * **Headphone indicator** Get whether headpones are plugged in * **IP Address** Get local IP address * **Media Watch Time** Print total media time of listed files * **Memory** Get memory usage * **Monitor Directories/Files** Monitor directories/files * **Check if online** Get current internet connection status * **Screenshots** Take screenshots * **Sound Manager** Get and set sound * **Internet speedtest** Show current internet speed * **SSH** List ssh clients on local network * **Time zone** Get and set current time zone * **Wifi Status** Set wifi on/off Limited features * **Configuration file differences** Show configuration file differences (Archlinux only) * **Power Manager** Set power and charging profiles (Dell only) * **Reboot check** List programs that need to be restarted (Archlinux only) * **Xwayland clients** List number of xwayland clients (Sway only) --- ### Configuring The configuration is read from `~/.config/desktopctl/desktopctlrc`. --- #### Session Authentication Show session Prints whether the session is [correctly authenticated](https://wiki.archlinux.org/title/General_troubleshooting#Session_permissions) using `loginctl`. Arguments: None #### Backlight Manager Get and set backlight Is configured to give non-linear brightness changes with a very simple interface. Can easily be bound to keyboard brightness keys. ``` Arguments: NUMBER, Set backlight to NUMBER percentage. +NUMBER, Increase backlight percentage by NUMBER. -NUMBER, Decrease backlight percentage by NUMBER. +, Go to the next backlight intensity level. -, Go to the previous backlight intensity level. -p, --print, Print current backlight percentages. -n, --notify, Send desktop notification with current backlight intensity. -h, --help, Display this help. ``` Changes are made with `xbacklight` under the hood. The brightness profile can be configured by setting `$BACKLIGHT_LEVELS` in the configuration file. The default is ``` BACKLIGHT_LEVELS=(0 1 2 3 4 5 6 7 8 9 10 15 20 25 30 40 50 60 70 80 90 100) ``` (Small steps at lower brightnesses and larger steps at higher brightnesses) #### Battery Manager Get battery status Gives very detailed statistics about the battery usage rate. Useful for building a status line. Comes shipped with a default status line. ``` Arguments: power, Current power usage (in W) voltage, Current battery voltage (in uV) current, Current battery current (in uA) capacity, Current battery capacity (in %) charge, Current battery capacity (in C) charging, Exit value 0 if charging charged, Exit value 0 if fully charged remaining, If on battery: remaining time until battery depleted If charging: remaining time until battery full (Human readable string) info, Statusline like information about battery (May need correct font configuration) ``` Configure battery icons with `$BATTERY_LEVELS_CHARGING` and `$BATTERY_LEVELS`. The defaults are set using [Overpass Mono Nerd Fonts](https://github.com/ryanoasis/nerd-fonts). ``` BATTERY_LEVELS_CHARGING=(󰂆 󰂆 󰂇 󰂈 󰂉 󰂊 󰂊 󰂋 󰂋 󰂅 ) BATTERY_LEVELS=(󰁺 󰁻 󰁼 󰁽 󰁾 󰁿 󰂀 󰂁 󰂂 󰁹 ) ``` (You may not be able to see these in browser) #### Bluetooth Manager Get and set Bluetooth ``` Arguments: on, Power bluetooth on off, Power bluetooth off --daemon, daemon, Interact with the bluetooth daemon -i, --indicator, Print current bluetooth connection indicator -l, --list, list, List connected bluetooth devicees -r, --restart, restart, Restart bluetooth -c, --connect, connect, Connect to bluetooth device -d, --disconnect, disconnect, Connect to bluetooth device -h, --help, help, Print this help ``` To display battery status of bluetooth devices, experimental features must be enabled in `/etc/bluetooth/main.conf` in the `[General]` section by setting ``` Experimental = true ``` Allows configuring bluetooth from the command line whilst aliasing devices with nice names. For example ``` desktopctl bluetooth connect sony-headphones ``` Instead of ``` bluetooth on bluetoothctl agent on bluetoothctl default-agent # Find out the MAC address of your Bluetooth device # Suppose it is 00:23:02:C0:A9:6F bluetoothctl connect 00:23:02:C0:A9:6F ``` These aliases are defined in the configuration file with a function which must be called `desktopctl.bt.config` and should return from an alias the correct MAC address. Here is an example ``` # Inside ~/.config/desktopctl/desktopctlrc desktopctl.bt.config () { case "$1" in aukey) ID=00:23:02:C0:A9:6F ;; soundcore) ID=08:EB:ED:5F:37:28 ;; dell-keyboard) ID=ED:DD:9A:5F:57:DB ;; dell-mouse) ID=EE:79:C0:96:C5:C3 ;; hr) ID=DA:80:4B:56:CE:4E ;; sony) ID=38:18:4C:BE:BB:00 ;; jlab) ID=00:23:10:0C:74:47 ;; wacom) ID=DC:2C:26:09:C7:70 ;; shokz) ID=C0:86:B3:57:39:67 ;; *) ID=$1 ;; esac } ```` Bluetooth is also quite fragile. Often one needs to restart to make things work. This script handles this automatically. May require polkit rule to allow restarting bluetooth without password This rule will allow any user in the `wheel` group to restart the systemd `bluetooth.service`. ``` polkit.addRule(function(action, subject) { if (action.id == "org.freedesktop.systemd1.manage-units" && subject.isInGroup("wheel") && action.lookup("unit") == "bluetooth.service") { return polkit.Result.YES; }; }); ``` #### Colour picker Simple colour picker. Copies value to clipboard in RBG, Hex and SRGB values. Compatible with wayland and X11. #### CPU frequency Prints `/` in human readable form Data as reported by: `/sys/devices/system/cpu/cpu*/cpufreq/scaling_cur_freq` ``` Arguments: -a, --avg, avg, Only print average CPU clock speed over all cores -m, --max, max, Only print maximum CPU clock speed over all cores -r, --raw, raw, Do not make human readable -h, --help, help, Display this help ``` Useful for status lines. #### Headphone indicator Prints indicator if headphones are plugged in Uses `pactl` under the hood Configure the icon in the configuration file by setting `HEADPHONE_INDICATOR`. Useful for status lines. #### IP Address Get local IP address. #### Media Watch Time Prints watch times of media with remaining time and percentage. Requires `column` from `util-linux`. ``` Arguments: A list of media files (mp4) ``` Example: ``` $ cd tv-shows/planet-earth $ desktopctl mediawatchtime *mp4 Item | Title | Duration | Watched | % Watched | Remaining 1 | S01E01-planet-earth-from-pole-to-pole.mp4: | 0:59 | 0:59 | 9.00 | 9:44 2 | S01E02-planet-earth-mountains.mp4: | 0:57 | 1:56 | 18.00 | 8:47 3 | S01E03-planet-earth-fresh-water.mp4: | 0:58 | 2:55 | 27.00 | 7:48 4 | S01E04-planet-earth-caves.mp4: | 0:57 | 3:52 | 36.00 | 6:51 5 | S01E05-planet-earth-deserts.mp4: | 0:57 | 4:50 | 45.00 | 5:53 6 | S01E06-planet-earth-ice-worlds.mp4: | 0:58 | 5:49 | 54.00 | 4:54 7 | S01E07-planet-earth-great-plains.mp4: | 0:58 | 6:48 | 63.00 | 3:55 8 | S01E08-planet-earth-jungles.mp4: | 0:58 | 7:46 | 72.00 | 2:56 9 | S01E09-planet-earth-shallow-seas.mp4: | 0:58 | 8:45 | 81.00 | 1:57 10 | S01E10-planet-earth-seasonal-forests.mp4: | 0:58 | 9:44 | 90.00 | 0:58 11 | S01E11-planet-earth-ocean-deep.mp4: | 0:58 | 10:43 | 100.00 | 0:00 ``` #### Memory Print memory usage (human readable). ``` Options -r, --raw, raw, Display in raw bytes (not human readable). ``` Useful for status lines #### Monitor Directories/Files Prints size, number of files in directory, and changes since last polling. Argument: Directory or file to monitor ``` Arguments: dir, Directory or file to monitor -i, --interval, Time interval to re-compute file sizes and changes in seconds (Default 60) ``` E.g. ``` $ rsync /path/to/src/dir /path/to/dest/dir ``` Forgot to add progress options! ... instead of cancelling the transfer, just monitor the destination directory directly ``` $ desktopctl mondir -i 5 /path/to/dest/dir mondir: Monitoring '/path/to/dest/dir' with interval 5s. 2024-03-30-15:23:14 Total: 188G Files: 349222 2024-03-30-15:23:20 Total: 188G Files: 349266 Diff: 500MiB Files diff: 44 Speed: 100MiB/s 2024-03-30-15:23:26 Total: 189G Files: 349339 Diff: 525MiB Files diff: 73 Speed: 105MiB/s ... ``` Of course this is also useful for tools that do not offer progress statistics. #### Check if online Get current internet connection status ``` Arguments: -t, --timeout, Set timeout in seconds -q, --quiet, Do not print. Only uses exit value ``` Note: Options must be specified separately i.e. `-q -t 30` and not `-qt30` or `-qt 30`. Useful in scripts, to start backups or synchronise emails only when connected to the internet. #### Screenshots Take screenshots Supports taking a partial selection of the screen Supports wayland/x11 Screenshots are copied to the clipboard ``` Arguments: --select, Will ask user to make selection of area to screenshot --blurred, (x11 only) Will blur screenshot ``` Blurred screenshots are nice for creating a lockscreen with current screen contents blurred. #### Sound Manager Get and set sound ``` Arguments: +, Increase volume -, Decrease volume sink, Print current default output sink ismuted, Print "yes" if muted all devices are muted, else no notify, Send a desktop notification of current volume get-volume, get Print current volume mute, Mute current default sink toggle, Toggle mute status ``` Uses `pactl` under the hood Useful for displaying current volume in status line or when binding keyboard buttons. #### Internet speedtest Show current internet speed `curl`s a file from Linode ``` http://eu-central-1.linodeobjects.com/speedtest/100MB-speedtest ``` #### SSH List ssh clients on local network Useful for finding a headless Raspberry Pi after setting it up. #### Time zone Get and set current time zone. Uses [ip-api.com](http://ip-api.com/) to get the time zone based on IP address. Uses systemd's `timedatectl` to set the time zone. To do this non-interactively one needs the following polkit rule ``` # /etc/polkit-1/rules.d/timedate.rules polkit.addRule(function(action, subject) { if (action.id == "org.freedesktop.timedate1.set-time") { return polkit.Result.YES; } }); ``` #### Wifi Status Set wifi on/off. Show wifi connection status, signal strength. Useful for status lines. ``` Arguments: ssid, Print connected ssid icons, Print ssid with icons only-icons Only print icons off, Turn wifi off on, Turn wifi on ``` Configuration values ``` WIFI_ICON_CONFIGURING=󰤫 WIFI_ICON_LOW_STRENGTH=󰤟 WIFI_ICON_MED_STRENGTH=󰤢 WIFI_ICON_HIG_STRENGTH=󰤨 WIFI_ICON_DISCONNECTED=󰤯 WIFI_ICON_OFF=󰤮 # nm for Network Manager and iwd for IWD WIFI_BACKEND=nm WIFI_DEVICE=wlan0 ``` --- ### Limited Features #### Config Diff Uses configured `DIFFTOOL` (from configuration file) to display changes of files that have been modified on disk from how they were originally shipped with the package manager. ``` Arguments: path, Path to configuration file ``` Example: See changes from the default in the bluetooth configuration file, call ``` desktopctl config_diff /etc/bluetooth/main.conf ``` Only works on Archlinux. #### Power Manager ``` Charging Profiles: ac, Primarily AC Charging, Auto performance express, Express charging, Low performance Performance: auto, Automatically adjust performance cool, Set performance profile to cool desktop, Highest performance settings laptop, Laptop performance settings low, Set perforamnce to power saving quiet, Set performance profile to quiet ``` #### Reboot check Prints information about what services need to be restarted, and whether the kernel is old Used to generally inform, whether the system should be rebooted Can be wrapped with pacman hook to give information after update ``` Options: -d, --detailed, Print more detailed information ``` #### Xwayland clients Count xwayland clients Arguemnts: format, A format string in which '%n' will replace number of Xwayland clients if there are any. If there are none, nothing will be printed.