CLI reference

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.

Generated from rift-cli at v0.7.0.

Choose an area

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:

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

Placeholders shown as links, such as <DIRECTION>, lead to their 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.