# How to Enable a Plugin Using Omarchy’s IPC setPluginEnabled Method

> Easily enable plugins in Omarchy with the setPluginEnabled method. Learn how to toggle plugins on using the command line for seamless integration. Get started now.

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

---

**Call `omarchy-shell shell setPluginEnabled <plugin-id> "true"` to toggle a plugin on, or use the `omarchy-plugin-enable` wrapper; only the literal string `"true"` enables the plugin, while any other value disables it.**

Omarchy’s desktop environment runs on a persistent Quickshell instance (`omarchy-shell`) that exposes an IPC interface for runtime configuration. To enable a plugin using Omarchy’s IPC `setPluginEnabled` method, you invoke a command against the running shell process, which delegates state management to the internal PluginRegistry and persists changes to [`shell.json`](https://github.com/basecamp/omarchy/blob/main/shell.json).

## Understanding the IPC setPluginEnabled Method Signature

The IPC method follows this signature:

```text
setPluginEnabled <id> <"true"|…>

```

- `id` – The plugin’s identifier (e.g., `omarchy.clock` or `community.weather-extra`).
- `enabled` – A **string** value; only the literal `"true"` activates the plugin. Any other string—including `"false"`—disables it.

The method returns `"ok"` on success or `"unknown"` if the plugin ID is not recognized.

## Enabling Plugins via the setPluginEnabled IPC Command

You can enable plugins directly through the IPC interface or use a convenience wrapper.

### Direct IPC Invocation with omarchy-shell

Use the `omarchy-shell` command to call the method directly:

```bash
omarchy-shell shell setPluginEnabled omarchy.clock true

```

Expected output:

```text
ok

```

To disable the plugin, pass any value other than `"true"`:

```bash
omarchy-shell shell setPluginEnabled omarchy.clock false

```

### Using the omarchy-plugin-enable Helper

For convenience, Omarchy provides `omarchy-plugin-enable`, which wraps the IPC call:

```bash
omarchy-plugin-enable omarchy.clock

```

Internally, this executes:

```bash
omarchy-shell shell setPluginEnabled "$id" true

```

This helper is defined in [`bin/omarchy-plugin-enable`](https://github.com/basecamp/omarchy/blob/quattro/bin/omarchy-plugin-enable).

## Programmatic setPluginEnabled Usage in Scripts

For automation, use the `shell_ipc` function to capture results:

```bash
result=$(shell_ipc shell setPluginEnabled "community.weather-extra" "true")
if [[ $result == ok ]]; then
    echo "Weather plugin enabled"
else
    echo "Failed to enable plugin: $result"
fi

```

This pattern is useful for installation scripts that need to verify plugin state before proceeding.

## Internal Implementation of setPluginEnabled

According to the basecamp/omarchy source code, the IPC method is defined in [`shell/shell.qml`](https://github.com/basecamp/omarchy/blob/quattro/shell/shell.qml) at lines 907‑909:

```qml
function setPluginEnabled(id: string, enabled: string): string {
    return shell.pluginRegistry.setEnabled(id, enabled === "true") ? "ok" : "unknown"
}

```

This function forwards the request to `shell.pluginRegistry.setEnabled()`, which:
1. Updates the persisted state in [`shell.json`](https://github.com/basecamp/omarchy/blob/main/shell.json)
2. Emits the appropriate signals to trigger UI updates

The concrete logic for `setEnabled` resides in [`shell/services/PluginRegistry.qml`](https://github.com/basecamp/omarchy/blob/quattro/shell/services/PluginRegistry.qml), where the function mutates the plugin state and handles placement options.

## Summary

- The `setPluginEnabled` IPC method requires a plugin ID and a string value; only `"true"` enables the plugin.
- Use `omarchy-shell shell setPluginEnabled <id> true` for direct activation or `omarchy-plugin-enable <id>` for convenience.
- The method returns `"ok"` on success and `"unknown"` if the plugin ID does not exist.
- State changes persist immediately to [`shell.json`](https://github.com/basecamp/omarchy/blob/main/shell.json) via the PluginRegistry service.

## Frequently Asked Questions

### What happens if I pass "false" to setPluginEnabled?

Passing `"false"`—or any string other than `"true"`—disables the plugin. The implementation in `shell/shell.qml` explicitly checks `enabled === "true"`, so only that exact literal activates the plugin; all other values evaluate to disabled.

### Can I use setPluginEnabled to toggle system plugins?

Yes, you can use the method on any plugin registered with the PluginRegistry, including core system plugins like `omarchy.clock` or community plugins like `community.weather-extra`, provided you know the exact plugin ID.

### Where is the plugin state saved when I enable it?

The PluginRegistry persists the enabled state to [`shell.json`](https://github.com/basecamp/omarchy/blob/main/shell.json) immediately upon invocation. According to the source code in `shell/services/PluginRegistry.qml`, the `setEnabled` function updates this configuration file and emits signals to notify the running shell of state changes.

### Is there a way to check if a plugin is enabled before calling setPluginEnabled?

While the `setPluginEnabled` method only toggles state and returns `"ok"` or `"unknown"`, you can query the current plugin state by examining [`shell.json`](https://github.com/basecamp/omarchy/blob/main/shell.json) directly or using other IPC methods documented in [[`docs/omarchy-shell.md`](https://github.com/basecamp/omarchy/blob/main/docs/omarchy-shell.md)](https://github.com/basecamp/omarchy/blob/quattro/docs/omarchy-shell.md) to list active plugins before making changes.