# How to Refresh the Omarchy Menu Configuration: A Complete Guide > Refresh Omarchy menu configuration easily. Use the omarchy-refresh-config command to update defaults, creating automatic backups. A complete guide for the basecamp/omarchy repository. - Repository: [37signals/omarchy](https://github.com/basecamp/omarchy) - Tags: how-to-guide - Published: 2026-08-26 --- **Use the `omarchy-refresh-config` command to copy updated menu defaults from the repository to your user configuration directory while automatically creating timestamped backups of existing files.** Omarchy stores its application menu definition in a JSON-C configuration file that requires explicit synchronization to apply changes to your running session. The `omarchy-refresh-config` utility, located at `bin/omarchy-refresh-config` in the `basecamp/omarchy` repository, handles this safely by validating sources, backing up existing user customizations, and deploying new defaults to `~/.config`. ## Understanding the Omarchy Menu Configuration File ### Location and Format The canonical menu definition resides at `$OMARCHY_PATH/default/omarchy/omarchy-menu.jsonc`. This JSON-C file contains the complete schema for menu entries, including IDs, icons, actions, and command aliases that appear when you summon the Omarchy menu. Unlike standard JSON, JSON-C supports comments and trailing commas, making the configuration more maintainable for complex menu hierarchies. The file follows the schema documented in [`docs/menu.md`](https://github.com/basecamp/omarchy/blob/main/docs/menu.md). ### Why Changes Require Refreshing When you modify files under `$OMARCHY_PATH/config` (including the default menu definition), these changes remain isolated from your active user configuration. Omarchy separates shipped defaults from user customizations to prevent updates from clobbering personal settings. To propagate modifications from the repository defaults to your live configuration at `~/.config`, you must explicitly refresh the configuration. ## How to Refresh Omarchy Menu Configuration ### Step 1: Edit the Default Configuration First, modify the menu definition file directly in the Omarchy repository path: ```bash vim "$OMARCHY_PATH/default/omarchy/omarchy-menu.jsonc" ``` Add new menu entries, update icons, or modify existing aliases according to the JSON-C schema. ### Step 2: Run the Refresh Command Execute the refresh utility, specifying the relative path from the default configuration: ```bash omarchy-refresh-config default/omarchy/omarchy-menu.jsonc ``` The command accepts any file path relative to `$OMARCHY_PATH/config`. For example, to update Hyprland bindings instead: ```bash omarchy-refresh-config hypr/bindings.lua ``` ### Step 3: Verify the Changes After refreshing, summon the menu to confirm your updates appear: ```bash omarchy menu summon system ``` New menu entries, modified icons, or updated aliases should render immediately based on the synchronized configuration. ## How the omarchy-refresh-config Command Works ### Validation and Error Handling Before copying, the command verifies that the requested file exists under `$OMARCHY_PATH/config`. If you specify a non-existent path, the utility aborts with an error message: ``` refresh-config: missing shipped config: hypr/missing.lua ``` This validation prevents accidentally creating empty or broken configuration files in your user directory. ### Backup Mechanism If a file with the same relative path already exists in `~/.config`, the command creates a timestamped backup using the pattern `*.bak.`. This mechanism protects your local customizations by preserving the previous state before overwriting with new defaults. ### Deployment Process The refresh operation follows this sequence: 1. Validate the source file exists in the shipped defaults 2. Create a timestamped backup of the existing user config (if present) 3. Copy the default file to the corresponding location inside `~/.config` Because the menu definition is just a JSON-C file on disk, this copy operation is sufficient to update the menu behavior without requiring service restarts. ## Common Use Cases ### Adding Menu Entries When extending the menu with new application shortcuts or system commands, edit `default/omarchy/omarchy-menu.jsonc` to add your entries, then refresh to deploy: ```bash omarchy-refresh-config default/omarchy/omarchy-menu.jsonc ``` ### Modifying Existing Aliases Changes to command aliases or keyboard-driven menu actions follow the same workflow. The refresh command ensures these modifications propagate from the repository defaults to your active user environment. ## Troubleshooting ### Handling Missing Configuration Errors If you encounter the error "refresh-config: missing shipped config," verify that: - The file path is relative to `$OMARCHY_PATH/config` (not an absolute path) - The file exists in the repository's default configuration - You have not accidentally deleted the source file from `$OMARCHY_PATH/default/` The automated tests in [`test/shell.d/refresh-config-test.sh`](https://github.com/basecamp/omarchy/blob/main/test/shell.d/refresh-config-test.sh) validate correct copy and backup behavior, ensuring the utility handles edge cases like missing directories or permission errors. ## Summary - **Menu Location**: The canonical definition lives at `$OMARCHY_PATH/default/omarchy/omarchy-menu.jsonc` - **Refresh Tool**: Use `omarchy-refresh-config ` to synchronize changes - **Safety Features**: Automatic timestamped backups prevent data loss - **Scope**: Works for any configuration file under `$OMARCHY_PATH/config`, not just the menu - **Validation**: The command verifies source files exist before attempting copies - **Immediate Effect**: Changes appear the next time you summon the menu ## Frequently Asked Questions ### Where is the Omarchy menu configuration stored? The default menu configuration resides at `$OMARCHY_PATH/default/omarchy/omarchy-menu.jsonc` within the Omarchy repository. Your active user copy lives in `~/.config/omarchy/omarchy-menu.jsonc` after running the refresh command. ### Does omarchy-refresh-config overwrite my custom settings? The command overwrites the file in `~/.config` but creates a timestamped backup first using the `*.bak.` pattern. This preserves your previous configuration, allowing you to restore customizations if needed. ### Can I refresh configurations other than the menu? Yes. The `omarchy-refresh-config` utility handles any file under `$OMARCHY_PATH/config`. Common examples include [`hypr/bindings.lua`](https://github.com/basecamp/omarchy/blob/main/hypr/bindings.lua) for window manager keybindings or other JSON-C configuration files in the default directory structure. ### How do I restore a previous configuration? Locate the timestamped backup file (with the `.bak.` extension) in your `~/.config` directory, then copy it back to the original filename. For example: `cp ~/.config/omarchy/omarchy-menu.jsonc.bak.20240115120000 ~/.config/omarchy/omarchy-menu.jsonc`.