Skip to content
Rift

Quick start

This guide assumes a fresh install with no custom configuration. You’ll arrange two windows, try keyboard navigation, and optionally save your own settings. Run the shell commands in Terminal.

1. Install Rift

Section titled “1. Install Rift”

Enable Displays have separate Spaces in System Settings → Desktop & Dock → Mission Control. If you use Homebrew, install Rift:

Terminal window
brew install acsandmann/tap/rift

For a release archive or permission details, see Installation.

2. Start the service

Section titled “2. Start the service”

Install the background service so Rift can run without an open Terminal window:

Terminal window
rift service install
rift service start

The first launch may stop after asking for Accessibility access. Allow Rift in System Settings → Privacy & Security → Accessibility, then run:

Terminal window
rift service restart

3. Activate the current Space

Section titled “3. Activate the current Space”

A Space is a macOS desktop, shown in Mission Control. By default, Rift waits for you to enable tiling on each Space.

Open two app windows, such as a browser and Terminal. Press Option (⌥) + Z. Rift should arrange them into tiles. Press the shortcut again to stop tiling this Space. Rift calls the Option key Alt in its configuration.

If nothing happens, check service, permission, and shortcut problems.

4. Try keyboard navigation

Section titled “4. Try keyboard navigation”

Press Option + H to focus the window on the left, or Option + L for the right. Focus means the window that receives your typing. Option + J and Option + K select windows below and above. These shortcuts come with Rift.

You can keep using the bundled settings. Continue below only when you want to customize them.

5. Save your own settings

Section titled “5. Save your own settings”

Create the configuration folder:

Terminal window
mkdir -p ~/.config/rift

Save the following as ~/.config/rift/config.toml in a plain-text editor. Back up that file first if it already exists.

[keys]
"Alt + Z" = "toggle_space_activated"
"Alt + H" = { move_focus = "left" }
"Alt + J" = { move_focus = "down" }
"Alt + K" = { move_focus = "up" }
"Alt + L" = { move_focus = "right" }
"Alt + Shift + H" = { move_node = "left" }
"Alt + Shift + J" = { move_node = "down" }
"Alt + Shift + K" = { move_node = "up" }
"Alt + Shift + L" = { move_node = "right" }
"Alt + Shift + Space" = "toggle_window_floating"


[settings.layout]
mode = "master_stack"


[settings.layout.gaps.outer]
top = 8.0
left = 8.0
bottom = 8.0
right = 8.0


[settings.layout.gaps.inner]
horizontal = 8.0
vertical = 8.0

This [keys] table replaces the bundled keymap. Keep every shortcut you want to use.

The example adds Shift to the direction keys to move a window. Option + Shift + Space toggles floating, which lets you position that window freely. Master-stack gives one window a larger area; the gaps leave space between windows.

Apply the file with rift-cli, Rift’s terminal control tool:

Terminal window
rift-cli execute config reload

Later edits normally apply automatically when you save. To retain all starter shortcuts, use the bundled config as your starting point instead.

Where to go next

Section titled “Where to go next”