# What Is the Purpose of shell.toml in Omarchy's Configuration?

> Discover the purpose of shell.toml in Omarchy's configuration. This file defines the visual language, including colors, states, spacing, and typography for QML components.

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

---

**[`shell.toml`](https://github.com/basecamp/omarchy/blob/main/shell.toml) is the central configuration file that defines the visual language of the Omarchy shell, declaratively specifying surface-role colors, control states, spacing tokens, and typography that QML components consume through the `Color` and `Style` singletons.**

The [`shell.toml`](https://github.com/basecamp/omarchy/blob/main/shell.toml) file sits at the heart of Omarchy's theming architecture, bridging static configuration with dynamic runtime behavior. According to the basecamp/omarchy source code, this TOML file provides a hot-reloadable source of truth for all UI styling without requiring shell restarts.

## Core Responsibilities and Structure

### Visual Surface Roles and Control States

At its foundation, [`shell.toml`](https://github.com/basecamp/omarchy/blob/main/shell.toml) organizes colors into semantic surface roles that QML components reference through the `Color` singleton defined in `shell/Commons/Color.qml`. The configuration groups related colors into tables such as **[bar]**, **[menu]**, and **[tooltip]**, each defining background and foreground values for specific UI regions.

Beyond static colors, the file declares **control-state definitions** including hover, active, and disabled variants. These states allow widgets to react to user interaction while maintaining visual consistency across the shell.

### Layout Metrics and Typography Definitions

The configuration also drives structural calculations through **spacing and sizing tokens**. Values for margins, paddings, and bar height live directly in [`shell.toml`](https://github.com/basecamp/omarchy/blob/main/shell.toml), enabling theme authors to adjust density without modifying QML source.

Typography receives similar treatment through the **[font]** table, which specifies `base-size`, `family`, and `weight`. The `Style` singleton in `shell/Commons/Style.qml` propagates these values to every widget, ensuring consistent text rendering across panels, menus, and tooltips.

## Theme Generation and Override Architecture

### Template-Based File Generation

When applying a theme, Omarchy generates [`shell.toml`](https://github.com/basecamp/omarchy/blob/main/shell.toml) from the template located at `default/themed/shell.toml.tpl`. This template serves as the fallback source, providing default values for all visual tokens when a theme does not explicitly override them.

### Theme-Level and User-Level Overrides

Themes can customize the shell appearance through two distinct mechanisms:

1. **Theme-provided override**: Shipping a file at `themes/<name>/shell.toml` within the theme directory replaces the generated defaults entirely.
2. **User-level override**: Creating `~/.config/omarchy/shell.toml` on the local machine applies machine-specific customizations that persist across theme changes.

If a theme omits the [`shell.toml`](https://github.com/basecamp/omarchy/blob/main/shell.toml) file, Omarchy automatically falls back to the template defaults, ensuring the shell remains functional regardless of theme completeness.

## Runtime Loading and Configuration Merging

### Configuration Precedence Model

At runtime, the shell loads two distinct TOML dictionaries that the `Color` singleton merges according to a strict precedence hierarchy:

- **Theme-provided**: Located at `$OMARCHY_PATH/themes/<theme>/shell.toml`, this file contains the theme author's intended styling.
- **User-provided**: Found at `~/.config/omarchy/shell.toml`, this file contains local machine overrides.

The merging algorithm gives explicit precedence to the user file, allowing local customizations to override theme defaults without modifying the theme package itself.

### Live Reloading Implementation

The architecture supports **live reloading** of colors, spacing, and font settings without restarting the shell. When users execute the `omarchy-theme-set <theme-name>` command, the CLI base-64-encodes the theme's [`shell.toml`](https://github.com/basecamp/omarchy/blob/main/shell.toml) and transmits it to the running shell via the `applyTheme <colorsB64> <shellB64>` function. The shell receives this payload, re-merges the configuration dictionaries, and immediately updates all bound QML properties.

## Practical Configuration Examples

### Customizing User Settings

Edit `~/.config/omarchy/shell.toml` to modify bar backgrounds and base font sizes:

```toml
[bar]
background = "#1e1e2e"

[font]
base-size = 13

```

### Applying Themes Programmatically

Use the bundled CLI tool to switch themes and push configuration to the running shell:

```bash
omarchy-theme-set <theme-name>

```

This command internally base-64-encodes the theme's [`shell.toml`](https://github.com/basecamp/omarchy/blob/main/shell.toml) and invokes the shell's theme application interface.

### Accessing Values in QML Components

QML files import the Commons namespace to access merged configuration values:

```qml
import "Commons" as Commons

Text {
    text: "Info"
    color: Commons.Color.tooltip.foreground
    font.pixelSize: Commons.Style.font.baseSize
}

```

The `Commons.Color` object exposes surface-role colors, while `Commons.Style` provides typography and spacing metrics sourced directly from the merged [`shell.toml`](https://github.com/basecamp/omarchy/blob/main/shell.toml) dictionaries.

## Summary

- **[`shell.toml`](https://github.com/basecamp/omarchy/blob/main/shell.toml)** is the declarative configuration file controlling Omarchy's entire visual language, located thematically at `default/themed/shell.toml.tpl` and overridden at runtime.
- The file defines **surface-role colors**, **control states**, **spacing tokens**, and **typography** that QML components consume through singletons.
- **Theme authors** override defaults by placing [`shell.toml`](https://github.com/basecamp/omarchy/blob/main/shell.toml) in their theme directory, while **users** customize via `~/.config/omarchy/shell.toml` with automatic precedence.
- The `Color` singleton in `shell/Commons/Color.qml` merges theme and user configurations, enabling **hot reloading** without shell restarts.
- The `omarchy-theme-set` CLI command encodes and transmits configuration changes via the `applyTheme` function interface.

## Frequently Asked Questions

### What file format does Omarchy use for shell configuration files?

Omarchy uses **TOML** (Tom's Obvious, Minimal Language) for its shell configuration. The [`shell.toml`](https://github.com/basecamp/omarchy/blob/main/shell.toml) file uses section headers like `[bar]` and `[font]` to organize related configuration keys, making it human-readable and easy to edit for both theme authors and end users.

### Where should I place my custom shell.toml overrides?

Place user-specific overrides in **`~/.config/omarchy/shell.toml`**. This location takes precedence over theme-provided configurations located at `$OMARCHY_PATH/themes/<theme>/shell.toml`. The shell automatically detects and merges this file at startup and during theme switches.

### How does Omarchy apply theme changes without restarting?

Omarchy implements a **live reloading mechanism** through base-64-encoded configuration transmission. When you run `omarchy-theme-set`, the CLI encodes the theme's [`shell.toml`](https://github.com/basecamp/omarchy/blob/main/shell.toml) and calls `applyTheme <colorsB64> <shellB64>`, which the running shell receives and applies immediately to all QML singletons.

### Can I modify just the font size without creating a full theme?

Yes. Create or edit **`~/.config/omarchy/shell.toml`** and add a `[font]` section with your desired `base-size` value. The `bin/omarchy-display-text-size` utility demonstrates how the shell reads this specific key to adjust text rendering across all widgets without requiring a custom theme package.