<div align="center"> <a href="https://github.com/orhun/runst"> <img src="assets/runst-logo.png" width="300"> </a> <h4><strong><code>runst</code></strong> — A dead simple notification daemon 🦡</h4>

</div>

Desktop notifications are small, passive popup dialogs that notify the user of particular events in an asynchronous manner. These passive popups can automatically disappear after a short period of time.

runst is the server implementation of freedesktop.org - Desktop Notifications Specification and it can be used to receive notifications from applications via D-Bus. As of now, only X11 is supported.

Features

Fully customizable notification window (size, location, text, colors).
Template-powered (Jinja2/Django) notification text.
Auto-clear notifications based on a fixed time or estimated read time.
Run custom OS commands based on the matched notifications.
Z-Bus based notification backend (Rust IPC handling over the D-Bus protocol)

Roadmap

runst is initially designed to show a simple notification window. On top of that, it combines customization-oriented and semi-innovative features. In the future, I'm aiming to shape runst functionality based on new ideas and feedback.

Feel free to submit an issue if you have something in mind or having a problem!

Installation

From crates.io

runst can be installed from crates.io:

$ cargo install runst

The minimum supported Rust version is 1.70.0.

Arch Linux

runst can be installed from the extra repository using pacman:

$ pacman -S runst

Or you can install the available AUR packages with using an AUR helper. For example:

$ paru -S runst-git

Alpine Linux

runst is available for Alpine Edge. It can be installed via apk after enabling the testing repository.

apk add runst

Binary releases

See the available binaries for different operating systems/architectures from the releases page.

Release tarballs are signed with the following PGP key: AEF8C7261F4CEB41A448CBC41B250A9F78535D1A

Build from source

Prerequisites

Instructions

Clone the repository.

$ git clone https://github.com/orhun/runst && cd runst/

Build.

$ CARGO_TARGET_DIR=target cargo build --release

Binary will be located at target/release/runst.

Usage

On Xorg startup

You can use xinitrc or xprofile for autostarting runst.

xinitrc

If you are starting Xorg manually with xinit, you can runst on X server startup via xinitrc:

$HOME/.xinitrc:

runst &

Long-running programs such as notification daemons should be started before the window manager, so they should either fork themself or be run in the background via appending & sign. Otherwise, the script would halt and wait for each program to exit before executing the window manager or desktop environment.

In the case of runst not being available since it's started at a faster manner than the window manager, you can add a delay as shown in the example below:

{ sleep 2; runst; } &

xprofile

If you are using a display manager, you can utilize an xprofile file which allows you to execute commands at the beginning of the X user session.

The xprofile file, which is ~/.xprofile or /etc/xprofile, can be styled similarly to xinitrc.

As a D-Bus service

Although runst now uses a Z-Bus backend internally, it still exposes the standard org.freedesktop.Notifications interface on the session D-Bus. In other words, Z-Bus handles the backend inside runst, while the activation mechanism is still D-Bus. Because of that, you can still use a regular D-Bus service file to launch runst automatically on the first notification action. For example, you can create the following service configuration:

/usr/share/dbus-1/services/org.orhun.runst.service:

[D-BUS Service]
Name=org.freedesktop.Notifications
Exec=/usr/bin/runst

Whenever an application sends a notification by sending a signal to org.freedesktop.Notifications, D-Bus activates runst.

Also, see #1 for systemd integration.

Commands

runst can be controlled with sending commands to D-Bus via dbus-send(1).

dbus-send --print-reply --dest=org.freedesktop.Notifications /org/freedesktop/Notifications/ctl "org.freedesktop.Notifications.${command}"

Available commands are:

History: show the last notification.
Close: close the notification.
CloseAll: close all the notifications.

For example:

# show the last notification
dbus-send --print-reply \
          --dest=org.freedesktop.Notifications \
          /org/freedesktop/Notifications/ctl \
          org.freedesktop.Notifications.History

An example usage for i3:

# Notification history
bindsym $mod+grave exec dbus-send --print-reply \
        --dest=org.freedesktop.Notifications /org/freedesktop/Notifications/ctl org.freedesktop.Notifications.History

# Close notification
bindsym $mod+shift+grave exec dbus-send --print-reply \
        --dest=org.freedesktop.Notifications /org/freedesktop/Notifications/ctl org.freedesktop.Notifications.Close

Additionally, to view the server version:

dbus-send --print-reply --dest=org.freedesktop.Notifications /org/freedesktop/Notifications org.freedesktop.Notifications.GetServerInformation

Configuration

runst configuration file supports TOML format and the default configuration values can be found here.

If exists, configuration file is read from the following default locations:

$HOME/.config/runst/runst.toml
$HOME/.runst/runst.toml

You can also specify a path via RUNST_CONFIG environment variable.

Global configuration

`log_verbosity`

Sets the logging verbosity. Possible values are error, warn, info, debug and trace.

`startup_notification`

Shows a notification at startup if set to true.

`geometry`

Sets the window geometry. The value format is <width>x<height>+<x>+<y>.

For setting this value, I recommend using a tool like slop which helps with querying for a selection and printing the region to stdout.

`wrap_content`

If set to true, the window is resized to match the contents.

If the content is larger than the window size, geometry option is used for maximum width and height.

`font`

Sets the font to use for the window.

`template`

Sets the template for the notification message. The syntax is based on Jinja2 and Django templates.

Simply, there are 3 kinds of delimiters:

{{ and }} for expressions
{% or {%- and %} or -%} for statements
{# and #} for comments

See Tera documentation for more information about control structures, [built-in filters](https://tera.netlify

Runst

Install / Use

README