### Install Rift as a Service (Build from Source)

Source: https://github.com/acsandmann/rift/wiki/Quick-Start

Commands to install and start Rift as a background service when building from source. Requires accessibility permissions.

```sh
cargo run --bin rift --release service install
cargo run --bin rift --release service start
```

```sh
cargo run --bin rift --release service restart
```

--------------------------------

### Install Rift as a Service (Homebrew)

Source: https://github.com/acsandmann/rift/wiki/Quick-Start

Commands to install and start Rift as a background service after installing with Homebrew. Requires accessibility permissions.

```sh
rift service install
ift service start
```

```sh
rift service restart
```

--------------------------------

### Query Window List with rift-cli

Source: https://github.com/acsandmann/rift/blob/main/_autodocs/INDEX.md

Use the rift-cli to retrieve a list of all current windows. No setup is required beyond having rift-cli installed.

```bash
rift-cli windows
```

--------------------------------

### Start Rift Server

Source: https://github.com/acsandmann/rift/blob/main/_autodocs/errors.md

Start the Rift daemon if it is not running. You can start it in the foreground or background.

```bash
rift
```

```bash
rift &
```

--------------------------------

### Rift Settings Section Example

Source: https://github.com/acsandmann/rift/blob/main/_autodocs/configuration.md

Provides an example of the `[settings]` section in the Rift configuration file. This section controls global behaviors such as animations, mouse focus, and startup commands.

```toml
[settings]
animate = true
animation_duration = 0.2
animation_fps = 60.0
animation_easing = "ease_in_out"
default_disable = true
mouse_follows_focus = true
mouse_hides_on_focus = true
focus_follows_mouse = true
hot_reload = true

auto_focus_blacklist = [
  "com.apple.Spotlight",
]

run_on_start = [
  "rift-cli subscribe workspace_changed -- echo 'Workspace: {event}'",
]

```

--------------------------------

### Install Rift via Homebrew

Source: https://github.com/acsandmann/rift/wiki/Quick-Start

Use this command to install the Rift application using the Homebrew package manager.

```sh
brew install acsandmann/tap/rift
```

--------------------------------

### App Rule Example

Source: https://github.com/acsandmann/rift/blob/main/_autodocs/configuration.md

Define rules to assign specific applications or windows to particular workspaces. This example shows how to target an application by its bundle ID and assign it to workspace 1.

```toml
[[virtual_workspaces.app_rules]]
app_id = "com.apple.Terminal"              # Bundle identifier
workspace = 1                              # 0-based index or name
floating = false                           # Float in this workspace
manage = true                              # Rift manages this window

```

--------------------------------

### Example List CLI Subscriptions Response

Source: https://github.com/acsandmann/rift/blob/main/_autodocs/endpoints.md

This is an example of the JSON response when listing active CLI subscriptions.

```json
{
  "data": {
    "subscriptions": [
      {
        "event": "workspace_changed",
        "command": "osascript",
        "args": ["-e", "display notification \"Workspace changed\""]
      }
    ]
  }
}
```

--------------------------------

### Minimal Configuration Example

Source: https://github.com/acsandmann/rift/blob/main/_autodocs/configuration.md

A basic configuration file demonstrating essential settings for animation, layout, gaps, keybindings, and application-specific workspace rules.

```toml
[settings]
animate = true
animation_duration = 0.15

[layout]
mode = "bsp"

[layout.gaps]
outer = { top = 10, left = 10, bottom = 10, right = 10 }
inner = { horizontal = 10, vertical = 10 }

[keys]
"Cmd + Space" = "toggle_space_activated"
"Cmd + J" = "next_window"
"Cmd + K" = "prev_window"
"Cmd + H" = { MoveFocus = "left" }
"Cmd + L" = { MoveFocus = "right" }
"Cmd + 1" = { SwitchToWorkspace = 0 }
"Cmd + 2" = { SwitchToWorkspace = 1 }

[virtual_workspaces]
default_workspace_count = 5
workspace_names = ["web", "code", "chat", "mail", "misc"]

[[virtual_workspaces.app_rules]]
app_id = "com.google.Chrome"
workspace = 0

[[virtual_workspaces.app_rules]]
app_id = "com.apple.Terminal"
workspace = 1
```

--------------------------------

### Workspace Rule Example

Source: https://github.com/acsandmann/rift/blob/main/_autodocs/configuration.md

Set layout rules for specific workspaces. This example assigns the 'bsp' layout to a workspace identified by the name 'web'.

```toml
[[virtual_workspaces.workspace_rules]]
workspace = 1                              # Index or name
layout = "bsp"                             # Layout mode

```

--------------------------------

### LayoutEngine Usage Example

Source: https://github.com/acsandmann/rift/blob/main/_autodocs/api-reference/layout-engine.md

Demonstrates how to initialize and use the LayoutEngine to handle commands and update window focus. Requires configuration and window server interaction.

```rust
use rift::layout_engine::{LayoutEngine, LayoutCommand};

let mut engine = LayoutEngine::new(config);

// Handle a focus command
let response = engine.handle_command(
    Some(space_id),
    &[space_id],
    &[screen_center],
    LayoutCommand::MoveFocus(Direction::Right),
);

// Raise windows and update focus
for window_id in response.raise_windows {
    window_server.raise(window_id);
}
if let Some(window_id) = response.focus_window {
    window_server.focus(window_id);
}
```

--------------------------------

### RiftResponse Success Example

Source: https://github.com/acsandmann/rift/blob/main/_autodocs/api-reference/ipc-protocol.md

Example of a successful response from the Rift Mach server, containing data in JSON format.

```json
{ "data": { "workspaces": [{ "id": "00000001", "name": "1" }] } }
```

--------------------------------

### IPC Protocol: Focus Next Window Request

Source: https://github.com/acsandmann/rift/blob/main/_autodocs/api-reference/ipc-protocol.md

Example JSON request to execute the 'next_window' command.

```json
{
  "execute_command": {
    "command": "next_window",
    "args": []
  }
}

```

--------------------------------

### Run Rift Directly (Homebrew)

Source: https://github.com/acsandmann/rift/wiki/Quick-Start

Command to run the Rift application directly after installing with Homebrew.

```sh
rift
```

--------------------------------

### Basic Keybinding Configuration

Source: https://github.com/acsandmann/rift/blob/main/_autodocs/configuration.md

Define custom keybindings for various Rift actions using TOML. This example shows how to map key combinations to specific commands or commands with parameters.

```toml
[keys]
"Cmd + Space" = "toggle_space_activated"
"Cmd + J" = "next_window"
"Cmd + K" = "prev_window"
"Cmd + H" = { MoveFocus = "left" }
"Cmd + L" = { MoveFocus = "right" }
"Cmd + I" = { MoveFocus = "up" }
"Cmd + M" = { MoveFocus = "down" }

"Cmd + Shift + H" = { MoveNode = "left" }
"Cmd + Shift + L" = { MoveNode = "right" }
"Cmd + Shift + I" = { MoveFocus = "up" }
"Cmd + Shift + M" = { MoveFocus = "down" }

"Cmd + E" = "toggle_orientation"
"Cmd + F" = "toggle_window_floating"
"Cmd + Alt + F" = "toggle_fullscreen"
"Cmd + Z" = "toggle_stack"

"Cmd + 1" = { SwitchToWorkspace = 0 }
"Cmd + 2" = { SwitchToWorkspace = 1 }
# ... more

"Cmd + N" = "next_workspace"
"Cmd + P" = "prev_workspace"
```

--------------------------------

### RiftResponse Error Example

Source: https://github.com/acsandmann/rift/blob/main/_autodocs/api-reference/ipc-protocol.md

Example of an error response from the Rift Mach server, detailing the failure reason.

```json
{ "error": "Failed to get workspaces: invalid space_id" }
```

--------------------------------

### IPC Protocol: Query Workspaces Request

Source: https://github.com/acsandmann/rift/blob/main/_autodocs/api-reference/ipc-protocol.md

Example JSON request to query workspaces. Pass `null` for `space_id` to get all workspaces.

```json
{
  "get_workspaces": {
    "space_id": null
  }
}

```

--------------------------------

### Example Subsequent Event Payload

Source: https://github.com/acsandmann/rift/blob/main/_autodocs/endpoints.md

This is an example of the JSON payload received when a 'workspace_changed' event occurs.

```json
{
  "event": "workspace_changed",
  "workspace_id": "00000001",
  "workspace_name": "1",
  "timestamp": 1704067200000
}
```

--------------------------------

### Rift Layout Configuration Example

Source: https://github.com/acsandmann/rift/blob/main/_autodocs/configuration.md

This TOML snippet shows a comprehensive configuration for the Rift layout settings, including traditional mode, gaps, stack orientation, master-stack parameters, and scrolling layout preferences.

```toml
[layout]
mode = "traditional"

[layout.gaps]
outer = { top = 10, left = 10, bottom = 10, right = 10 }
inner = { horizontal = 10, vertical = 10 }

[layout.stack]
default_orientation = "vertical"

[layout.master_stack]
side = "left"
ratio = 0.6
count = 1

[layout.scrolling]
column_width_ratio = 0.7
min_column_width_ratio = 0.3
max_column_width_ratio = 0.9
alignment = "center"
focus_navigation_style = "niri"

[layout.scrolling.gestures]
enabled = true
```

--------------------------------

### Get Windows Request

Source: https://github.com/acsandmann/rift/blob/main/_autodocs/endpoints.md

Fetch a list of all windows or windows within a specific space. Provide `space_id` to filter by space, or `null` to get all windows.

```json
{
  "get_windows": {
    "space_id": null
  }
}
```

--------------------------------

### IPC Protocol: Focus Next Window Response

Source: https://github.com/acsandmann/rift/blob/main/_autodocs/api-reference/ipc-protocol.md

Example JSON response indicating the success of the 'next_window' command.

```json
{
  "data": { "success": true }
}

```

--------------------------------

### IPC Protocol: Query Workspaces Response

Source: https://github.com/acsandmann/rift/blob/main/_autodocs/api-reference/ipc-protocol.md

Example JSON response containing a list of workspaces, each with its ID, name, window count, and layout mode.

```json
{
  "data": {
    "workspaces": [
      { "id": "00000001", "name": "1", "window_count": 3, "layout_mode": "traditional" },
      { "id": "00000002", "name": "2", "window_count": 0, "layout_mode": "traditional" }
    ]
  }
}

```

--------------------------------

### TOML Configuration for App Rules

Source: https://github.com/acsandmann/rift/blob/main/_autodocs/api-reference/virtual-workspaces.md

Example TOML configuration snippet for defining application rules in virtual workspaces. This demonstrates how to map applications to specific workspaces and set window management properties.

```toml
[[virtual_workspaces.app_rules]]
app_id = "com.apple.Terminal"
workspace = 1
floating = false
manage = true

[[virtual_workspaces.app_rules]]
app_id = "com.google.Chrome"
workspace = "web"
title_substring = "YouTube"

[[virtual_workspaces.app_rules]]
app_name = "Finder"
workspace = 2
```

--------------------------------

### Get Config Request

Source: https://github.com/acsandmann/rift/blob/main/_autodocs/endpoints.md

Fetch the current configuration settings, including UI preferences, layout modes, and animation settings. No parameters are needed.

```json
{
  "get_config": {}
}
```

--------------------------------

### Get Applications Request

Source: https://github.com/acsandmann/rift/blob/main/_autodocs/endpoints.md

This endpoint fetches a list of all running applications. It does not require any parameters.

```json
{
  "get_applications": {}
}
```

--------------------------------

### run_mach_server

Source: https://github.com/acsandmann/rift/blob/main/_autodocs/api-reference/ipc-protocol.md

Spawns a background Mach server thread and returns its shared state. This function is used to start the Rift server process.

```APIDOC
## run_mach_server

### Description
Spawns a background Mach server thread and returns its shared state. This function is used to start the Rift server process.

### Method
`run_mach_server`

### Parameters
#### Path Parameters
- `reactor` (ReactorHandle) - Yes - Reactor to send commands to
- `config_tx` (config_actor::Sender) - Yes - Config actor sender

### Returns
- `Result<SharedServerState, String>`: Shared server state upon successful startup.

### Throws
- `String`: If another Rift instance is already running.

### Effect
Spawns background Mach server thread and returns shared state for subscriptions.

### Example
```rust
let server_state = run_mach_server(reactor, config_tx)?;
// Server now accepts connections and commands
```
```

--------------------------------

### Sending Events and Commands to Reactor

Source: https://github.com/acsandmann/rift/blob/main/_autodocs/api-reference/reactor.md

Demonstrates how to send various types of events and commands to the Reactor. Includes an example of handling potential errors when sending events.

```rust
use rift::actor::reactor::{ReactorHandle, Event};

// Send an event
reactor_handle.send(Event::ScreenParametersChanged(vec![screen_info]));

// Send a command
let cmd = Command::Layout(LayoutCommand::NextWindow);
reactor_handle.send(Event::Command(cmd));

// Try to send and handle error
if let Err(e) = reactor_handle.try_send(event) {
    eprintln!("Reactor channel closed: {}", e);
}
```

--------------------------------

### Get Virtual Workspace Layout System

Source: https://github.com/acsandmann/rift/blob/main/_autodocs/api-reference/virtual-workspaces.md

Returns a reference to the layout system managing windows within the workspace.

```rust
pub fn tree(&self) -> &LayoutSystemKind
```

--------------------------------

### Execute Command with Rust Client

Source: https://github.com/acsandmann/rift/blob/main/_autodocs/INDEX.md

Send commands to Rift via the Rust client, for example, to move to the next window. Arguments can be passed as a vector of strings.

```rust
let req = RiftRequest::ExecuteCommand {
    command: "next_window".to_string(),
    args: vec![],
};
```

--------------------------------

### Get Window Info Request

Source: https://github.com/acsandmann/rift/blob/main/_autodocs/endpoints.md

Retrieve detailed information about a specific window using its ID. The `window_id` must be provided as a string.

```json
{
  "get_window_info": {
    "window_id": "123"
  }
}
```

--------------------------------

### Creating a Custom Actor in Rust

Source: https://github.com/acsandmann/rift/blob/main/_autodocs/api-reference/actor-system.md

Provides a complete example of defining a custom actor, including its event type, state, channel creation, and the `run` and `handle_event` methods. This serves as a template for building new actors within the Rift framework.

```rust
use rift::actor;

// Define your event type
pub enum MyEvent {
    Foo(String),
    Bar(i32),
}

pub struct MyActor {
    receiver: actor::Receiver<MyEvent>,
    // ... state
}

impl MyActor {
    pub fn new() -> (Self, actor::Sender<MyEvent>) {
        let (sender, receiver) = actor::channel();
        let actor = Self { receiver, /* ... */ };
        (actor, sender)
    }

    pub async fn run(mut self) {
        while let Some((span, event)) = self.receiver.recv().await {
            let _guard = span.enter();
            self.handle_event(event);
        }
    }

    fn handle_event(&mut self, event: MyEvent) {
        match event {
            MyEvent::Foo(s) => println!("Foo: {}", s),
            MyEvent::Bar(i) => println!("Bar: {}", i),
        }
    }
}
```

--------------------------------

### IPC Protocol: Subscribe to Events Request

Source: https://github.com/acsandmann/rift/blob/main/_autodocs/api-reference/ipc-protocol.md

Example JSON request to subscribe to 'workspace_changed' events. The initial response confirms the subscription.

```json
{
  "subscribe": {
    "event": "workspace_changed"
  }
}

```

--------------------------------

### Set Master-Stack Layout for Workspace 2

Source: https://github.com/acsandmann/rift/wiki/Config

Configure specific workspaces to use a different layout mode by default. This example sets workspace with index 2 to use the 'master_stack' layout.

```toml
workspace_rules = [
  { workspace = 2, layout = "master_stack" },
]
```

--------------------------------

### Enable Hot Reload and Restart Rift

Source: https://github.com/acsandmann/rift/blob/main/_autodocs/errors.md

If config changes are not applied, ensure 'hot_reload = true' is set in the '[settings]' section of your configuration. If necessary, restart Rift by killing the process and starting it again.

```bash
# Ensure hot_reload = true in [settings]
# Restart Rift: killall rift && rift
# Check for validation errors in logs
```

--------------------------------

### Build Rift from Source

Source: https://github.com/acsandmann/rift/wiki/Quick-Start

Build the Rift binary and CLI tools in release mode after cloning the repository.

```sh
cargo build --bins --release
```

--------------------------------

### Simple Command Keybinding

Source: https://github.com/acsandmann/rift/blob/main/_autodocs/configuration.md

Illustrates the basic format for assigning a simple command to a key combination. No parameters are required for these actions.

```toml
"Cmd + J" = "next_window"
```

--------------------------------

### Get Workspace Layouts Request

Source: https://github.com/acsandmann/rift/blob/main/_autodocs/endpoints.md

Retrieve layout configurations for workspaces. You can filter by `space_id` or `workspace_id`, or set both to null to get all layouts.

```json
{
  "get_workspace_layouts": {
    "space_id": null,
    "workspace_id": null
  }
}
```

--------------------------------

### Run Rift from Source

Source: https://github.com/acsandmann/rift/wiki/Quick-Start

Execute the Rift application directly from the build output when building from source.

```sh
./target/release/rift
```

--------------------------------

### Command with Parameter Keybinding

Source: https://github.com/acsandmann/rift/blob/main/_autodocs/configuration.md

Shows how to bind keys to commands that require parameters. This allows for more specific actions like moving focus or switching workspaces by index.

```toml
"Cmd + H" = { MoveFocus = "left" }
```

```toml
"Cmd + 1" = { SwitchToWorkspace = 0 }
```

--------------------------------

### Get Virtual Workspace Name

Source: https://github.com/acsandmann/rift/blob/main/_autodocs/api-reference/virtual-workspaces.md

Retrieves the display name of the virtual workspace.

```rust
pub fn name(&self) -> &str
```

--------------------------------

### Get Displays Request

Source: https://github.com/acsandmann/rift/blob/main/_autodocs/endpoints.md

This endpoint retrieves information about all connected displays. It does not require any parameters.

```json
{
  "get_displays": {}
}
```

--------------------------------

### Get Reactor Sender

Source: https://github.com/acsandmann/rift/blob/main/_autodocs/api-reference/reactor.md

Retrieves a cloneable sender for the reactor's event channel.

```rust
pub fn sender(&self) -> Sender
```

--------------------------------

### Virtual Workspace Manager Usage

Source: https://github.com/acsandmann/rift/blob/main/_autodocs/api-reference/virtual-workspaces.md

Demonstrates how to initialize and use the VirtualWorkspaceManager to query workspaces, assign windows, and switch between workspaces. Requires the `rift` crate and relevant settings.

```rust
use rift::model::virtual_workspace::{VirtualWorkspaceManager, AppRuleResult};

let manager = VirtualWorkspaceManager::new(&settings);

// Query a workspace
let ws = manager.workspace(workspace_id).unwrap();
println!("Workspace: {} ({})", ws.name(), ws.window_count());

// Assign window
match manager.assign_window(window_id, &window_info, space) {
    AppRuleResult::Managed(assignment) => {
        let ws = manager.workspace_mut(assignment.workspace_id).unwrap();
        ws.add_window(window_id);
        println!("Added window to {}", ws.name());
    },
    AppRuleResult::Unmanaged => {
        println!("Window not managed by Rift");
    },
}

// Switch workspaces
let changes = manager.switch_workspace(current_id, target_id);
for (window_id, should_show) in changes {
    if should_show {
        show_window(window_id);
    } else {
        hide_window(window_id);
    }
}
```

--------------------------------

### RiftMachClient::connect

Source: https://github.com/acsandmann/rift/blob/main/_autodocs/api-reference/ipc-protocol.md

Establishes a connection to the Rift Mach server.

```APIDOC
## RiftMachClient::connect

### Description
Synchronous client for connecting to the Rift Mach server.

### Method
```rust
pub fn connect() -> Result<Self, String>
```

### Returns
Connected client or error

### Throws
`String` error if server is not registered

### Example
```rust
let client = RiftMachClient::connect()?;
```
```

--------------------------------

### Get Last Focused Window

Source: https://github.com/acsandmann/rift/blob/main/_autodocs/api-reference/virtual-workspaces.md

Retrieves the `WindowId` of the last focused window in this workspace, if one was set.

```rust
pub fn last_focused(&self) -> Option<WindowId>
```

--------------------------------

### Switch Virtual Workspaces

Source: https://github.com/acsandmann/rift/blob/main/_autodocs/api-reference/virtual-workspaces.md

Prepares windows for a workspace switch between two virtual workspaces. It returns a list of window IDs and a boolean indicating whether each window should be shown. The actual visibility changes are applied by the Reactor.

```rust
pub fn switch_workspace(
    &self,
    from: VirtualWorkspaceId,
    to: VirtualWorkspaceId,
) -> Vec<(WindowId, bool))>
```

--------------------------------

### Connect to Rift Mach Server

Source: https://github.com/acsandmann/rift/blob/main/_autodocs/api-reference/ipc-protocol.md

Establishes a connection to the Rift Mach server. Throws an error if the server is not registered.

```rust
let client = RiftMachClient::connect()?;
```

--------------------------------

### HotkeySpec Type Alias

Source: https://github.com/acsandmann/rift/blob/main/_autodocs/types.md

An alias for String, used to define keyboard bindings in configuration. Examples include 'Ctrl + A' or 'Cmd'.

```rust
pub type HotkeySpec = String
```

--------------------------------

### Rift CLI Commands

Source: https://github.com/acsandmann/rift/blob/main/_autodocs/api-reference/ipc-protocol.md

Use the `rift-cli` tool to interact with the Rift server for various operations like managing workspaces, executing commands, subscribing to events, and moving windows.

```bash
rift-cli workspaces
```

```bash
rift-cli command next_window
```

```bash
rift-cli subscribe workspace_changed
```

```bash
rift-cli move-window 2
```

--------------------------------

### Get Opposite HideCorner

Source: https://github.com/acsandmann/rift/blob/main/_autodocs/api-reference/virtual-workspaces.md

Returns the alternative `HideCorner` variant. If the current corner is `BottomLeft`, it returns `BottomRight`, and vice versa.

```rust
pub fn opposite(self) -> Self>
```

--------------------------------

### Get Virtual Workspace Window Count

Source: https://github.com/acsandmann/rift/blob/main/_autodocs/api-reference/virtual-workspaces.md

Returns the total number of windows currently contained within the virtual workspace.

```rust
pub fn window_count(&self) -> usize
```

--------------------------------

### Basic Settings Configuration

Source: https://github.com/acsandmann/rift/wiki/Config

Configure master animation settings like enabling animations, duration, and frames per second.

```toml
[settings]
animate = true
animation_duration = 0.2
animation_fps = 100.0
```

--------------------------------

### Get Virtual Workspace Native Space ID

Source: https://github.com/acsandmann/rift/blob/main/_autodocs/api-reference/virtual-workspaces.md

Retrieves the ID of the native macOS Space associated with this virtual workspace.

```rust
pub fn space(&self) -> SpaceId
```

--------------------------------

### Get Virtual Workspace Manager Reference

Source: https://github.com/acsandmann/rift/blob/main/_autodocs/api-reference/layout-engine.md

Provides read-only access to the VirtualWorkspaceManager, allowing for querying and modification of workspace configurations.

```rust
pub fn virtual_workspace_manager(&self) -> &VirtualWorkspaceManager
```

--------------------------------

### Using Modifier Combinations in Keybindings

Source: https://github.com/acsandmann/rift/blob/main/_autodocs/configuration.md

Demonstrates how to use a defined modifier combination to create a shortcut. This reduces repetition when using the same modifiers frequently.

```toml
[keys]
"cmd_shift + A" = "toggle_floating"
```

--------------------------------

### Check App Rule Configuration

Source: https://github.com/acsandmann/rift/blob/main/_autodocs/errors.md

If a window is not managed, check your app rule configuration. Ensure the 'manage' setting is true or that rules are correctly matched. Verify the app_id or app_name is accurate.

```bash
# Check app rule configuration
# Verify app_id or app_name is correct
# Test with rift-cli window-info <id>
```

--------------------------------

### Query Window List with Rust Client

Source: https://github.com/acsandmann/rift/blob/main/_autodocs/INDEX.md

Connect to the Rift IPC server using the Rust client to programmatically query for window information. Ensure the RiftMachClient is correctly initialized and connected.

```rust
let client = RiftMachClient::connect()?;
let req = RiftRequest::GetWindows { space_id: None };
let resp = client.send_request(&req)?;
```

--------------------------------

### Get Layout State Request

Source: https://github.com/acsandmann/rift/blob/main/_autodocs/endpoints.md

Query the layout state of a specific space. The `space_id` parameter is required and specifies the space to query.

```json
{
  "get_layout_state": {
    "space_id": 1
  }
}
```

--------------------------------

### Rift CLI Commands

Source: https://github.com/acsandmann/rift/blob/main/_autodocs/endpoints.md

Use these commands to interact with Rift workspaces, windows, and events via the CLI. Some commands accept arguments for specific actions.

```bash
# Query workspaces
rift-cli workspaces
```

```bash
# Query windows
rift-cli windows
```

```bash
# Execute command
rift-cli command next_window
```

```bash
# Move window to workspace
rift-cli move-window 2
```

```bash
# Subscribe to events
rift-cli subscribe workspace_changed
```

```bash
# Subscribe with command
rift-cli subscribe workspace_changed -- \
  osascript -e 'display notification "Workspace changed"'
```

--------------------------------

### GetApplications

Source: https://github.com/acsandmann/rift/blob/main/_autodocs/endpoints.md

Fetches a list of running applications.

```APIDOC
## GetApplications

### Description
Fetches a list of running applications.

### Method
query

### Endpoint
/-

### Parameters
None

### Request Example
```json
{
  "get_applications": {}
}
```

### Response
#### Success Response (200)
- **data** (object) - Contains the list of applications.
  - **applications** (array) - List of application objects.
    - **pid** (integer) - The process ID of the application.
    - **name** (string) - The name of the application.
    - **bundle_id** (string) - The bundle identifier of the application.
    - **is_active** (boolean) - Whether the application is currently active.
    - **window_count** (integer) - The number of windows opened by the application.

#### Response Example
```json
{
  "data": {
    "applications": [
      {
        "pid": 456,
        "name": "Visual Studio Code",
        "bundle_id": "com.microsoft.VSCode",
        "is_active": true,
        "window_count": 2
      }
    ]
  }
}
```

### Status Codes
- 200 (success)
```

--------------------------------

### Get a Virtual Workspace by ID

Source: https://github.com/acsandmann/rift/blob/main/_autodocs/api-reference/virtual-workspaces.md

Retrieves a reference to a specific virtual workspace using its ID. Returns `None` if the workspace does not exist.

```rust
pub fn workspace(&self, id: VirtualWorkspaceId) -> Option<&VirtualWorkspace))>
```

--------------------------------

### GetWindows

Source: https://github.com/acsandmann/rift/blob/main/_autodocs/endpoints.md

Fetches a list of all windows or windows within a specific space.

```APIDOC
## GetWindows

### Description
Fetches a list of all windows or windows within a specific space.

### Method
query

### Endpoint
/-

### Parameters
#### Query Parameters
- **space_id** (u64 | null) - Yes - Specific space or null for all

### Request Example
```json
{
  "get_windows": {
    "space_id": null
  }
}
```

### Response
#### Success Response (200)
- **data** (object) - Contains the list of windows.
  - **windows** (array) - List of window objects.
    - **id** (integer) - Unique identifier for the window.
    - **title** (string) - The title of the window.
    - **app** (string) - The application name.
    - **pid** (integer) - The process ID of the application.
    - **workspace_id** (string) - The ID of the workspace the window belongs to.
    - **floating** (boolean) - Whether the window is floating.
    - **frame** (object) - The window's frame.
      - **origin** (object) - The origin coordinates of the frame.
        - **x** (integer) - X-coordinate.
        - **y** (integer) - Y-coordinate.
      - **size** (object) - The size of the frame.
        - **width** (integer) - Width of the frame.
        - **height** (integer) - Height of the frame.

#### Response Example
```json
{
  "data": {
    "windows": [
      {
        "id": 123,
        "title": "editor.rs",
        "app": "Visual Studio Code",
        "pid": 456,
        "workspace_id": "00000001",
        "floating": false,
        "frame": { "origin": {"x": 0, "y": 25}, "size": {"width": 960, "height": 1055} }
      }
    ]
  }
}
```

### Status Codes
- 200 (success)
- 400 (invalid space_id)
```

--------------------------------

### Execute Command: next_window

Source: https://github.com/acsandmann/rift/blob/main/_autodocs/api-reference/ipc-protocol.md

Executes a command to focus the next window.

```APIDOC
## Execute Command: next_window

### Description
Executes a command to focus the next window.

### Request Body
```json
{
  "execute_command": {
    "command": "next_window",
    "args": []
  }
}
```

### Response
#### Success Response (200)
- `data` (object) - Contains the result of the command execution.
  - `success` (boolean) - Indicates if the command was successful.

### Response Example
```json
{
  "data": { "success": true }
}
```
```

--------------------------------

### GetConfig

Source: https://github.com/acsandmann/rift/blob/main/_autodocs/endpoints.md

Fetches the current configuration of the system.

```APIDOC
## GetConfig

### Description
Fetches the current configuration of the system.

### Method
query

### Endpoint
/-

### Parameters
None

### Request Example
```json
{
  "get_config": {}
}
```

### Response
#### Success Response (200)
- **data** (object) - Contains the system configuration.
  - **settings** (object) - General settings.
    - **animate** (boolean) - Whether animations are enabled.
    - **animation_duration** (number) - Duration of animations.
    - **mouse_follows_focus** (boolean) - Whether mouse follows focus.
    - **focus_follows_mouse** (boolean) - Whether focus follows mouse.
  - **layout** (object) - Layout configuration.
    - **mode** (string) - The default layout mode.
    - **gaps** (object) - Gap settings.
      - **outer** (object) - Outer gap settings.
      - **inner** (object) - Inner gap settings.
  - **ui** (object) - UI specific settings.
  - **virtual_workspaces** (object) - Virtual workspace settings.

#### Response Example
```json
{
  "data": {
    "settings": {
      "animate": true,
      "animation_duration": 0.2,
      "mouse_follows_focus": true,
      "focus_follows_mouse": true
    },
    "layout": {
      "mode": "traditional",
      "gaps": { "outer": {...}, "inner": {...} }
    },
    "ui": {...},
    "virtual_workspaces": {...}
  }
}
```

### Status Codes
- 200 (success)
```

--------------------------------

### Get Metrics Request

Source: https://github.com/acsandmann/rift/blob/main/_autodocs/endpoints.md

Retrieve system metrics such as window count, workspace count, and event queue depth. This endpoint requires no parameters.

```json
{
  "get_metrics": {}
}
```

--------------------------------

### Get Workspaces Request

Source: https://github.com/acsandmann/rift/blob/main/_autodocs/endpoints.md

Use this endpoint to fetch a list of all workspaces or a specific workspace by its ID. The `space_id` parameter can be null to retrieve all workspaces.

```json
{
  "get_workspaces": {
    "space_id": null
  }
}
```

--------------------------------

### Execute Command with rift-cli

Source: https://github.com/acsandmann/rift/blob/main/_autodocs/INDEX.md

Execute commands on Rift using the rift-cli, such as navigating to the next window. This is a straightforward way to automate window management tasks.

```bash
rift-cli command next_window
```

--------------------------------

### Get Virtual Workspace Layout Mode

Source: https://github.com/acsandmann/rift/blob/main/_autodocs/api-reference/virtual-workspaces.md

Retrieves the current layout mode of the virtual workspace, such as Traditional, Bsp, Stack, MasterStack, or Scrolling.

```rust
pub fn layout_mode(&self) -> LayoutMode
```

--------------------------------

### Query State via Rift CLI

Source: https://github.com/acsandmann/rift/blob/main/_autodocs/README.md

Interact with Rift using the command-line interface to manage workspaces, execute commands, and subscribe to events.

```bash
# Get all workspaces
rift-cli workspaces
```

```bash
# Execute command
rift-cli command next_window
```

```bash
# Subscribe to events
rift-cli subscribe workspace_changed
```

--------------------------------

### Settings Struct

Source: https://github.com/acsandmann/rift/blob/main/_autodocs/types.md

The main configuration structure for the application. Loaded from config file.

```rust
pub struct Settings {
    pub animate: bool,
    pub animation_duration: f64,
    pub animation_fps: f64,
    pub animation_easing: AnimationEasing,
    pub default_disable: bool,
    pub mouse_follows_focus: bool,
    pub mouse_hides_on_focus: bool,
    pub focus_follows_mouse: bool,
    pub focus_follows_mouse_disable_hotkey: Option<HotkeySpec>,
    pub auto_focus_blacklist: Vec<String>,
    pub layout: LayoutSettings,
    pub ui: UiSettings,
    pub gestures: GestureSettings,
    pub window_snapping: WindowSnappingSettings,
    pub run_on_start: Vec<String>,
    pub hot_reload: bool,
}

```

--------------------------------

### Get a Mutable Virtual Workspace by ID

Source: https://github.com/acsandmann/rift/blob/main/_autodocs/api-reference/virtual-workspaces.md

Retrieves a mutable reference to a specific virtual workspace using its ID. Returns `None` if the workspace does not exist.

```rust
pub fn workspace_mut(&mut self, id: VirtualWorkspaceId) -> Option<&mut VirtualWorkspace))>
```

--------------------------------

### Rift Data Flow Diagram

Source: https://github.com/acsandmann/rift/blob/main/_autodocs/README.md

Illustrates the sequence of events from system APIs to window server application and broadcasted events.

```text
System Events (macOS APIs)
    ↓
Event Tap & Gesture Tap
    ↓
WM Controller
    ↓
Reactor (state machine)
    ↓
Layout Engine (compute frames)
    ↓
Window Server (apply frames)
    ↓
Broadcast Events (IPC subscribers)
```

--------------------------------

### Subscribe to Events with Rust Client

Source: https://github.com/acsandmann/rift/blob/main/_autodocs/INDEX.md

Set up event subscriptions with the Rift IPC server using the Rust client. The client will continuously receive events until the subscription is closed.

```rust
let sub = client.subscribe("workspace_changed")?;
loop {
    let event = sub.recv_event()?;
    println!("Event: {}", event);
}
```

--------------------------------

### Subscribe to Events with rift-cli

Source: https://github.com/acsandmann/rift/blob/main/_autodocs/INDEX.md

Subscribe to specific events from Rift using the rift-cli, such as workspace changes. This allows monitoring of Rift's state.

```bash
rift-cli subscribe workspace_changed
```

--------------------------------

### IPC Endpoints Documentation

Source: https://github.com/acsandmann/rift/blob/main/_autodocs/COMPLETION_SUMMARY.txt

Documentation for all Inter-Process Communication (IPC) endpoints, detailing their methods, request and response schemas, status codes, errors, and providing actual JSON examples.

```APIDOC
## IPC Endpoints

This section details all IPC endpoints available in the Rift Window Manager.

### Endpoint Documentation Format

Each endpoint is documented with:
- Method/request type
- Request schema table
- Response schema table
- Status codes and errors
- Examples with actual JSON

### Example Endpoint Structure (Illustrative)

## [METHOD] [ENDPOINT_PATH]

### Description
[Brief description of the endpoint's purpose.]

### Method
[HTTP method or IPC request type]

### Endpoint
[Full endpoint path or identifier]

### Request Schema
| Field | Type | Required/Optional | Description |
|---|---|---|---|
| field1 | string | Required | Description of field1 |
| field2 | integer | Optional | Description of field2 |

### Response Schema
| Field | Type | Description |
|---|---|---|
| responseField1 | boolean | Description of responseField1 |
| responseField2 | array | Description of responseField2 |

### Status Codes and Errors
- **200 OK**: Successful operation.
- **400 Bad Request**: Invalid request payload.
- **404 Not Found**: Resource not found.
- **500 Internal Server Error**: Server error.

### Examples
#### Request Example
```json
{
  "field1": "value1",
  "field2": 123
}
```

#### Response Example (Success)
```json
{
  "responseField1": true,
  "responseField2": ["item1", "item2"]
}
```

#### Response Example (Error)
```json
{
  "error": "Bad Request",
  "message": "Invalid input provided."
}
```
```

--------------------------------

### Sending Events to Reactor

Source: https://github.com/acsandmann/rift/blob/main/_autodocs/api-reference/actor-system.md

Demonstrates the typical pattern for initializing a Window Manager controller with a Reactor sender and sending events from an event handler. Ensure you have a `reactor::Sender` instance available.

```rust
use reactor::Sender;

// In WM Controller
let (mut wm_controller, wm_sender) = WmController::new(
    config,
    events_tx,  // reactor::Sender
    event_tap_tx,
    stack_line_tx,
    mission_control_tx,
    gesture_tap_tx,
    window_tx_store,
);

// In event handler
if some_condition {
    events_tx.send(reactor::Event::WindowCreated(window_id, info, None, None));
}
```

--------------------------------

### Define Keybindings

Source: https://github.com/acsandmann/rift/wiki/Config

Example of defining keybindings in TOML format. Use quotes around key combinations and specify commands or command objects. Custom modifier combinations can be referenced.

```toml
"Alt + H" = { move_focus = "left" }
"Alt + Shift + Left" = { join_window = "left" }
"Alt + 1" = { switch_to_workspace = 1 }
"comb1 + S" = { switch_to_workspace = 2 }
```

--------------------------------

### Inspect Rift State

Source: https://github.com/acsandmann/rift/blob/main/_autodocs/errors.md

Use rift-cli commands to inspect the current state of Rift, including all workspaces, windows on a space, and the current layout.

```bash
# View all workspaces
ift-cli workspaces

# View windows on a space
ift-cli windows

# View layout
ift-cli layout-state
```

--------------------------------

### Try Send Event to Actor

Source: https://github.com/acsandmann/rift/blob/main/_autodocs/api-reference/actor-system.md

Attempts to send an event to an actor, returning a Result. This is useful when you need to know if the send operation failed, for example, if the actor's channel has been closed.

```rust
reactor_sender.try_send(event)?;
```

--------------------------------

### VirtualWorkspaceManager::switch_workspace

Source: https://github.com/acsandmann/rift/blob/main/_autodocs/api-reference/virtual-workspaces.md

Prepares the visibility of windows when switching between two virtual workspaces. It returns a list of window IDs and a boolean indicating whether each window should be shown.

```APIDOC
## VirtualWorkspaceManager::switch_workspace

### Description
Prepares windows for visibility changes during a workspace switch.

### Method
`switch_workspace`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **from** (`VirtualWorkspaceId`) - Required - Current workspace
- **to** (`VirtualWorkspaceId`) - Required - Target workspace

### Returns
Vec of `(window_id, should_show)` tuples to update visibility

### Effect
Prepares windows for show/hide; doesn't apply changes (Reactor does)
```

--------------------------------

### IPC Protocol: Subscribe to Events Response (Subsequent)

Source: https://github.com/acsandmann/rift/blob/main/_autodocs/api-reference/ipc-protocol.md

Example JSON format for subsequent 'workspace_changed' events streamed after a successful subscription. Includes event details like ID and timestamp.

```json
{
  "event": "workspace_changed",
  "workspace_id": 1,
  "timestamp": 1234567890
}

```

--------------------------------

### Initialize VirtualWorkspaceManager

Source: https://github.com/acsandmann/rift/blob/main/_autodocs/api-reference/virtual-workspaces.md

Creates a new VirtualWorkspaceManager with the specified settings. The settings define the initial count, names, and rules for the workspaces.

```rust
pub fn new(settings: &VirtualWorkspaceSettings) -> Self>
```

--------------------------------

### Add Hotkey Bindings in TOML

Source: https://github.com/acsandmann/rift/blob/main/_autodocs/INDEX.md

Configure custom keyboard shortcuts by editing the `~/.config/rift/config.toml` file under the `[keys]` section. Bindings can trigger specific Rift commands or actions.

```toml
[keys]
"Cmd + Space" = "toggle_space_activated"
"Cmd + J" = "next_window"
"Cmd + H" = { MoveFocus = "left" }
```

--------------------------------

### Handle IPC Errors with RiftMachClient

Source: https://github.com/acsandmann/rift/blob/main/_autodocs/errors.md

Shows how to connect to the Rift server using RiftMachClient and handle responses, specifically focusing on parsing and reacting to error messages received from the server. This is useful for debugging and user feedback.

```rust
use rift::ipc::RiftMachClient;

let client = RiftMachClient::connect()
    .expect("Rift server must be running");

match client.send_request(&request) {
    Ok(RiftResponse::Success { data }) => {
        println!("Result: {}", data);
    },
    Ok(RiftResponse::Error { error }) => {
        eprintln!("Error: {}", error);
        // Handle error based on error message
        let err_str = error.to_string();
        if err_str.contains("Unknown command") {
            eprintln!("Invalid command; check configuration");
        }
    },
    Err(e) => {
        eprintln!("Client error: {}", e);
    }
}
```

--------------------------------

### Handle Command in LayoutEngine

Source: https://github.com/acsandmann/rift/blob/main/_autodocs/api-reference/layout-engine.md

Handles layout commands for a specific space, processing commands like moving to the next window. Returns an EventResponse containing information about windows to focus or raise.

```rust
pub fn handle_command(
    &mut self,
    command_space: Option<SpaceId>,
    visible_spaces: &[SpaceId],
    visible_space_centers: &[CGPoint],
    cmd: LayoutCommand,
) -> EventResponse
```

```rust
let response = layout_engine.handle_command(
    Some(space_id),
    &[space_id],
    &[CGPoint::new(960.0, 540.0)],
    LayoutCommand::NextWindow,
);
if let Some(window) = response.focus_window {
    // Focus this window
}
```

--------------------------------

### Check Command Existence and Format

Source: https://github.com/acsandmann/rift/blob/main/_autodocs/errors.md

When encountering an 'Unknown command' error, verify the command exists in configuration.md and follows the snake_case format. Also, check if the correct number of arguments are provided.

```bash
# Check command exists in configuration.md
# Verify snake_case format (e.g., next_window not nextWindow)
# Check command takes correct number of arguments
```

--------------------------------

### Layout Engine Methods

Source: https://github.com/acsandmann/rift/blob/main/_autodocs/INDEX.md

Methods for interacting with the layout engine to manage window tiling and state.

```APIDOC
## Layout Engine (`src/layout_engine/`)

### Description
Provides methods to execute layout commands, handle virtual workspace operations, and process layout events.

### Methods
- `LayoutEngine::handle_command()`
- `LayoutEngine::handle_virtual_workspace_command()`
- `LayoutEngine::process_event()`

### Exported Types
- `LayoutCommand`
- `LayoutEvent`
- `EventResponse`
- `LayoutEngine`
- `LayoutMode`
- `Direction`
```

--------------------------------

### Rift Configuration File Structure

Source: https://github.com/acsandmann/rift/blob/main/_autodocs/configuration.md

Defines the top-level sections of a complete Rift configuration file. These sections manage global settings, layout, keybindings, UI elements, and virtual workspace configurations.

```toml
[settings]
# Global settings

[layout]
# Layout mode and gaps

[keys]
# Keyboard bindings

[ui]
# UI (menu bar, stack line, mission control)

[[keys]]
# Alternative key binding format

[virtual_workspaces]
# Workspace configuration

[[virtual_workspaces.app_rules]]
# App rules (multiple, in array)

[[virtual_workspaces.workspace_rules]]
# Workspace-specific layout rules

```

--------------------------------

### ExecuteCommand

Source: https://github.com/acsandmann/rift/blob/main/_autodocs/endpoints.md

Executes a specified command with optional arguments. This endpoint is used to interact with and modify the state of the Rift system.

```APIDOC
## POST /execute_command

### Description
Executes a specified command with optional arguments. This endpoint is used to interact with and modify the state of the Rift system.

### Method
POST

### Endpoint
/execute_command

### Parameters
#### Request Body
- **command** (string) - Required - Command name (snake_case)
- **args** (array of strings) - Required - Command arguments

### Request Example
```json
{
  "execute_command": {
    "command": "next_window",
    "args": []
  }
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the command execution was successful.

#### Response Example
```json
{
  "data": {
    "success": true
  }
}
```

#### Error Response (400, 500)
- **error** (string) - Description of the error encountered during command execution.

#### Error Response Example
```json
{
  "error": "Unknown command: foo"
}
```

### Status Codes
- 200: Success
- 400: Invalid command
- 500: Execution error
```