# How to Configure the Omarchy Shell: Complete Guide to shell.json

> Learn how to configure the Omarchy shell with our complete guide to shell.json. Customize your shell by following these simple steps and override default settings for personalized control.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: how-to-guide
- Published: 2026-08-31

---

**The Omarchy shell reads its configuration from a JSON file named [`shell.json`](https://github.com/omacom/omarchy/blob/main/shell.json) located at `~/.config/omarchy/shell.json`, which overrides the default configuration at [`config/omarchy/shell.json`](https://github.com/omacom/omarchy/blob/main/config/omarchy/shell.json) in the repository.**

Omarchy is a Wayland compositor with an integrated shell system that renders the status bar, widgets, and plugin interfaces. Understanding how to configure the Omarchy shell is essential for customizing your desktop environment. This guide covers the configuration file structure, CLI commands, and programmatic interfaces based on the Omarchy source code.

## Configuration File Locations

The Omarchy shell uses a two-tier configuration system:

- **[`config/omarchy/shell.json`](https://github.com/omacom/omarchy/blob/main/config/omarchy/shell.json)** — Shipped with the repository as the baseline configuration
- **`~/.config/omarchy/shell.json`** — User-editable file that completely overrides the default when present and valid

In `shell/shell.qml`, the shell defines these paths as:

```qml
property var defaultsPath: omarchyPath + "/config/omarchy/shell.json"
property var userConfigPath: home + "/.config/omarchy/shell.json"

```

The loading algorithm at lines 73–102 follows this priority:

1. If `userConfigPath` exists and parses to a valid object, use it
2. Otherwise, load `defaultsPath`
3. If parsing fails, log a warning and fall back to builtin defaults

## Structure of shell.json

The [`shell.json`](https://github.com/omacom/omarchy/blob/main/shell.json) file follows a strict schema validated on load. Here is the complete structure:

```json
{
  "version": 1,
  "bar": {
    "id": "local.demo-bar",
    "transparent": false,
    "layout": {
      "left": [
        {"type": "command", "command": "date", "settings": {}}
      ],
      "center": [],
      "right": []
    }
  },
  "plugins": []
}

```

### Required Fields

| Field | Type | Description |
|-------|------|-------------|
| `version` | integer | Schema version; must be `1` |
| `bar` | object | Bar configuration container |
| `bar.layout` | object | Contains `left`, `center`, `right` arrays |

### Bar Layout Widgets

Each widget entry in the layout arrays supports:

- **`type`** — Either `"command"` (executes shell command) or `"qml"` (loads QML component)
- **`command`** — For command type: the shell command to execute
- **`id`** — Optional identifier for the widget instance
- **`settings`** — Per-widget configuration object

The `transparent` boolean controls whether the bar background renders transparent.

### Plugin System

The top-level `plugins` array contains plugin IDs that should be enabled. The `shell/services/PluginRegistry.qml` processes this list to activate corresponding features.

## CLI Configuration Commands

Omarchy provides built-in CLI helpers for managing [`shell.json`](https://github.com/omacom/omarchy/blob/main/shell.json) without manual editing:

### omarchy bar set

Creates or updates a widget entry in the specified bar section:

```bash
omarchy bar set \
  --section=center \
  --id=my.custom.clock \
  --type=command \
  --command='date "+%H:%M:%S"' \
  --settings='{"interval": 1000}'

```

### omarchy bar position

Updates bar positioning fields without touching other configuration:

```bash
omarchy bar position --anchor=top --margin=4

```

### omarchy-refresh-config

Copies the default configuration to the user location with automatic backup:

```bash
omarchy-refresh-config omarchy/shell.json

```

This command is idempotent: it preserves existing user files by renaming them with timestamps before overwriting.

### omarchy bar reload

Triggers the running shell to re-read [`shell.json`](https://github.com/omacom/omarchy/blob/main/shell.json) without restarting the compositor:

```bash
omarchy bar reload

```

## Programmatic Configuration Access

The shell exposes the effective configuration through `shell.getEffectiveConfig()` (line 991 in `shell/shell.qml`). This method returns the merged configuration after processing user overrides and applying defaults.

For development sessions, the shell watches [`shell.json`](https://github.com/omacom/omarchy/blob/main/shell.json) for filesystem changes. In production builds, explicit `omarchy bar reload` is required.

## Practical Configuration Examples

### Add a Custom Status Widget

```bash

# Add CPU usage display to the right side of the bar

omarchy bar set \
  --section=right \
  --id=custom.cpu \
  --type=command \
  --command="grep -o '^[0-9]*' /proc/stat | head -1 | awk '{print \"CPU: \" $1}'" \
  --settings='{"interval": 2000}'

omarchy bar reload

```

### Enable Multiple Plugins

```bash

# Modify plugins array directly with jq

jq '.plugins = ["weather", "system-monitor", "notifications"]' \
  ~/.config/omarchy/shell.json > /tmp/shell.json.tmp \
  && mv /tmp/shell.json.tmp ~/.config/omarchy/shell.json

omarchy bar reload

```

### Reset to Factory Defaults

```bash

# Backup current config and restore defaults

omarchy-refresh-config omarchy/shell.json
omarchy bar reload

```

### Create Transparent Bar

```bash

# Edit directly for settings not exposed via CLI

jq '.bar.transparent = true' ~/.config/omarchy/shell.json > /tmp/shell.json.tmp \
  && mv /tmp/shell.json.tmp ~/.config/omarchy/shell.json

omarchy bar reload

```

## Schema Validation

The Omarchy test suite validates [`shell.json`](https://github.com/omacom/omarchy/blob/main/shell.json) structure in [`test/shell.d/config-test.sh`](https://github.com/omacom/omarchy/blob/main/test/shell.d/config-test.sh) (lines 16–17). Invalid configurations trigger fallback to defaults with console warnings. Required validation rules include:

- `version` field must exist and equal `1`
- `bar` must be an object with `layout` containing three array properties
- `plugins` must be an array of strings

## Key Source Files

| File | Purpose |
|------|---------|
| `shell/shell.qml` | Core loader and configuration watching logic |
| [`config/omarchy/shell.json`](https://github.com/omacom/omarchy/blob/main/config/omarchy/shell.json) | Repository default configuration |
| `shell/services/PluginRegistry.qml` | Plugin enablement based on `plugins` array |
| [`shell/README.md`](https://github.com/omacom/omarchy/blob/main/shell/README.md) | Human-readable schema documentation |
| [`test/shell.d/config-test.sh`](https://github.com/omacom/omarchy/blob/main/test/shell.d/config-test.sh) | Automated schema validation tests |

## Summary

- **User configuration lives at** `~/.config/omarchy/shell.json` and completely overrides repository defaults
- **Required fields** are `version`, `bar.layout.left/center/right`, and optionally `plugins`
- **CLI commands** (`omarchy bar set`, `omarchy bar reload`) provide safe editing without syntax errors
- **Changes require explicit reload** via `omarchy bar reload` in production builds
- **Invalid configurations fall back** to defaults with logged warnings per `shell/shell.qml` lines 73–84

## Frequently Asked Questions

### What happens if my shell.json has a syntax error?

The Omarchy shell validates the user file on load. If parsing fails or the `version` field is missing, the shell falls back to the repository default at [`config/omarchy/shell.json`](https://github.com/omacom/omarchy/blob/main/config/omarchy/shell.json) and prints a warning to the console. This behavior is implemented in `shell/shell.qml` lines 73–84.

### Can I use the shell without a user configuration file?

Yes. If `~/.config/omarchy/shell.json` does not exist, Omarchy automatically uses the default configuration shipped with the repository. This is the standard experience for new installations.

### How do I reload configuration without losing my open windows?

Use `omarchy bar reload` from a terminal or keybinding. This command signals the running shell process to re-parse [`shell.json`](https://github.com/omacom/omarchy/blob/main/shell.json) and update the bar layout without restarting the Wayland compositor or affecting running applications.

### Where is the complete schema documentation?

The authoritative schema reference is [`shell/README.md`](https://github.com/omacom/omarchy/blob/main/shell/README.md) in the repository. Additionally, the test file [`test/shell.d/config-test.sh`](https://github.com/omacom/omarchy/blob/main/test/shell.d/config-test.sh) contains the machine-validated assertions that define valid configuration structures.