Nirius: utility commands for the niri wayland compositor

Some utility commands for the niri wayland compositor. You have to start the niriusd daemon and then issue commands using the nirius utility. The daemon is best started by adding spawn-at-startup "niriusd" to niri's config.kdl.

Commands

Focusing matching windows

The focus commands are shortcuts for quickly focusing (or even spawning) the apps you need all the time.

• focus [OPTIONS]: Focuses a matching window if there is one, otherwise exits non-zero. What windows match is specified using the options --app-id (-a) and --title (-t), both regular expressions. If there are multiple matching windows, the command cycles through them.
• focus-or-spawn [OPTIONS] [COMMAND]...: Same behavior as focus except that it spawns COMMAND instead of exiting non-zero if no matching window exists.

Moving matching windows to the current workspace

Where the focusing commands switch to matching windows where they are, maybe on a different workspace on a different output, the below commands move matching windows from elsewhere to the current workspace.

• move-to-current-workspace [OPTIONS]: Moves a matching window (same options as focus) from some unfocused workspace to the currently focused workspace. If the --focus flag is given, the moved window also gains focus. If there is no matching window, exits non-zero.
• move-to-current-workspace-or-spawn [OPTIONS] [COMMAND]: Same behavior as move-to-current-workspace except that it spawns the given COMMAND if there is no matching window.

Categorizing windows with marks

The below commands allow for annotating windows with different marks (or labels) and provide means to quickly cycle through all windows having the same mark.

• toggle-mark [MARK]: Marks or unmarks a window with the given or default mark (which is __default__). Marked windows can be focused using focus-marked.
• focus-marked [MARK]: Focuses the window marked with MARK, or the default mark __default__ if not given. If there are multiple such windows, cycles through all of them.
• list-marked [MARK]: Lists all windows marked with MARK, or the default mark if not given, on stdout. If the --all flag is given, list all windows of all marks.

Follow-mode

Windows in follow-mode follow you when switching from one workspace to another one. The primary intended use-case are floating music or video player windows.

• toggle-follow-mode: Enables or disables follow mode for the currently focused window. When switching to another workspace, all windows in follow mode are moved to that workspace.

The scratchpad

Users coming to niri from i3/sway probably know the "scratchpad" which is a kind of hidden workspace there where you can send windows to which you need often but don't want to have next to you all the time, e.g., a terminal which you just need for executing git commands every now and then. You a command which shows one scratchpad window as floating window on top of your tiled windows and moves it back when invoked again. The below commands implement the same for niri. The difference is that niri has no hidden workspace, so the scratchpad is actually the bottom-most non-empty workspace. When you focus that, nirius will move the scratchpad windows to the workspace below.

• scratchpad-toggle: Moves the current window to the scratchpad if it's not a scratchpad window already. If it is, removes it from the scratchpad, i.e., it's just a normal floating window afterwards. Making a scratchpad window tiled again also removes its scratchpad state implicitly.
• scratchpad-show: Shows a window from the scratchpad. If a scratchpad window is already shown, moves it back to the scratchpad. Repeated invocations cycle though all scratchpad windows.

Installation

Some distros have packaged nirius so that you can install it using your distro's package manager. Alternatively, it's easy to build and install it yourself using cargo.

Distro packages

The following GNU/Linux and BSD distros package nirius. Thanks a lot to the respective package maintainers! Refer to the repology site for details.

Building with cargo

You'll need to install the current stable rust toolchain using the one-liner shown at the official rust installation page.

Then you can install nirius like so:

cargo install nirius

For getting updates easily, I recommend the cargo cargo-update plugin.

# Install it once.
cargo install cargo-update

# Then you can update all installed rust binary crates including nirius using:
cargo install-update --all

# If you only want to update nirius, you can do so using:
cargo install-update -- nirius

Questions & Patches

For asking questions, sending feedback, or patches, refer to my public inbox (mailinglist). Please mention the project you are referring to in the subject, e.g., nirius (or other projects in different repositories).

Bugs

It compiles, therefore there are no bugs. Oh well, if you still found one or want to request a feature, you can do so here.

Build status

License

Nirius is licensed under the GPLv3 (or later).