# Essential Omarchy CLI Commands and Their Purposes > Master essential Omarchy CLI commands for system updates theme management hardware toggles and diagnostics Discover powerful tools in this unified interface - Repository: [Omacom/omarchy](https://github.com/omacom/omarchy) - Tags: how-to-guide - Published: 2026-09-08 --- **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 ` 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`](https://github.com/omacom/omarchy/blob/main/agents/skills/command-metadata.md), while the routing logic and dispatch system are documented in [`docs/cli-router.md`](https://github.com/omacom/omarchy/blob/main/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. ```bash 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 `** – Applies the specified theme, updating colors and icons ```bash omarchy theme set nord ``` ### Font and Display Configuration - **`omarchy font list`** – Shows available fonts that Omarchy can use - **`omarchy toggle `** – Enables or disables specific system features such as `touchscreen`, `screensaver`, or `nightlight` ```bash 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 `** command restores default configuration files to the user’s `~/.config` directory. This is essential when resetting specific application configs to Omarchy defaults. ```bash omarchy refresh-config hypr/hyprland.lua ``` ### Package Installation Install optional software using the hyphenated syntax: - **`omarchy install-`** – 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 `** – 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-` for optional software - **Command discovery** is handled through `omarchy commands`, which validates metadata defined in [`agents/skills/command-metadata.md`](https://github.com/omacom/omarchy/blob/main/agents/skills/command-metadata.md) and routed through logic in [`docs/cli-router.md`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/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 `** 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.