# Complete Guide to Omarchy Shell IPC Commands: API Reference and Examples

> Master Omarchy shell IPC commands. Control plugins, manage widgets, and reload config with this comprehensive API reference and examples. Explore summon, toggle, and reloadConfig.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: api-reference
- Published: 2026-09-08

---

**The Omarchy desktop exposes a lightweight IPC interface through the `omarchy-shell` binary, enabling command-line tools to control plugins, manipulate bar widgets, and reload configuration in the running Quickshell process using standardized methods like `summon`, `toggle`, and `reloadConfig`.**

The Omarchy desktop environment from the **omacom/omarchy** repository operates as a single long-living Quickshell process that implements a comprehensive **IPC command** architecture for real-time external interaction. All CLI utilities communicate with the shell through the `omarchy-shell` helper binary, which forwards requests to the running instance and returns plugin responses via STDOUT. This design enables dynamic widget manipulation, hot-reloading, and live theming without requiring a desktop session restart.

## Core IPC Architecture

### The omarchy-shell Bridge

The executable **`bin/omarchy-shell`** (generated at install time) serves as the command-line gateway to the running shell. When invoked, it targets the **`shell`** service by default, though individual plugins register their own IPC targets (e.g., `omarchy.clock`, `omarchy.power`, `image-selector`). The binary forwards arguments to the Quickshell process and prints the plugin's JSON response to STDOUT. If the shell is not running, the call fails unless the `-q` flag enables quiet best-effort mode.

### Plugin Registry Implementation

The concrete IPC dispatcher mapping these commands to plugin objects is implemented in **`shell/services/PluginRegistry.qml`**. This QML service handles method routing, plugin lifecycle management, and state synchronization. The authoritative command specification resides in **[`docs/omarchy-shell.md`](https://github.com/omacom/omarchy/blob/main/docs/omarchy-shell.md)** starting at line 99, which defines the complete method table and parameter signatures.

## Essential IPC Command Reference

### Plugin Lifecycle and Visibility

Control plugin loading and visibility using these core **IPC commands**:

- **`ping`** — Performs a health check returning `ok` when the shell is reachable. Use this to verify the desktop is running before issuing subsequent commands.

- **`summon <id> <payloadJson>`** — Loads a plugin if not already active and opens its interface. Example payload: `'{"menu":"apps"}'` for the menu plugin.

- **`hide <id>`** — Closes a previously summoned plugin instance without unloading it from memory.

- **`toggle <id> <payloadJson>`** — Opens the plugin if closed, or closes it if already open. Ideal for quick-access widgets like the clock or power menu.

### Bar Widget Management

Manipulate the desktop bar layout and widget properties dynamically:

- **`togglePanelAt <section> <index>`** — Toggles the panel occupying a specific bar section and index position directly.

- **`enablePlugin <id> <placementJson>`** — Enables a plugin and places it in a bar section in one atomic operation. Example: `omarchy-shell shell enablePlugin omarchy.clock '{"section":"center","index":0}'`.

- **`putBarWidget <id> <placementJson>`** — Idempotent insertion that adds a widget only if it is not already present in the bar.

- **`moveBarWidget <id> <placementJson>`** — Repositions an existing widget within the bar layout. Useful for reordering: `omarchy-shell shell moveBarWidget omarchy.clock '{"section":"right","index":1}'`.

- **`setBarWidget <id> <key> <valueJson> <selectorJson>`** — Updates inline widget options such as format strings or colors. Example changing clock format: `omarchy-shell shell setBarWidget omarchy.clock format '"HH:mm:ss"' '{}'`.

### Configuration and Theming

Modify system behavior and appearance without restarting:

- **`reloadConfig`** — Reloads the [`shell.json`](https://github.com/omacom/omarchy/blob/main/shell.json) configuration file to apply layout changes immediately.

- **`applyTheme <colorsB64> <shellB64>`** — Pushes a new theme (base64-encoded colors and shell settings) to the running instance for live theme switching.

- **`toggleBarTransparency`** — Switches the bar background between solid and transparent states.

- **`setPluginEnabled <id> <"true"|"false">`** — Enables or disables a plugin entirely, returning `ok` or `unknown` status.

### Development and Diagnostics

Inspect and debug the running system:

- **`call <id> <method> <arg>`** — Invokes custom RPC methods on already-loaded plugins. Enables deep integration: `omarchy-shell shell call omarchy.weather getCurrentLocation`.

- **`rescanPlugins`** — Re-walks plugin directories and hot-reloads changed code without restarting the shell.

- **`listPlugins`** — Emits a JSON array describing every discovered plugin, useful for inventory and status checks.

- **`listShellConfig`** — Dumps the effective [`shell.json`](https://github.com/omacom/omarchy/blob/main/shell.json) configuration as JSON for debugging.

- **`debugBarGeometry`** — Prints a detailed geometry dump for troubleshooting bar placement issues.

## Practical IPC Usage Examples

These commands constitute the canonical interface used by all Omarchy CLI tools such as `omarchy-toggle`, `omarchy-update`, and `omarchy-theme-set`.

```bash

# Verify the shell is alive before proceeding

omarchy-shell shell ping

# Output: ok

# Open the application menu with specific payload

omarchy-shell shell summon omarchy.menu '{"menu":"apps"}'

# Toggle the clock widget visibility

omarchy-shell shell toggle omarchy.clock '{}'

# Change clock format in real-time

omarchy-shell shell setBarWidget omarchy.clock format '"HH:mm:ss"' '{}'

# Hide the clock widget

omarchy-shell shell hide omarchy.clock

# List all loaded plugins and extract IDs

omarchy-shell shell listPlugins | jq '.[] .id'

# Reload configuration after editing ~/.config/omarchy/shell.json

omarchy-shell shell reloadConfig

# Apply a new theme with base64-encoded parameters

omarchy-shell shell applyTheme "$COLORS_B64" "$SHELL_B64"

```

## Implementation and Source Files

The IPC system relies on these critical source locations:

| File | Purpose |
|------|---------|
| [`docs/omarchy-shell.md`](https://github.com/omacom/omarchy/blob/main/docs/omarchy-shell.md) | Authoritative documentation defining the command table at line 99 and parameter specifications. |
| `shell/services/PluginRegistry.qml` | QML implementation of the IPC dispatcher that routes commands to plugin objects. |
| [`test/shell.d/runtime-smoke-test.sh`](https://github.com/omacom/omarchy/blob/main/test/shell.d/runtime-smoke-test.sh) | Integration test suite exercising every IPC method to guarantee reliability. |
| `bin/omarchy-shell` | Generated executable that marshals CLI arguments into IPC calls. |

Because the IPC layer is thin and text-based, any new command added to `PluginRegistry.qml` becomes immediately available via the command line without requiring updates to `omarchy-shell` itself.

## Summary

- The **Omarchy shell IPC interface** exposes 18+ methods for controlling the desktop via `omarchy-shell`.
- **Plugin lifecycle** methods (`summon`, `hide`, `toggle`) manage visibility while `enablePlugin` and `setPluginEnabled` control activation state.
- **Bar manipulation** commands allow dynamic widget placement, reordering, and property updates without config reloads.
- **Configuration methods** (`reloadConfig`, `applyTheme`) support hot-reloading of layout and appearance changes.
- The implementation resides in **`shell/services/PluginRegistry.qml`** with documentation in **[`docs/omarchy-shell.md`](https://github.com/omacom/omarchy/blob/main/docs/omarchy-shell.md)**.

## Frequently Asked Questions

### How does the omarchy-shell binary communicate with the running desktop?

The `bin/omarchy-shell` executable forwards command-line arguments to the long-living Quickshell process through a lightweight IPC mechanism. It targets the `shell` service by default or plugin-specific targets (like `omarchy.clock`), printing JSON responses to STDOUT and failing if the shell is not running (unless using the `-q` quiet flag).

### What is the difference between `summon` and `enablePlugin`?

The **`summon`** command loads and opens a plugin temporarily, while **`enablePlugin`** permanently adds a plugin to the bar configuration with a specific placement. Use `summon` for temporary overlays and `enablePlugin` for persistent widget additions that survive config reloads.

### Can I call custom methods on any loaded plugin?

Yes. The **`call`** method enables arbitrary RPC invocations on any active plugin using the signature `call <id> <method> <arg>`. This allows external scripts to execute plugin-specific functions like `omarchy-shell shell call omarchy.weather getCurrentLocation`, provided the plugin implements the target method in its QML code.

### Where is the authoritative list of IPC commands documented?

The complete method table is documented in **[`docs/omarchy-shell.md`](https://github.com/omacom/omarchy/blob/main/docs/omarchy-shell.md)** starting at line 99. This file specifies all 18+ commands, their parameters, return values, and typical use cases, serving as the reference for both users and the integration tests in [`test/shell.d/runtime-smoke-test.sh`](https://github.com/omacom/omarchy/blob/main/test/shell.d/runtime-smoke-test.sh).