How to Reload the Omarchy Shell Configuration: 3 Methods Explained

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. The function parses ~/.config/omarchy/shell.json and triggers UI reconstruction. A convenience wrapper at 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.

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, 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:

omarchy-shell shell reloadConfig

This sends a request to the running omarchy-shell process, invoking the reloadConfig function defined in 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:

// 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 and need immediate effect.

Verifying Configuration Reload Success

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

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
bin/omarchy-shell-config	Convenience wrapper executing omarchy-shell shell reloadConfig	bin/omarchy-shell-config
docs/omarchy-shell.md	Reference documentation for the reloadConfig command	[docs/omarchy-shell.md](https://github.com/basecamp/omarchy/blob/quattro/docs/omarchy-shell.md)
shell/README.md	Public API documentation including configuration reload behavior	[shell/README.md](https://github.com/basecamp/omarchy/blob/quattro/shell/README.md)
agents/skills/shell-dev.md	Developer guide mentioning reloadConfig for shell extension development	[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 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 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.

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