# How to Communicate with the Omarchy Shell via CLI: A Complete IPC Guide

> Learn to communicate with the Omarchy shell via CLI using Unix sockets and JSON commands. This guide provides a complete IPC solution for scriptable desktop environment control.

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: how-to-guide
- Published: 2026-08-26

---

**The `omarchy-shell` binary establishes an IPC connection via Unix socket to the running Quickshell process, serializing CLI arguments as JSON commands and returning structured responses, enabling full scriptability of the desktop environment.**

The Omarchy desktop environment from basecamp/omarchy runs as a persistent Quickshell process that exposes all interactive UI actions through a dedicated command-line interface. By leveraging the `omarchy-shell` CLI wrapper, you can programmatically control panels, services, and plugins without manual interaction. This guide covers the complete IPC architecture, syntax patterns, and practical examples for communicating with the Omarchy shell via CLI.

## Architecture Overview

The Omarchy shell communication stack consists of four core components working over Unix sockets. When you invoke `omarchy-shell`, the binary locates the socket under `$OMARCHY_PATH` and establishes a persistent IPC channel to the running shell process.

- **`omarchy-shell` (CLI binary)**: Located at `bin/omarchy-shell`, this executable parses subcommands, serializes arguments into JSON, and manages the request-response lifecycle.
- **`shell/shell.qml` (Host Process)**: The main QML process opens the Unix socket, listens for incoming messages, and dispatches commands to registered plugins or core services.
- **Plugin Services**: Located under `shell/plugins/**`, each plugin implements a `Service.qml` or JavaScript interface exposing methods callable via CLI namespacing.
- **`OMARCHY_PATH`**: Environment variable defining the root directory containing the socket, configuration, and runtime data required by both CLI and shell.

## CLI Syntax and Command Structure

The `omarchy-shell` utility follows a predictable argument pattern that maps directly to the internal plugin architecture.

```bash
omarchy-shell [options] <namespace> <action> [args...]

```

Namespaces correspond to plugin identifiers (e.g., `omarchy.indicators`, `omarchy.notifications`) or the special `shell` namespace for core operations. Actions represent exposed methods such as `refresh`, `toggle`, `summon`, or `hide`.

Key options include:

- **`-q` or `--quiet`**: Suppresses JSON output, returning only exit codes (0 for success, non-zero for failure), ideal for automation scripts and systemd services.

The `shell` namespace provides generic operations including `ping`, `listPlugins`, `summon`, `hide`, and `setPluginEnabled`, allowing you to query state and manage plugin visibility programmatically.

## Practical CLI Examples

### Health Checks and Plugin Discovery

Verify the shell is responsive and enumerate loaded plugins:

```bash

# Check if the shell process is alive

omarchy-shell shell ping

# Output: {"ok":true,"msg":"pong"}

# List all loaded plugins with their identifiers

omarchy-shell shell listPlugins

# Output: {"plugins":["omarchy.clock","omarchy.menu","omarchy.weather",...]}

```

### Controlling UI Components

Refresh indicators, summon specific plugins with payloads, or hide elements:

```bash

# Refresh the indicator bar silently (no output)

omarchy-shell -q omarchy.indicators refresh

# Summon the clock plugin with a timezone parameter

omarchy-shell shell summon omarchy.clock '{"tz":"UTC"}'

# Remove the weather widget from the UI

omarchy-shell shell hide omarchy.weather

```

### System Services and Notifications

Interact with idle management and notification systems:

```bash

# Lock the screen if idle

omarchy-shell idle lock

# Send a structured notification

omarchy-shell notifications send '{"title":"Build finished","body":"All tests passed"}'

# Dismiss all notifications immediately

omarchy-shell notifications dismissAll

```

### Plugin Management

Enable or disable plugins dynamically from scripts:

```bash

# Disable the menu plugin

omarchy-shell shell setPluginEnabled omarchy.menu false

```

## Key Source Files and Implementation Details

Understanding the underlying source code provides insight into the IPC mechanism and extension points.

**CLI Entry Point**: `bin/omarchy-shell` implements the argument parsing and socket connection logic. This binary handles the JSON serialization and manages the `$OMARCHY_PATH` environment variable resolution.

**IPC Host**: `shell/shell.qml` creates the Unix socket listener and routes incoming commands to the appropriate service handlers. This file manages the lifecycle of plugin communication channels.

**Service Implementation Example**: `shell/plugins/services/idle/Service.qml` demonstrates how plugins expose CLI-callable methods. This pattern shows the standardized interface for receiving commands from `omarchy-shell idle` invocations.

**Integration Testing**: [`test/shell.d/shell-ipc-display-test.sh`](https://github.com/basecamp/omarchy/blob/main/test/shell.d/shell-ipc-display-test.sh) provides working examples of CLI invocation patterns, including quiet-mode usage for automated testing harnesses.

**Routing Documentation**: [`docs/cli-router.md`](https://github.com/basecamp/omarchy/blob/main/docs/cli-router.md) details the mapping between top-level commands and binary execution paths, including the `omarchy-shell` entry point specification.

## Summary

- **`omarchy-shell`** serves as the unified CLI entry point for all Omarchy IPC communication.
- Commands use the pattern `omarchy-shell [options] <namespace> <action> [args]` with JSON responses.
- The **`-q`** flag enables silent operation for shell scripting and automation.
- Communication occurs over Unix sockets located under the **`$OMARCHY_PATH`** directory.
- The **`shell`** namespace provides meta-operations like `ping`, `listPlugins`, and `setPluginEnabled`.
- All commands return standard exit codes (0 for success), making them compatible with systemd services and CI/CD pipelines.

## Frequently Asked Questions

### What is the difference between `omarchy-shell` and the Quickshell process?

The Quickshell process (`omarchy-shell` in process listings) is the long-running graphical runtime that renders the desktop environment. The `omarchy-shell` binary is a separate CLI wrapper that communicates with this process via IPC sockets, allowing external scripts to trigger UI changes without direct graphical interaction.

### How do I troubleshoot "Connection refused" errors when running omarchy-shell commands?

Ensure the `OMARCHY_PATH` environment variable is set correctly and points to the directory containing the active Unix socket. Verify the Quickshell process is actually running by checking for the `omarchy-shell` process in your system monitor. The socket file is created dynamically when the shell starts.

### Can I create custom CLI commands for my own Omarchy plugins?

Yes. By implementing a `Service.qml` file in your plugin directory following the pattern shown in `shell/plugins/services/idle/Service.qml`, your plugin automatically becomes accessible via `omarchy-shell <your.namespace> <action>`. The shell host dispatches JSON payloads to your service's exposed methods.

### Is the omarchy-shell CLI suitable for use in cron jobs or systemd timers?

Absolutely. The `-q` or `--quiet` flag suppresses all JSON output, ensuring only exit codes are returned. This makes `omarchy-shell` ideal for automation, as non-zero exit codes properly indicate failures to systemd or cron while keeping logs clean of JSON chatter.