Omarchy Shell IPC Methods for CLI Communication: Complete API Reference

The Omarchy desktop environment exposes nine core IPC methods—including ping, summon, hide, toggle, call, rescanPlugins, reloadConfig, setPluginEnabled, and listPlugins—through a Quickshell-based shell target that the omarchy-shell CLI wrapper invokes for scriptable UI control.

The Omarchy desktop by Basecamp runs as a single long-lived Quickshell instance named omarchy-shell. When automating window management or controlling UI panels from external scripts, developers communicate through the Omarchy shell IPC methods exposed via Quickshell's inter-process communication protocol.

IPC Architecture Overview

The Omarchy shell IPC system relies on three coordinated components: the long-running Quickshell process, a thin CLI wrapper, and a dynamic plugin registry that manages available targets.

The Quickshell Process

At shell/shell.qml, Omarchy initializes its primary Quickshell instance. Hyprland launches this process at startup, and it persists for the entire desktop session. The entry point registers the default shell IPC target and initializes the plugin subsystem. Any plugin may register additional IPC targets (such as omarchy.menu or image-selector) beyond the core shell target.

The CLI Wrapper Script

The bin/omarchy-shell executable provides the user-facing interface. Rather than requiring users to type raw Quickshell commands, this wrapper forwards arguments to the running Quickshell instance using quickshell ipc -p $OMARCHY_PATH/shell. The script manages the OMARCHY_SHELL_IPC_TIMEOUT environment variable, normalizes error messages (such as "not running" or "not ready"), and adds timeout handling for reliability.

Plugin Registry and Target Management

Located at shell/services/PluginRegistry.qml, the registry discovers both built-in and user-defined plugins by scanning plugin directories. It maintains the enabled state for each plugin and handles hot-reloading when rescanPlugins is invoked. The registry also registers any extra IPC targets that individual plugins expose, making them available to the CLI.

Core IPC Methods Reference

The shell target exposes nine distinct IPC methods documented in the contract at shell/README.md lines 68-87. Each method follows a strict signature and return contract.

ping

Signature: ping
Returns: ok
Effect: Performs a health check to verify that the Quickshell process is responsive and accepting commands. Use this to confirm the shell is running before issuing critical UI commands.

summon

Signature: summon <id> <payloadJson>
Returns: ok or unknown
Effect: Loads and opens a panel or overlay plugin identified by <id>. The <payloadJson> argument passes initialization parameters to the plugin. Returns unknown if the plugin identifier does not exist in the registry.

hide

Signature: hide <id>
Returns: (empty)
Effect: Closes a previously summoned plugin panel without unloading it from memory. This removes the UI element from view while keeping the plugin instance active for rapid resummoning.

toggle

Signature: toggle <id> <payloadJson>
Returns: (empty)
Effect: Switches the plugin state between open and closed. If the plugin is currently hidden, toggle behaves like summon and opens it with the provided JSON payload. If the plugin is currently visible, toggle behaves like hide and closes it. This is the primary method for menu and panel interactions.

call

Signature: call <id> <method> <arg>
Returns: string
Effect: Invokes a specific method on an already-loaded plugin instance. Unlike summon, which initializes the plugin, call executes arbitrary functionality exposed by the plugin's API. The <arg> parameter passes as a string argument to the method.

rescanPlugins

Signature: rescanPlugins
Returns: (empty)
Effect: Re-walks the plugin directories and hot-reloads plugin code without restarting the Quickshell process. Use this after editing plugin QML files or adding new plugins to the filesystem.

reloadConfig

Signature: reloadConfig
Returns: ok
Effect: Reloads the ~/.config/omarchy/shell.json configuration file and applies changes immediately. This affects global shell settings without requiring a session restart.

setPluginEnabled

Signature: setPluginEnabled <id> <enabled>
Returns: ok or unknown
Effect: Toggles the persisted enabled bit for a plugin in shell.json. When disabled, the plugin will not load on subsequent shell restarts. Returns unknown if the plugin identifier is not found in the registry.

listPlugins

Signature: listPlugins
Returns: JSON
Effect: Returns a JSON array containing every discovered plugin sorted by name, including metadata about their enabled state and availability. Pipe this output to jq for filtering or use it to build dynamic UI menus.

Practical CLI Usage Examples

The omarchy-shell wrapper simplifies IPC invocation. Below are common operations demonstrating the nine core methods:

# 1. Basic health check

omarchy-shell shell ping

# Output: ok

# 2. Summon a panel (e.g., the clock) with configuration payload

omarchy-shell shell summon omarchy.clock '{"menu":"root"}'

# 3. Hide a specific panel

omarchy-shell shell hide omarchy.clock

# 4. Toggle a panel (open if closed, close if open)

omarchy-shell shell toggle omarchy.clock '{"menu":"root"}'

# 5. Call a custom method on a loaded plugin

omarchy-shell shell call omarchy.menu reload "{}"

# 6. Reload all plugins after editing code

omarchy-shell shell rescanPlugins

# 7. Reload the shell's configuration file

omarchy-shell shell reloadConfig

# 8. Enable or disable a plugin persistently

omarchy-shell shell setPluginEnabled omarchy.weather true

# 9. List all discovered plugins with metadata

omarchy-shell shell listPlugins | jq .

Key Source Files

Understanding the IPC implementation requires familiarity with these specific files in the basecamp/omarchy repository:

• shell/README.md — Defines the IPC contract, method signatures, and return values at lines 68-87. This is the authoritative specification for the protocol.

• bin/omarchy-shell — The CLI wrapper script that translates user commands into Quickshell IPC invocations, handling timeouts and error normalization.

• shell/shell.qml — The entry point for the long-running Quickshell process that instantiates the shell IPC target and initializes the plugin system.

• shell/services/PluginRegistry.qml — Manages plugin discovery, IPC target registration beyond the default shell target, and the hot-reload mechanism.

• shell/plugins/README.md — Documents first-party plugins and their specific IPC targets, such as omarchy.menu or specialized overlay handlers.

Summary

• The Omarchy shell exposes nine IPC methods through the default shell target: ping, summon, hide, toggle, call, rescanPlugins, reloadConfig, setPluginEnabled, and listPlugins.

• Communication flows through Quickshell IPC, invoked via the omarchy-shell wrapper script located at bin/omarchy-shell.

• The PluginRegistry at shell/services/PluginRegistry.qml manages plugin discovery and can register additional IPC targets beyond the core shell interface.

• Methods like toggle and call enable dynamic UI control, while rescanPlugins and reloadConfig support runtime configuration changes without session restart.

Frequently Asked Questions

How do I verify the Omarchy shell is running before sending commands?

Use the ping method via omarchy-shell shell ping. If the process is responsive, it returns ok. If the shell is not running or not ready, the wrapper script returns an error message indicating "not running" or "not ready" based on the OMARCHY_SHELL_IPC_TIMEOUT check.

Can I communicate directly with individual plugins instead of the main shell target?

Yes. While the default shell target provides plugin lifecycle management, individual plugins can register their own IPC targets (such as omarchy.menu or image-selector) through the PluginRegistry. Use omarchy-shell <target-name> <method> <args> to communicate directly with these plugin-specific targets.

What is the difference between summon and toggle for plugin panels?

The summon command always attempts to load and show the plugin, returning unknown if the plugin is already open or unavailable. The toggle command checks the current state: if the plugin is hidden, it summons it; if visible, it hides it. Use toggle for menu buttons where the same keybinding should both open and close a panel.

How do I apply changes after editing plugin source code?

Run omarchy-shell shell rescanPlugins to trigger the PluginRegistry to re-walk the plugin directories and hot-reload changed QML files without restarting the entire Quickshell process. For configuration changes in shell.json, use omarchy-shell shell reloadConfig instead.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}