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

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 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 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 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.

# 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	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	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.

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 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.

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