# Where Is the Omarchy Shell Configuration Stored? A Complete Guide to Config Paths

> Find where Omarchy shell configuration is stored. Learn about user-specific and default config paths for easy management and customization.

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

---

**Omarchy stores its shell configuration in `~/.config/omarchy/shell.json` for user-specific settings, falling back to `$OMARCHY_PATH/config/omarchy/shell.json` for default values.**

Understanding where **Omarchy shell configuration** is stored is essential for customizing your desktop environment. In the `basecamp/omarchy` repository, the shell uses a JSON-based configuration system that separates user preferences from shipped defaults. This guide explains the exact file paths and loading mechanism implemented in the source code.

## Default vs. User Configuration Paths

Omarchy implements a two-tier configuration system. The **default configuration** resides in the repository at `$OMARCHY_PATH/config/omarchy/shell.json`. When you customize settings, the shell writes to the **user configuration** path at `~/.config/omarchy/shell.json`.

In `shell/shell.qml`, the code explicitly declares these locations through the `defaultsPath` and `userConfigPath` variables. The shell first loads the defaults, then checks for the user file. If `~/.config/omarchy/shell.json` exists and parses correctly, it overrides the default values.

## Key Configuration Files

The following files define how Omarchy manages shell settings:

- **`shell/shell.qml`**: Contains the configuration loading logic with `defaultsPath` pointing to `$OMARCHY_PATH/config/omarchy/shell.json` and `userConfigPath` pointing to `$HOME/.config/omarchy/shell.json`.

- **[`config/omarchy/shell.json`](https://github.com/basecamp/omarchy/blob/main/config/omarchy/shell.json)**: The shipped default configuration that ships with the repository.

- **[`shell/plugins/bar/README.md`](https://github.com/basecamp/omarchy/blob/main/shell/plugins/bar/README.md)**: Documents how the bar plugin reads its specific settings from `~/.config/omarchy/shell.json`.

- **[`shell/README.md`](https://github.com/basecamp/omarchy/blob/main/shell/README.md)**: Provides general documentation on the shell's configuration handling.

## How Configuration Loading Works

According to the `basecamp/omarchy` source code, the shell follows a specific precedence order:

1. Load the defaults from `$OMARCHY_PATH/config/omarchy/shell.json`
2. Check for `$HOME/.config/omarchy/shell.json`
3. If the user file exists and is valid JSON, merge it with defaults (user values take precedence)
4. If the user file is missing or corrupt, continue using defaults

This approach ensures that users only need to specify values they want to change, while inheriting sensible defaults for everything else.

## Reading and Modifying Configuration

You can interact with the **Omarchy shell configuration** using standard command-line tools or the Omarchy CLI.

View the current configuration:

```bash
jq . "$HOME/.config/omarchy/shell.json"

```

Reset to shipped defaults:

```bash
cp "$OMARCHY_PATH/config/omarchy/shell.json" "$HOME/.config/omarchy/shell.json"

```

Modify settings using the Omarchy CLI (writes to shell.json):

```bash
omarchy bar position top

```

## Summary

- Omarchy uses `~/.config/omarchy/shell.json` as the primary **user configuration** location.
- Default values are stored in `$OMARCHY_PATH/config/omarchy/shell.json` within the repository.
- The loading logic in `shell/shell.qml` implements a fallback system: defaults first, then user overrides.
- You can manually edit the JSON file or use the `omarchy` CLI to modify settings.

## Frequently Asked Questions

### Where is the main Omarchy shell configuration file located?

The primary configuration file is located at `~/.config/omarchy/shell.json`. This file stores your personalized settings and overrides the default configuration shipped with the repository at `$OMARCHY_PATH/config/omarchy/shell.json`.

### How do I reset Omarchy shell settings to defaults?

Copy the default configuration from the repository to your user config directory using `cp "$OMARCHY_PATH/config/omarchy/shell.json" "$HOME/.config/omarchy/shell.json"`. This overwrites your custom settings with the original defaults defined in the source tree.

### What happens if the user configuration file is missing or invalid?

If `~/.config/omarchy/shell.json` does not exist or contains invalid JSON, Omarchy will continue using the default configuration from `$OMARCHY_PATH/config/omarchy/shell.json` without throwing errors. The shell gracefully handles missing user files by falling back to `defaultsPath` as defined in `shell/shell.qml`.

### Can I edit the shell configuration manually?

Yes, you can directly edit `~/.config/omarchy/shell.json` using any text editor or JSON processor like `jq`. However, using the `omarchy` CLI (e.g., `omarchy bar position top`) is recommended as it validates input and ensures proper JSON formatting before writing to the configuration file.