# Omarchy Shell IPC Methods for CLI Communication: Complete API Reference > Explore Omarchy shell IPC methods for CLI communication. Learn to control your UI scriptably with ping, summon, hide, and more. Full API reference included. - Repository: [37signals/omarchy](https://github.com/basecamp/omarchy) - Tags: api-reference - Published: 2026-08-25 --- **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`](https://github.com/basecamp/omarchy/blob/main/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 ` **Returns:** `ok` or `unknown` **Effect:** Loads and opens a panel or overlay plugin identified by ``. The `` argument passes initialization parameters to the plugin. Returns `unknown` if the plugin identifier does not exist in the registry. ### hide **Signature:** `hide ` **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 ` **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 ` **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 `` 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 ` **Returns:** `ok` or `unknown` **Effect:** Toggles the persisted enabled bit for a plugin in [`shell.json`](https://github.com/basecamp/omarchy/blob/main/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: ```bash # 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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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 ` 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`](https://github.com/basecamp/omarchy/blob/main/shell.json), use `omarchy-shell shell reloadConfig` instead.