CLI reference

Source version: main.

Use rift-cli to inspect Rift, control windows and workspaces, change runtime settings, and subscribe to events. Every command, description, argument, and option in this reference comes directly from the checked-out CLI.

Choose an area

Area	Use it to
Queries	Inspect workspaces, windows, displays, layouts, and metrics
Execute	Control windows, workspaces, layouts, configuration, displays, and macOS Spaces
Subscriptions	Stream events or run a command when Rift changes
Service	Find the corresponding `rift service` commands

Quick examples

# See the windows Rift is managing
rift-cli query windows

# Focus the window to the left
rift-cli execute window focus left

# Move to the next virtual workspace
rift-cli execute workspace next

# Reload the configuration file
rift-cli execute config reload

Queries print JSON; set RIFT_CLI_PRETTY=1 for readable output. Commands under execute act on the running Rift instance. Virtual workspace indexes are zero-based, so 0 means the first workspace.

Reading command values

Command synopses use angle brackets for required values and square brackets for optional values:

<VALUE> Required[VALUE] Optional<DIRECTION> Linked to its definition

Underlined placeholders are links. Select one in a synopsis or parameter list, such as <DIRECTION>, to see its accepted values or identifier format.

Accepted values

These placeholders have a fixed set of accepted values.

<DIRECTION>: One of left, right, up, or down, relative to the current window, selection, display, or macOS Space.
<ORIENTATION>: The resize axis: horizontal, vertical, or smart. Smart chooses the nearest applicable split.
<MODE>: A layout mode: traditional, bsp, stack, master_stack, or scrolling.
<EVENT>: One of workspace_changed, windows_changed, window_title_changed, focused_window_changed, stacks_changed, or * for every event.
<SCOPE>: The restore scope: workspace for one workspace or space for all saved workspaces in the current macOS Space.

Identifiers

These placeholders identify Rift or macOS objects rather than choosing from a fixed set.

<WINDOW_ID>: A Rift window identifier. Commands accept the JSON form, such as {"pid":123,"idx":456}, or the debug-text form where noted.
<WINDOW_SERVER_ID>: The numeric window ID assigned by the macOS WindowServer.
<WORKSPACE_ID>: A zero-based Rift virtual-workspace index. 0 identifies the first workspace.
<SPACE_ID>: The numeric macOS Space identifier returned by Rift query output. This is distinct from a virtual workspace index.
<UUID>: A display UUID. Use rift-cli query displays to find the UUIDs of connected displays.
<INDEX>: A zero-based display index. Use rift-cli query displays to inspect connected displays.