# How to Reload the Omarchy Shell Configuration: 3 Methods Explained

> Reload Omarchy shell configuration instantly with three methods. Apply changes to shell.json without restarting your Wayland compositor. Learn how now.

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

---

**Run `omarchy-shell shell reloadConfig` (or the `omarchy-shell-config` wrapper) to apply changes from `~/.config/omarchy/shell.json` without restarting the Wayland compositor.**

The Omarchy desktop environment stores its bar layout, plugins, and UI behavior in `~/.config/omarchy/shell.json`. After editing this file, you must **reload the Omarchy shell configuration** to refresh the interface without logging out or restarting the session.

## How the Omarchy Shell Configuration Reload Works

When invoked, the **`reloadConfig`** command defined in `shell/shell.qml` re-reads the JSON configuration, rebuilds the status bar, and reinitializes plugins. This hot-reload capability updates the shell surface atomically while keeping the compositor and all applications running.

The implementation resides in the `Shell` QML object at [`shell/shell.qml`](https://github.com/basecamp/omarchy/blob/quattro/shell/shell.qml). The function parses `~/.config/omarchy/shell.json` and triggers UI reconstruction. A convenience wrapper at [`bin/omarchy-shell-config`](https://github.com/basecamp/omarchy/blob/quattro/bin/omarchy-shell-config) exposes this to the terminal.

## Methods to Reload the Omarchy Shell Configuration

### Method 1: Use the omarchy-shell-config Wrapper

The simplest approach uses the dedicated helper script that ships with Omarchy.

```bash
omarchy-shell-config

```

This command executes `omarchy-shell shell reloadConfig` and reports any errors to stderr. According to the source at [`bin/omarchy-shell-config`](https://github.com/basecamp/omarchy/blob/quattro/bin/omarchy-shell-config), the script returns the shell's response—typically `ok` on success.

### Method 2: Direct Shell Command

For automation or debugging, call the shell's API directly via D-Bus:

```bash
omarchy-shell shell reloadConfig

```

This sends a request to the running `omarchy-shell` process, invoking the `reloadConfig` function defined in [`shell/shell.qml`](https://github.com/basecamp/omarchy/blob/quattro/shell/shell.qml). The command returns immediately and applies changes without restarting the compositor.

### Method 3: Programmatic Reload via QML

Custom plugins or internal components can trigger reloads programmatically:

```qml
// Inside a QML component with access to the Shell object
Shell.reloadConfig()

```

This approach bypasses the CLI entirely and is useful when building configuration editors or automated tuning scripts that modify [`shell.json`](https://github.com/basecamp/omarchy/blob/main/shell.json) and need immediate effect.

## Verifying Configuration Reload Success

The `reloadConfig` command returns the string `ok` to stdout when successful. To verify programmatically:

```bash
if omarchy-shell shell reloadConfig | grep -q "ok"; then
    echo "Omarchy shell configuration reloaded"
else
    echo "Reload failed"
fi

```

If `~/.config/omarchy/shell.json` contains syntax errors, the shell logs the failure to stderr and retains the previous valid configuration.

## Key Source Files Reference

| File | Purpose | Source Link |
|------|---------|-------------|
| `shell/shell.qml` | Defines `Shell.reloadConfig()` that parses `~/.config/omarchy/shell.json` and rebuilds the UI | [`shell/shell.qml`](https://github.com/basecamp/omarchy/blob/quattro/shell/shell.qml) |
| `bin/omarchy-shell-config` | Convenience wrapper executing `omarchy-shell shell reloadConfig` | [`bin/omarchy-shell-config`](https://github.com/basecamp/omarchy/blob/quattro/bin/omarchy-shell-config) |
| [`docs/omarchy-shell.md`](https://github.com/basecamp/omarchy/blob/main/docs/omarchy-shell.md) | Reference documentation for the `reloadConfig` command | [[`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) |
| [`shell/README.md`](https://github.com/basecamp/omarchy/blob/main/shell/README.md) | Public API documentation including configuration reload behavior | [[`shell/README.md`](https://github.com/basecamp/omarchy/blob/main/shell/README.md)](https://github.com/basecamp/omarchy/blob/quattro/shell/README.md) |
| [`agents/skills/shell-dev.md`](https://github.com/basecamp/omarchy/blob/main/agents/skills/shell-dev.md) | Developer guide mentioning `reloadConfig` for shell extension development | [[`agents/skills/shell-dev.md`](https://github.com/basecamp/omarchy/blob/main/agents/skills/shell-dev.md)](https://github.com/basecamp/omarchy/blob/quattro/agents/skills/shell-dev.md) |

## Summary

- **Omarchy shell configuration** lives at `~/.config/omarchy/shell.json` and controls the desktop bar and plugins.
- **Reload the configuration** using `omarchy-shell shell reloadConfig` or the `omarchy-shell-config` wrapper to avoid session restarts.
- **Implementation** resides in [`shell/shell.qml`](https://github.com/basecamp/omarchy/blob/quattro/shell/shell.qml) as the `reloadConfig()` function.
- **Return value** is `ok` on success; errors are logged to stderr without crashing the compositor.
- **Programmatic access** is available via `Shell.reloadConfig()` in QML for custom tooling.

## Frequently Asked Questions

### What configuration file does the Omarchy shell reload command read?

The `reloadConfig` command specifically reads `~/.config/omarchy/shell.json`. This JSON file defines the bar layout, plugin positions, and UI behavior. The shell watches this path exclusively; modifying other files requires a full session restart.

### Do I need to restart the Wayland compositor after reloading the shell configuration?

No. The **Omarchy shell configuration reload** is a hot-reload operation. The compositor remains active, and only the shell surface, bar, and plugins are reconstructed. This preserves all open applications and window states.

### How can I check if the shell configuration reload succeeded?

Check the command output for the string `ok`. The [`bin/omarchy-shell-config`](https://github.com/basecamp/omarchy/blob/quattro/bin/omarchy-shell-config) script and `omarchy-shell shell reloadConfig` both return this on success. If the JSON is malformed, the command returns an error message and the shell retains the previous valid configuration.

### Can I trigger a configuration reload from a custom plugin or automation script?

Yes. Custom QML plugins can call `Shell.reloadConfig()` directly assuming they have access to the Shell object. For shell scripts, use `omarchy-shell shell reloadConfig` after modifying `~/.config/omarchy/shell.json` programmatically.