Essential Omarchy CLI Commands and Their Purposes

Omarchy CLI commands provide a unified interface for system updates, theme management, hardware toggles, and diagnostics through a dynamic router that discovers any executable prefixed with omarchy- in the system path.

The Omarchy command-line interface, maintained in the omacom/omarchy repository, handles everyday Linux system management through a modular architecture. All Omarchy CLI commands route through a single front-end script that dynamically discovers functionality by scanning for omarchy-* binaries. This design allows users to update packages, switch themes, capture screenshots, and manage hardware features using a consistent omarchy <command> syntax.

How the Omarchy CLI Router Works

Dynamic Command Discovery

The foundation of all Omarchy CLI commands lies in bin/omarchy, the central router script. This executable automatically registers any binary named with the omarchy-* prefix as a subcommand. The router maintains a GROUP_DESCRIPTIONS table within the script (lines 29-98) that categorizes commands into logical groups such as theme, update, and toggle.

Command Metadata Structure

Each executable can include descriptive metadata within comment headers, allowing the router to display human-readable descriptions without executing the commands. The metadata structure is defined in agents/skills/command-metadata.md, while the routing logic and dispatch system are documented in docs/cli-router.md.

Core System Management Commands

Update Operations

The omarchy update command pulls the latest Omarchy release and upgrades system packages. This serves as the primary maintenance entry point for keeping the environment current.

omarchy update

System Monitoring and Diagnostics

Monitor hardware and troubleshoot issues using these essential commands:

• omarchy system-stats – Displays an overview of CPU, memory, and disk usage
• omarchy debug – Prints assorted debugging information about the current environment
• omarchy weather-status – Retrieves and displays the current weather

Customization and Theming Commands

Theme Management

The theme group controls visual appearance:

• omarchy theme list – Lists all installed themes
• omarchy theme set <name> – Applies the specified theme, updating colors and icons

omarchy theme set nord

Font and Display Configuration

• omarchy font list – Shows available fonts that Omarchy can use
• omarchy toggle <feature> – Enables or disables specific system features such as touchscreen, screensaver, or nightlight

omarchy toggle nightlight

Media Capture and Interface Commands

Screenshot and Recording

The capture group provides multiple aliases for screen capture:

• omarchy screenshot – Takes a screenshot
• omarchy screenshot-full – Full-screen capture alias
• omarchy screenrecord – Starts a screen-recording session

Menu and TUI Management

• omarchy menu – Opens the Omarchy menu UI or lists menu entries
• omarchy tui-install – Installs terminal-UI launchers for applications
• omarchy tui-remove – Removes terminal-UI launchers

Advanced System Configuration

Configuration Recovery

The omarchy refresh-config <path> command restores default configuration files to the user’s ~/.config directory. This is essential when resetting specific application configs to Omarchy defaults.

omarchy refresh-config hypr/hyprland.lua

Package Installation

Install optional software using the hyphenated syntax:

• omarchy install-<pkg> – Installs specific packages (e.g., omarchy install-docker)

Virtual Machine Integration

• omarchy windows-vm – Manages the optional Windows virtual-machine integration

Hook Execution

• omarchy hook <name> – Runs a user-defined hook script from the configuration directory

Discovering Available Commands

The Commands Utility

The omarchy commands utility provides comprehensive command discovery with optional flags:

• --all – Lists every command, including hidden ones
• --json – Outputs machine-readable JSON format
• --markdown – Generates documentation format
• --check – Validates command metadata across all binaries

This command reads the comment headers from each omarchy-* binary to build its list, ensuring accurate descriptions without requiring execution.

Summary

• Omarchy CLI commands are discovered dynamically through the bin/omarchy router script, which scans for omarchy-* prefixed executables
• Core workflow commands include omarchy update for system maintenance, omarchy theme set for customization, and omarchy toggle for hardware features
• Diagnostic tools such as omarchy debug and omarchy system-stats provide environment insights and resource monitoring
• Configuration management uses omarchy refresh-config to restore defaults and omarchy install-<pkg> for optional software
• Command discovery is handled through omarchy commands, which validates metadata defined in agents/skills/command-metadata.md and routed through logic in docs/cli-router.md

Frequently Asked Questions

How does Omarchy discover new CLI commands?

Omarchy dynamically discovers commands through the bin/omarchy router script, which scans the system for any executable binary prefixed with omarchy-*. When found, these binaries are automatically registered as subcommands using the dispatch logic defined in lines 29-98 of the router, which references the GROUP_DESCRIPTIONS table to categorize each command appropriately.

Where can I find documentation for command metadata?

Command metadata standards are defined in agents/skills/command-metadata.md, which specifies the comment-header keys that enrich each command’s description. The routing architecture is explained in docs/cli-router.md, while the actual command binaries (such as bin/omarchy-update and bin/omarchy-theme-set) contain the concrete implementations and inline documentation.

What is the difference between omarchy theme list and omarchy commands?

omarchy theme list is a specific functional command that displays installed themes within the theme group, while omarchy commands is a meta-command that lists every available CLI command across all groups. The latter includes options like --all, --json, and --check for validation, whereas the former executes the specific theme group's listing logic directly.

How do I restore default configurations in Omarchy?

Use the omarchy refresh-config <path> command to restore any default configuration file to your ~/.config directory. For example, omarchy refresh-config hypr/hyprland.lua would reset your Hyprland configuration to the Omarchy defaults. This command belongs to the refresh group and is essential when troubleshooting configuration issues or reverting custom changes.

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