Skip to content

CLI

Jump to bottom
acsandmann edited this page Jul 22, 2026 · 1 revision

rift-cli reference

rift-cli communicates with the running rift instance over Mach IPC and returns JSON. Set RIFT_CLI_PRETTY=1 for pretty-printed responses.

Query commands

  • rift-cli query workspaces [--space-id ID] — List virtual workspaces.
  • rift-cli query windows [--space-id ID] — List tracked windows.
  • rift-cli query displays — List connected displays and their UUIDs.
  • rift-cli query window WINDOW_ID — Get information about a specific window.
  • rift-cli query applications — List running applications.
  • rift-cli query layout --space-id ID — Get layout state for a macOS space.
  • rift-cli query workspace-layout [--space-id ID] [--workspace-id ID] — Get layout-engine modes.
  • rift-cli query metrics — Get performance metrics.

Window and workspace examples:

rift-cli query displays
rift-cli execute window focus left
rift-cli execute window resize-by 0.05
rift-cli execute workspace switch 2
rift-cli execute workspace move-window 1
rift-cli execute workspace set-layout --workspace-id 2 scrolling

Execute commands

  • rift-cli execute window ... — Focus, resize, float, fullscreen, or close windows.
  • rift-cli execute workspace ... — Switch, create, move, or change virtual workspaces.
  • rift-cli execute layout ... — Manipulate the layout tree, stacks, master area, or scrolling strip.
  • rift-cli execute config ... — Update, inspect, save, or reload configuration.
  • rift-cli execute mission-control show-all|show-current|dismiss — Control rift's mission control view.
  • rift-cli execute display ... — Focus displays, move the mouse, or move windows between displays.
  • rift-cli execute space toggle-activated|switch DIRECTION — Manage or switch native macOS spaces.
  • rift-cli execute save-layout PATH / rift-cli execute save-layout --master — Save the current layout.
  • rift-cli execute load-layout PATH [--scope workspace|space] / rift-cli execute load-layout --master — Restore a saved layout.
  • rift-cli execute debug — Print the active layout tree.
  • rift-cli execute serialize — Print serialized runtime state.
  • rift-cli execute show-timing — Print timing metrics.
  • rift-cli execute save-and-exit — Save the master layout and exit.

Event subscriptions

Mach subscriptions stream JSON events to stdout:

rift-cli subscribe mach workspace_changed
rift-cli subscribe mach '*'

The supported events are workspace_changed, windows_changed, window_title_changed, stacks_changed, and * for all events.

CLI subscriptions execute a command whenever an event is emitted. The event JSON is appended as the final argument:

rift-cli subscribe cli --event workspace_changed --command sh --args -c 'sketchybar --trigger rift_workspace_changed RIFT_WORKSPACE_NAME="$RIFT_WORKSPACE_NAME"'
rift-cli subscribe list-cli
rift-cli subscribe unsub-cli workspace_changed

For CLI subscriptions, rift also sets event-specific environment variables. Common variables include RIFT_EVENT_TYPE, RIFT_EVENT_JSON, RIFT_WORKSPACE_ID, RIFT_WORKSPACE_NAME, RIFT_SPACE_ID, and RIFT_DISPLAY_UUID. Window events additionally provide RIFT_WINDOW_COUNT, RIFT_WINDOWS, or RIFT_WINDOW_ID; title events provide RIFT_PREVIOUS_WINDOW_TITLE and RIFT_WINDOW_TITLE; stack events provide RIFT_STACK_COUNT and RIFT_ACTIVE_WORKSPACE_HAS_FULLSCREEN.

Service and startup commands

The rift binary manages the per-user launchd service:

rift service install
rift service start
rift service restart
rift service stop
rift service uninstall

Useful startup flags include:

  • rift --config PATH — Use a configuration file other than ~/.config/rift/config.toml.
  • rift --default-disable — Disable new spaces by default.
  • rift --restore — Restore the master layout snapshot at startup.
  • rift --validate — Check whether the saved master layout snapshot can be loaded.

Layout persistence

Rift can save and restore layout snapshots in .ron format.

  • The master layout file is stored at ~/.rift/layout.ron.
  • rift-cli execute save-layout --master updates the master file without exiting.
  • rift-cli execute load-layout --master restores the master file.
  • Passing a path to save-layout or load-layout uses a reusable layout file instead.
  • load-layout --scope workspace restores one workspace; --scope space restores all saved workspaces for the current macOS space.
  • The menu bar's layout_folder controls which reusable layout files appear in the menu.

Example:

mkdir -p ~/.config/rift/layouts
rift-cli execute save-layout ~/.config/rift/layouts/coding.ron
rift-cli execute load-layout ~/.config/rift/layouts/coding.ron --scope workspace

Clone this wiki locally