URL Scheme API

Complete reference for Loop URL scheme commands for automation

Overview

Loop supports URL scheme commands for window management and automation. All commands use the base format:

loop://<command>/<parameters>

All commands are case-insensitive and operate on the frontmost non-terminal window.

Base URL Format

scheme · string · required

Must be loop

command · string · required

The command type: direction, screen, action, keybind, or list

parameters · string

Command-specific parameters (varies by command type)

---

Direction Commands

Move or resize windows using directional commands.

Endpoint

loop://direction/<direction>

Parameters

direction · string · required

The direction to move or resize the window. Supports both short and full names.

Basic directions:

• left - Move window to left half
• right - Move window to right half
• top - Move window to top half
• bottom - Move window to bottom half
• maximize - Maximize window
• center - Center window

Full names: Any value from WindowDirection enum (e.g., leftHalf, rightHalf, topHalf, bottomHalf)

Examples

# Basic directions
open "loop://direction/left"
open "loop://direction/right"
open "loop://direction/top"
open "loop://direction/bottom"

# Full names
open "loop://direction/maximize"
open "loop://direction/center"

Response

success · void

Window is moved/resized to the specified direction. No return value.

Error Responses

error · string

Returns error message to console/log:

• "No direction specified" - Missing direction parameter
• "Invalid direction: <value>" - Unknown direction value
• "No suitable windows or screen found" - No eligible window to operate on

---

Screen Commands

Move windows between multiple displays.

Endpoint

loop://screen/<command>

Parameters

command · string · required

Screen movement command:

• next - Move window to next screen
• previous - Move window to previous screen

Examples

# Move to next screen
open "loop://screen/next"

# Move to previous screen
open "loop://screen/previous"

Response

success · void

Window is moved to the target screen. No return value.

Error Responses

error · string

Returns error message to console/log:

• "No screen command or window" - Missing parameter or no active window
• "Failed to find target screen" - No available screen in requested direction

---

Action Commands

Execute predefined window actions or custom actions.

Endpoint

loop://action/<action>

Parameters

action · string · required

The action to execute. Can be:

Predefined actions:

• Any WindowDirection value (e.g., maximize, leftHalf, rightHalf)
• See loop://list/actions for complete list

Custom actions:

• Any custom action name you’ve defined in Loop settings
• Custom action names are case-insensitive

Stash actions:

• Any stash action name you’ve defined

Examples

# Predefined actions
open "loop://action/maximize"
open "loop://action/leftHalf"
open "loop://action/center"

# Custom actions (if defined)
open "loop://action/myCustomLayout"

# List all available actions
open "loop://action/list"

Response

success · void

Action is executed on the target window. No return value.

list · file

When using loop://action/list, opens a temporary text file with categorized actions:

• Custom Actions
• Stash Actions
• General Actions
• Halves
• Quarters
• Horizontal Thirds
• Vertical Thirds
• Screen Switching
• Size Adjustment
• Shrink
• Grow
• Move
• Other

Error Responses

error · string

Returns error message to console/log:

• "Invalid action: <value>" - Unknown action name
• "Could not find a suitable window to apply the custom action" - No eligible window

---

Keybind Commands

Execute custom keybind actions by name.

Endpoint

loop://keybind/<name>

Parameters

name · string · required

The name of the custom keybind to execute. Must match a keybind name defined in Loop settings.

• Names are case-insensitive
• Use loop://keybind/list or loop://list/keybinds to see available keybinds

Examples

# Execute custom keybind
open "loop://keybind/myCustomLayout"

# List all keybinds
open "loop://keybind/list"

Response

success · void

Keybind is executed on the target window. No return value.

list · array

When using loop://keybind/list, prints available keybind names to console.

Error Responses

error · string

Returns error message to console/log:

• "No keybind specified" - Missing name parameter
• "Keybind not found: <name>" - No keybind with that name exists

---

List Commands

View available commands, actions, and keybinds.

Endpoint

loop://list/<type>

Parameters

type · string · default: "all"

The type of items to list:

• actions - List all window actions (predefined and custom)
• keybinds - List all custom keybinds
• all - List all commands, actions, and keybinds

Examples

# List all actions
open "loop://list/actions"

# List all keybinds
open "loop://list/keybinds"

# List everything
open "loop://list/all"

Response

output · file

Opens a temporary text file (auto-deleted after 60 seconds) containing:

For loop://list/actions:

• Custom Actions (if any defined)
• Stash Actions (if any defined)
• General Actions
• Halves (leftHalf, rightHalf, topHalf, bottomHalf)
• Quarters (topLeft, topRight, bottomLeft, bottomRight)
• Horizontal Thirds
• Vertical Thirds
• Screen Switching (nextScreen, previousScreen)
• Size Adjustment
• Shrink
• Grow
• Move
• Other

For loop://list/keybinds:

• All named custom keybinds with their URL format

For loop://list/all:

• All direction commands
• All screen commands
• All actions (custom and predefined)
• All keybind commands
• All list commands

---

Error Handling

Invalid Scheme

If the URL scheme is not loop://, returns:

Invalid scheme: <scheme>
Required format: loop://<command>/<parameters>

Invalid Command

If the command is not recognized, returns:

Invalid command: <command>
Available commands: direction, screen, action, keybind, list

Missing Parameters

Each command type provides specific guidance when parameters are missing. For example:

# Missing direction
open "loop://direction"
# Returns: No direction specified
# Available directions: left, right, top, bottom, ...

---

Window Selection

Loop automatically selects the target window using this priority:

1. User-defined target - Window selected via Loop’s target window mechanism
2. Last active window - Window that was active within the last 5 seconds
3. Frontmost window - First eligible window in the window list

Eligible Windows

Windows must meet these criteria:

• Not the Loop application itself
• Regular activation policy (not background-only apps)
• Visible (not hidden or minimized)

---

Usage Tips

• All commands are case-insensitive
• Parameters with spaces must be URL-encoded
• Use list commands to discover available options dynamically
• Commands can be executed from Terminal, AppleScript, or any automation tool

Window commands operate on the frontmost non-terminal window. Ensure the target window is active before executing commands for predictable results.

Integration Examples

Shell Script

#!/bin/bash
# Move window right and then maximize
open "loop://direction/right"
sleep 0.5
open "loop://action/maximize"

Keyboard Maestro

Execute Shell Script:
  open "loop://action/leftHalf"

Alfred Workflow

open "loop://action/{query}"

Hammerspoon

os.execute('open "loop://direction/left"')

---

Command Reference Table

Command	Format	Description
Direction	loop://direction/<direction>	Move/resize window
Screen	loop://screen/<next|previous>	Move between displays
Action	loop://action/<action>	Execute predefined or custom action
Keybind	loop://keybind/<name>	Execute named keybind
List	loop://list/<type>	View available commands