Table of contents

• Default key-bindings
• Using Wayfire
  • Opening terminals and moving around
  • Opening other applications
  • Closing windows
  • Moving windows
  • Resizing windows
  • Switching between windows
  • Positioning windows
  • Using workspaces
  • Moving windows to workspaces
  • Changing the opacity
  • Reloading the configuration
  • Exiting Wayfire
• Configuring Wayfire
  • Setting your keyboard layout
  • Terminal
  • Application launcher
  • Setting the wallpaper
  • Adding a panel and dock
  • Configuring viewport switcher
  • Configuring your outputs
  • Notifications
  • Idle configuration
  • Screen locker
  • Logout
  • Changing the volume
  • Changing the screen brightness
  • Screen color temperature
  • Taking screenshots
  • Creating screencasts
  • Automatically maximizing windows
  • Remote desktop

Here is an overview (non-exhaustive) of the key-bindings you can find in the wayfire.ini config file. A comprehensive reference of bindings available by default is available here.

• Super + e ⇒ Overview all workspaces.
  • [hjklEnterHomeEnd] ⇒ Switch to the specified workspace; add Shift for bottom.
• Super + Enter ⇒ Open a terminal (Alacritty).
• Super + Shift + Enter ⇒ Open the launcher (Wofi).
• Super + w ⇒ Close window.
• Super + Tab ⇒ Preview windows and select the next window; add Shift for previous.
• Alt + Escape ⇒ Select the next window.
• Super + [UpDownLeftRightHomeEndfd] ⇒ Arrange window into a grid; add Shift for bottom.
• Super + [hjkl] ⇒ Switch to adjacent workspace; add Shift to move with the focused window.
• Super + Control + [hl] ⇒ Switch to the previous or next workspace, by using the cube.
• Super + o ⇒ Move focus to the next output; add Shift to move with the focused window.

Note that you probably need to adapt the applications, such as the terminal and launcher, in your config file.

One very basic operation is opening a new terminal. By pressing Super + Enter, a new terminal will be opened. By default, the key-binding opens Alacritty.

Aside from opening applications from a terminal, you can also use the handy Wofi which is opened by pressing Super + Shift + Enter by default.

Additionally, if you have applications you open very frequently, you can create a key-binding for starting the application directly. See the section Configuring Wayfire for details.

If an application does not provide a mechanism for closing (most applications provide a menu, the middle mouse button for tabs, the escape key or a shortcut like Control + w to close), you can press Super + w, Super and middle mouse button or Alt + F4 to close a window.

By dragging the window’s title bar with your mouse you can move the window around. You can also drag windows by holding down Super and left mouse button.

By grabbing the borders and moving them you can resize the window. You can also do that by holding down Super and right mouse button.

By pressing Super + Tab, you can preview the windows in the current workspace and select the next window; add Shift for previous. To switch without animation, press Alt + Escape.

Press Super and the arrow keys for arranging windows into a grid of 2 cells. Press Super + [HomeEnd] for arranging windows into a grid of 4 cells; add Shift for bottom. Press Super + f to position the window in the center of the screen. Press Super + d to restore the window to its original size and position. You can also use the keypad, which is laid out exactly to match the slots.

Workspaces are an easy way to group a set of windows. Wayfire allows you to arrange your workspaces spatially, rather than linearly. By default, there is 9 – 3 horizontal and 3 vertical – workspaces, and you are on the first workspace.

To switch to another workspace, press Super + HJKL; add Shift to move with the focused window.

You can also use the cube, by holding Super + Shift and left mouse button, or via the keyboard with Super + Control + [hl].

Pressing Super allows you to preview all workspaces in the current output. You can use your mouse to select a workspace. HJKL, Enter, Home and End can be used to select a workspace with your keyboard; add Shift for bottom.

To move a window to another workspace, simply press Super + Shift + HJKL.

When the modifier key Super + Alt is held down, you can scroll down and up to adjust the opacity of the window.

To reload the configuration, simply save the config file. Most of the options are automatically reloaded.

Press Control + Alt + Backspace.

TODO: Add a configuration option.

To change the configuration of Wayfire, copy wayfire.ini to ~/.config/wayfire.ini and edit it with a text editor. For a complete reference, see the Configuration document.

~/.config/wayfire.ini

[input]
xkb_layout = us,fr
xkb_variant = dvorak,bepo

See Input for more information.

Open Alacritty, kitty or another terminal:

~/.config/wayfire.ini

[command]
binding_terminal = <super> KEY_ENTER
command_terminal = alacritty

See Command for more information.

Example – Run Wofi, a graphical launcher, similar to dmenu:

~/.config/wayfire.ini

[command]
binding_launcher = <super> <shift> KEY_ENTER
command_launcher = wofi

Note: Add mode=run or mode=drun to ~/.config/wofi/config. You can also specify the mode with --show option.

You might prefer fzf running in a terminal.

Example – Run Launcher with fzf and Alacritty:

~/.config/wayfire.ini

[command]
binding_launcher = <super> <shift> KEY_ENTER
command_launcher = alacritty --command sh -c 'nohup launcher-run $(launcher-list | fzf) > /dev/null'

See Command for more information.

You can use wf-background, provided by wf-shell.

~/.config/wayfire.ini

[autostart]
background = wf-background

See Autostart for more information.

If you prefer swaybg, adapt the command as follows.

Example – Simple:

swaybg --image /path/to/wallpaper.webp

Example – Random wallpaper:

find -L /path/to/wallpapers -type f | sort -R | head -n 1 | xargs swaybg --image

You can use wf-panel and wf-dock, provided by wf-shell.

~/.config/wayfire.ini

[autostart]
panel = wf-panel
dock = wf-dock

You can also use Waybar if you prefer it.

~/.config/wayfire.ini

[autostart]
bar = waybar

See Autostart for more information.

See Viewport switcher for more information.

If you want to switch to another workspace by pressing super+num where num is the number of the workspace you want to use.

Follow the example below.

~/.config/wayfire.ini

[vswitch]
binding_0 = <super> KEY_0
binding_1 = <super> KEY_1
binding_2 = <super> KEY_2
binding_3 = <super> KEY_3
binding_4 = <super> KEY_4
binding_5 = <super> KEY_5
binding_6 = <super> KEY_6
binding_7 = <super> KEY_7
binding_8 = <super> KEY_8
binding_9 = <super> KEY_9

See Output for more information, setting mirroring, custom modes, etc.

Example configuration statically via Wayfire:

~/.config/wayfire.ini

[eDP-1]
mode = [email protected] # or just 1920x1080
layout = 0,0
transform = normal
scale = 1.000000

Kanshi supports more dynamic configuration, like switching profiles based on connected outputs:

~/.config/kanshi/config

{
  output eDP-1 mode 1920x1080 position 0,0
}
{
  output eDP-1 mode 1920x1080 position 0,900
  output HDMI-A-1 mode 1440x900 position 0,0
}

You can get the names of your outputs with wlr-randr, or by inspecting the log of Wayfire (printed to stdout by default).

And start kanshi on startup with Autostart.

Using mako:

~/.config/wayfire.ini

[autostart]
notifications = mako

See Autostart for more information.

Example configuration with swayidle and swaylock:

~/.config/wayfire.ini

[autostart]
idle = swayidle before-sleep swaylock

[idle]
toggle = <super> KEY_Z
screensaver_timeout = 300
dpms_timeout = 600

• Disables the compositor going idle with Super + z.
• This will lock your screen after 300 seconds of inactivity, then turn off your displays after another 300 seconds.

See Autostart and Idle for more information.

Note: for now there is a trick for binding a key to instantly turn-off the screen (DPMS).

Lock your screen with swaylock:

~/.config/wayfire.ini

[command]
binding_lock = <super> KEY_ESC
command_lock = swaylock

See Command for more information.

Use wayland-logout to kill the current compositor instance. Launch logout GUI wlogout:

~/.config/wf-shell.ini

[panel]
menu_logout_command = wlogout

Example – Changing the volume with ALSA:

~/.config/wayfire.ini

[command]
repeatable_binding_volume_up = KEY_VOLUMEUP
command_volume_up = amixer set Master 5%+
repeatable_binding_volume_down = KEY_VOLUMEDOWN
command_volume_down = amixer set Master 5%-
binding_mute = KEY_MUTE
command_mute = amixer set Master toggle

Example – Changing the volume with PulseAudio:

~/.config/wayfire.ini

[command]
repeatable_binding_volume_up = KEY_VOLUMEUP
command_volume_up = pactl set-sink-volume 0 +5%
repeatable_binding_volume_down = KEY_VOLUMEDOWN
command_volume_down = pactl set-sink-volume 0 -5%
binding_mute = KEY_MUTE
command_mute = pactl set-sink-mute 0 toggle

Example – Changing the volume with WirePlumber for PipeWire:

~/.config/wayfire.ini

[command]
repeatable_binding_volume_up = KEY_VOLUMEUP
command_volume_up = wpctl set-volume @DEFAULT_AUDIO_SINK@ 5%+
repeatable_binding_volume_down = KEY_VOLUMEDOWN
command_volume_down = wpctl set-volume @DEFAULT_AUDIO_SINK@ 5%-
binding_mute = KEY_MUTE
command_mute = wpctl set-mute @DEFAULT_AUDIO_SINK@ toggle

See Command for more information.

Example – Changing the screen brightness with Light:

~/.config/wayfire.ini

[command]
repeatable_binding_light_up = KEY_BRIGHTNESSUP
command_light_up = light -A 5
repeatable_binding_light_down = KEY_BRIGHTNESSDOWN
command_light_down = light -U 5

Note: Make sure that the user is part of the video group, otherwise you will not get access to the devices.

See Command for more information.

Adjust the color temperature of your screen with Redshift:

~/.config/wayfire.ini

[autostart]
redshift = redshift -m wayland

Note: Requires Redshift with Wayland support.

See Autostart for more information.

Taking screenshots with grim and slurp:

~/.config/wayfire.ini

[command]
binding_screenshot = KEY_PRINT
command_screenshot = grim $(date '+%F_%T').webp
binding_screenshot_interactive = <shift> KEY_PRINT
command_screenshot_interactive = slurp | grim -g - $(date '+%F_%T').webp

You can also use wl-clipboard in combination with grim and slurp capture a screenshot to clipboard. Put this entry in [command] section.

binding_screenshot_clip = <super> <ctrl> KEY_S
command_screenshot_clip = grim -g \"$(slurp)" - | wl-copy

See Command for more information.

See wf-recorder and wlrobs.

You can maximize specific windows by default with the following command:

~/.config/wayfire.ini

[window-rules]
alacritty = on created if app_id is "Alacritty" then maximize

You can get the properties of your applications with the following command:

WAYLAND_DEBUG=1 alacritty 2>&1 | kak

See Window rules for more information.

With virtual pointer support, programs like wayvnc are possible. No special wayfire configuration is required.