How to Refresh the Omarchy Menu Configuration: A Complete Guide

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.

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:

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:

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:

omarchy-refresh-config hypr/bindings.lua

Step 3: Verify the Changes

After refreshing, summon the menu to confirm your updates appear:

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.<timestamp>. 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:

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 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 <relative-path> 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.<timestamp> 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 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.<timestamp> 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.

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