# Omarchy Menus, Panels, and the CLI > Learn the three control surfaces of Omarchy 4: the Super + Space menu, the top bar with its panels and toggles, and the omarchy command in the terminal, so you can find and change anything without hunting through settings windows. --- # Omarchy Menus, Panels, and the CLI On Windows you open Settings. On macOS you open System Settings. On Omarchy there is no Settings app, and that is the first thing that makes people feel lost. The settings did not vanish. They moved into three places that all do the same job in different ways: a keyboard-driven menu, a top bar with popup panels, and a command called `omarchy`. This guide gives you a map of all three. By the end you will know which door to use for which job, how to flip modes like do not disturb and night light, and how to read what the `omarchy` command offers without memorizing it. Checked against Omarchy 4.0.4. ## Prerequisite You need a running Omarchy install. If you are not there yet, start with [Installing Omarchy](/guides/installing-omarchy). If a terminal still feels foreign, [The Terminal and Shell](/guides/the-terminal-and-shell) is the friendly on-ramp. ## How to read this - **In a hurry?** Read Phase 1 for the menu, then skim the hotkey tables in Phase 2. - **Want it to finally make sense?** Read in order. The menu, the bar, and the command are three views of the same system, so each phase explains the next. - **Coming from another OS?** [Omarchy for Windows, macOS, and Ubuntu Users](/guides/omarchy-for-windows-macos-and-ubuntu-users) translates your old reflexes first. ## The phases 1. **[The Omarchy Menu and the Apps Menu](01-the-omarchy-menu-and-apps-menu.md)** - what lives behind `Super + Space`, how the ten top-level entries are organized, and how to find any hotkey. 2. **[The Top Bar, Panels, and Toggles](02-the-top-bar-panels-and-toggles.md)** - what the glyphs mean, the audio, Wi-Fi, Bluetooth, display, and power panels, and the modes you flip on and off. 3. **[The omarchy Command](03-the-omarchy-command.md)** - how the command is organized, how to explore it safely, and which subcommands change things. ## Where this guide stops Editing config files such as `bindings.lua` lives in [Making Omarchy Comfortable](/guides/making-omarchy-comfortable). Installing software is in [Installing and Updating Software on Omarchy](/guides/installing-and-updating-software-on-omarchy). Windows and workspaces are in [Omarchy Tiling, Windows, and Workspaces](/guides/omarchy-tiling-windows-and-workspaces). --- # The Omarchy Menu and the Apps Menu There is no Start button, no Dock, and no desktop full of icons. When Omarchy first boots, the manual itself says you cannot do a thing with the mouse alone. What you can do is press `Super + Space`, and almost everything opens from there. This phase gives you the layout of that menu, so "where is the setting for X" has a short list of possible answers instead of a hundred. ## What the menu actually is The Omarchy menu is a native command palette drawn by the Omarchy shell. Think of Spotlight on macOS or the Windows Start search, but merged with the Settings app, the app store, and the power menu. You type, the list filters, and you press `Return`. Two details matter: - **It launches apps and runs settings from the same box.** Version 4 merged the old split between a launcher and a menu. If an older guide describes a separate launcher, it is describing an earlier release. - **Typing searches inside submenus too.** You do not have to walk the tree. Typing part of a name finds it even when it is nested a level or two down. `Super` is the Windows key on a PC keyboard. On a Mac keyboard it sits where Command was. ## The ten top-level entries Open the menu and you see the same ten rows, in this order. | Entry | What it is for | What is inside (v4.0.4) | |---|---|---| | **Apps** | Starting installed applications | Your installed apps | | **Learn** | Reading the docs without leaving the desktop | Keybindings, the Omarchy manual, the Hyprland wiki, the Arch wiki, LazyVim keymaps, a Bash cheatsheet, Tmux and Herdr keybindings, the community Discord | | **Trigger** | Doing something right now | Emoji, Reminder, Capture, Transcode, Share, Toggle, Hardware, Speed Test | | **Style** | How things look | Theme, Background, Font, Menu Bar, Hyprland, Screensaver | | **Setup** | How things behave | Monitors, Keybindings, Input, Network, Defaults, Plugins, Security, Config, Direct Boot, Reset Computer | | **Install** | Adding software | Package, AUR, Web App, TUI, Service, Development, Editor, Terminal, Browser, AI, Gaming, and more | | **Remove** | Taking software away | Package, Web App, TUI, Theme, Development, Browser, and more | | **Update** | Keeping the system current | Omarchy, Channel, Config, Process, Hardware, Firmware, Password, Timezone, Time | | **About** | System information | Opens the system info screen | | **System** | Leaving the session | Screensaver, Lock, Suspend, Hibernate, Logout, Reboot, Shutdown | A way to remember the middle of the list: **Trigger** is a verb you do now, **Style** changes appearance, **Setup** changes behavior, and **Install**, **Remove**, **Update** are the life of your software. That grouping is a memory aid, not something the manual says, but it matches how the entries are filled. Some rows only show up when they apply. Suspend hides itself if you have turned suspend off, and Hibernate hides itself when your machine cannot hibernate. ## The Apps menu is the same menu, narrowed `Super + Alt + Space` opens the **apps-only** menu. It is the same palette, started on the Apps entry, so a stray letter cannot land you on a setting. When you only want to launch something, this is the faster door. Everything else in the list above is reachable the same way. Several submenus have their own direct hotkey: | Hotkey | Opens | |---|---| | `Super + Space` | The Omarchy menu, from the top | | `Super + Alt + Space` | The apps-only menu | | `Super + Escape` | The System menu (lock, reboot, shutdown) | | `Super + Ctrl + O` | The Toggle menu (under Trigger) | | `Super + Ctrl + C` | The Capture menu (screenshots and recording) | | `Super + Ctrl + H` | The Hardware menu (under Trigger) | | `Super + Ctrl + S` | The Share menu (LocalSend) | | `Super + Ctrl + Shift + Space` | The theme picker | | `Super + Ctrl + Space` | The background picker | You do not need to memorize that table. It shows a pattern: a hotkey exists for the thing you reach for daily, and the menu covers the long tail. ## When the menu opens a file Several Setup entries do not show a form. They open a plain text file in your editor. _Setup > Monitors_ opens `monitors.lua`, _Setup > Keybindings_ opens `bindings.lua`, and _Setup > Input_ opens `input.lua`. The default editor is Neovim. To save and leave, type `:wq` and press `Return`. When you close the editor, Omarchy restarts whatever needs restarting so the change takes effect. That is how Omarchy replaces the Settings window: the settings are files, and the menu is a shortcut to the right file. [Making Omarchy Comfortable](/guides/making-omarchy-comfortable) goes into what to put in them, and [Editing in the Terminal](/guides/editing-in-the-terminal) helps if Neovim is new. ## Forgot a hotkey? Ask the system Press `Super + K`. It shows every main keybinding in a searchable list. The same list is under _Learn > Keybindings_. The manual's advice is to skim the hotkeys once, then use `Super + K` whenever a binding slips, and calls it the only hotkey you have to memorize. Two sibling lists exist for terminal tools: `Super + Alt + K` shows Tmux bindings, and `Super + Ctrl + K` shows Herdr bindings. From a terminal, the same information prints with a command: ```bash omarchy menu keybindings --print ``` Your own overrides live in `~/.config/hypr/bindings.lua`, and that list reflects them. ## Driving the menu from a terminal The menu has a command, which is handy for your own keybindings and scripts. These forms come from the manual: ```bash omarchy menu # open the menu at the root omarchy menu summon style.theme # jump straight to the theme picker omarchy menu toggle system # open the System menu, or close it if already open omarchy menu close # put the menu away ``` The words after `summon` are the entry's dotted id. `style.theme` means "the Theme row under Style", which is the same shape as the _Style > Theme_ path you click through. ## Adding your own row You can extend the menu without touching Omarchy's files. Create `~/.config/omarchy/extensions/omarchy-menu.jsonc`. It is JSONC, which is JSON that allows comments. Each entry is keyed by a dotted id, and the id decides where it lands in the tree. Reusing an existing id overrides that row. The manual's example adds a top-level "Personal" entry with a Notes row under it: ```json { "personal": { "label": "Personal" }, "personal.notes": { "label": "Notes", "action": "omarchy-launch-editor ~/notes" } } ``` The manual's own example also gives each row an icon glyph, and the file Omarchy ships documents every field in comments, so read that before adding more. ⚠️ **Gotcha.** Do not edit the menu definition under `/usr/share/omarchy`. Omarchy owns that folder, and a package update overwrites it. Your files under `~/.config` are yours, and updates leave them alone. ## Your turn: find three things Use the menu, not a search engine. This takes about two minutes and builds the map in your head. ```exercise [ { "type": "predict", "task": "Which hotkey opens the apps-only menu? Write it the way this guide does, for example `Super + Space`.", "accept": ["/^super\\s*\\+\\s*alt\\s*\\+\\s*space$/i"], "hint": "It is the Omarchy menu hotkey with one extra modifier held down." }, { "type": "task", "task": "Without leaving the menu, find: (1) the entry that lists every keybinding, (2) the entry that opens your monitors file, (3) the entry that installs a package.", "reveal": "(1) Learn > Keybindings, (2) Setup > Monitors, (3) Install > Package.", "checklist": ["Found Learn > Keybindings", "Found Setup > Monitors", "Found Install > Package"] } ] ``` Check yourself before moving on: ```quiz [ { "q": "You want to start an application and do not want to risk landing on a setting. Which door is best?", "choices": [ "Super + Alt + Space, the apps-only menu", "Super + Escape, the System menu", "Super + Ctrl + O, the Toggle menu" ], "answer": 0, "explain": "The apps-only menu is the same palette started on the Apps entry. The other two open the System and Toggle menus.", "why": [null, "That menu holds lock, suspend, reboot, and shutdown, not applications.", "That menu holds mode switches such as night light, not applications."] }, { "q": "You choose Setup > Keybindings. What happens?", "choices": [ "A settings window with a list of shortcuts opens", "Your bindings.lua file opens in your editor, and Omarchy restarts what needs it when you close the editor", "Omarchy resets every shortcut to its default" ], "answer": 1, "explain": "Setup entries for monitors, keybindings, and input open the real config file. The settings are files, and the menu is a shortcut to them." }, { "q": "Where should your own extra menu rows live?", "choices": [ "In /usr/share/omarchy, next to the default menu", "In ~/.config/omarchy/extensions/omarchy-menu.jsonc", "Inside the Omarchy shell's source code" ], "answer": 1, "explain": "Files under /usr/share/omarchy belong to Omarchy and are overwritten by updates. Extensions under ~/.config are yours." } ] ``` ## Recap 1. `Super + Space` opens one menu that both launches apps and changes settings, and typing filters it, nested rows included. 2. The ten entries are Apps, Learn, Trigger, Style, Setup, Install, Remove, Update, About, and System. 3. `Super + Alt + Space` is the apps-only menu, and `Super + Escape`, `Super + Ctrl + O`, `Super + Ctrl + C`, and `Super + Ctrl + H` open specific submenus. 4. Several Setup entries open the real config file in your editor, and Omarchy restarts what needs it afterward. 5. `Super + K` lists every main keybinding, and `omarchy menu keybindings --print` prints it in a terminal. 6. Your own menu rows go in `~/.config/omarchy/extensions/omarchy-menu.jsonc`, never under `/usr/share/omarchy`. Next up, [The Top Bar, Panels, and Toggles](02-the-top-bar-panels-and-toggles.md): the strip across your screen and the popups behind it. --- # The Top Bar, Panels, and Toggles The strip along the top of the screen is the one part of Omarchy that is always visible, so it is worth knowing what every glyph does. On Windows it covers the taskbar and system tray, and on macOS the menu bar and Notification Center. This phase shows how to read the bar, open the popups behind it with a hotkey instead of aiming at a tiny icon, and flip the day-to-day modes you would otherwise hunt through settings for. ## What the bar actually is The bar is not a separate program bolted onto the desktop. It is part of the Omarchy shell, one long-running process that also draws the menu, the notifications, the volume and brightness popups, and the lock screen. That is why a panel opens instantly and why everything shares one theme. By default the bar has three sections. | Section | Default contents | |---|---| | **Left** | The Omarchy logo (opens the menu) and the workspace indicators | | **Center** | Status indicators, the clock, the keyboard layout, the weather, and an update badge | | **Right** | The system tray, agents, Bluetooth, network, audio, display, and power | Some widgets only appear when they have something to say. The keyboard layout shows only if you configured more than one. The update badge, a circle arrow right of the clock, appears only when an Omarchy update is waiting. The agents icon appears the first time Omarchy finds AI coding usage on the machine. ## Clicking: the right and middle buttons matter Most widgets do something on left click, right click, and middle click, and some react to scrolling. The right and middle buttons are where a lot of the useful behavior hides. | Widget | Left | Right | Middle or scroll | |---|---|---|---| | Menu | Omarchy menu | New terminal | - | | Clock | Calendar popup | Cycle the label format | Middle: timezone picker | | Weather | Forecast popup | Full weather as a notification | Middle: refresh | | Audio | Audio panel | Mute | Middle: panel. Scroll: volume | | Network | Network panel | - | - | | Bluetooth | Bluetooth panel | Toggle the radio | - | | Display | Display panel | - | Scroll: brightness | | Power | Power panel | Toggle the battery percentage | - | | Tray | Hover to reveal the drawer | Right-click the chevron to manage | - | | Omarchy update | Run the update | - | - | The media and microphone widgets exist but are off by default. The Tailscale and Dropbox widgets only appear after you install those services from _Install > Service_. ## Panels: do the thing, do not only read it Clicking an icon opens a **panel**: a popup with sliders and lists you can use with the keyboard. Each panel has a hotkey, so you never need to aim at a 16-pixel glyph. | Hotkey | Panel | What you do there | |---|---|---| | `Super + Ctrl + A` | Audio | Master volume, pick the output device, and a per-app mixer | | `Super + Ctrl + W` | Network | Scan Wi-Fi, see signal strength, connect, choose a DNS provider | | `Super + Ctrl + B` | Bluetooth | See devices, connect or disconnect, read battery levels | | `Super + Ctrl + D` | Display | Brightness, text size, monitor scaling presets, per-monitor controls | | `Super + Ctrl + P` | Power | Battery stats, power profiles, system info | | `Super + Ctrl + Alt + D` | Calendar | A month grid with ISO week numbers | | `Super + Ctrl + 1-9` | The nth panel | Counts icons left to right in the right section, skipping the tray | Inside any panel, the arrow keys move, `Return` activates, `Tab` steps to the neighbouring panel, and `Escape` closes it. The Power panel remembers a separate power profile for battery and for AC. If you are used to separate Wi-Fi and Bluetooth tools from older Omarchy releases, they are gone in version 4. These panels replaced them, with NetworkManager doing the work underneath. ## Indicators: the glyphs that appear on their own The cluster in the center of the bar is the **indicators** widget. It shows modes you switched on: do not disturb, night light, a queued reminder, an active screen recording, stay awake, and dictation. Inactive ones stay hidden until you hover the center of the bar, and clicking an active one turns that mode off. To see them all the time, set `alwaysShow` to `true` on the indicators widget in your shell config, covered below. ## Toggles: modes, not settings A lot of what you change day to day is not a setting. It is a mode you turn on for an hour: night light while you work late, do not disturb while you present. Omarchy calls these **toggles**. Each one has a hotkey, a menu entry, and a command, all hitting the same switch. `Super + Ctrl + O` opens _Trigger > Toggle_ directly. | Toggle | Hotkey | Command | |---|---|---| | Night light | `Super + Ctrl + N` | `omarchy toggle nightlight` | | Silence notifications | `Super + Ctrl + ,` | `omarchy toggle notification silencing` | | Stay awake (no idle lock) | `Super + Ctrl + I` | `omarchy toggle idle` | | Menu bar | `Super + Shift + Space` | `omarchy toggle bar` | | Screensaver | none | `omarchy toggle screensaver` | | Crash capture | none | `omarchy toggle crash-capture` | Touchpad, touchscreen, and hybrid GPU switches live under _Trigger > Hardware_ (`Super + Ctrl + H`), because they only matter when you own that hardware. The Toggle menu also carries battery percentage, workspace layout (`Super + L`), window gaps (`Super + Shift + Backspace`), and the one-window square aspect (`Super + Ctrl + Backspace`). Most toggles are a flag file under `~/.local/state/omarchy/toggles/`. The flags are named for the **off** state, such as `screensaver-off`, so a file's presence means the feature is disabled. ### Night light `Super + Ctrl + N` warms the screen to 4000K, and pressing it again returns it to 6500K. It uses hyprsunset, which the toggle starts for you. Out of the box, hyprsunset does nothing to your screen until you ask. ### Do not disturb, and where notifications go `Super + Ctrl + ,` silences notifications. No pop-ups appear, and the crossed-out bell stays in the bar to remind you why things went quiet. Nothing is lost: silenced notifications are written to your notification history. | Hotkey | Does | |---|---| | `Super + ,` | Dismiss the latest notification | | `Super + Shift + ,` | Dismiss all notifications | | `Super + Ctrl + ,` | Toggle silencing | | `Super + Alt + ,` | Invoke the most recent notification | | `Super + Shift + Alt + ,` | Open notification history | Two kinds still get through while silencing is on: Omarchy's own confirmations for something you did a moment ago, such as "Theme changed", and critical alerts sent from the command line. ### Idle, the screensaver, and the lock screen Idle timing lives in `~/.config/omarchy/shell.json` as a top-level `idle` block: ```json { "version": 1, "idle": { "screensaver": 150, "lock": 300 } } ``` Both numbers are seconds counted from when you went idle, not from each other. With the defaults the screensaver starts after two and a half minutes and the lock screen takes over at five, whether or not the screensaver ran. Saving the file applies the new timings right away. - `Super + Ctrl + I` turns **stay awake** on, so the machine stops locking on idle, and a coffee cup indicator appears. Press it again to return to normal. Use it before a long presentation. - `Super + Ctrl + L` locks the computer immediately. - The screensaver is ASCII art with random text effects, one per monitor, and any key exits it. _System > Screensaver_ starts it on demand, and `Super + Escape` opens the System menu directly. Stay awake controls locking and the screensaver, not suspend or hibernation. Those have their own setup. ### Reminders and notices Reminders are countdown timers with a message, delivered as a notification. | Hotkey | Does | |---|---| | `Super + Ctrl + R` | Set a reminder | | `Super + Ctrl + Alt + R` | See all reminders | | `Super + Ctrl + Shift + R` | Clear all reminders | From a terminal, the number is minutes: `omarchy reminder 7 'Tea ready'`. Three **notices** put information on screen without opening anything: `Super + Ctrl + Alt + T` shows the date and time, `Super + Ctrl + Alt + B` shows the battery, and `Super + Ctrl + Alt + W` shows the weather. The weather location comes from your IP address, which can be off. Pin it with `omarchy weather location --set Malibu`, run `omarchy weather location` alone to see where it thinks you are, and add `--clear` to return to auto-detection. ## Rearranging the bar You can change the bar without opening a file. Drag an empty patch of the bar toward another screen edge and it moves there. Double-left-click empty space to toggle transparency. Drag any widget to reorder it. The same options are in _Style > Menu Bar_. The commands, from the manual: ```bash omarchy bar position bottom omarchy bar transparent toggle omarchy bar move omarchy.clock --section center --index 0 omarchy bar set omarchy.clock format "HH:mm" omarchy bar defaults ``` To add or remove a whole widget, list them with `omarchy plugin list`, then enable or disable by id: ```bash omarchy plugin enable omarchy.media --section center omarchy plugin disable omarchy.weather ``` `Super + Shift + Space` hides the bar and shows it again without stopping the shell, so panels and hotkeys keep working. All of this is stored in `~/.config/omarchy/shell.json` under a `bar` key. A trimmed version: ```json { "version": 1, "bar": { "position": "top", "transparent": false, "centerAnchor": "omarchy.clock", "layout": { "left": [{ "id": "omarchy.menu" }, { "id": "omarchy.workspaces" }], "center": [{ "id": "omarchy.clock", "format": "HH:mm" }], "right": [{ "id": "omarchy.audio" }, { "id": "omarchy.power" }] } } } ``` ⚠️ **Gotcha.** Once you have your own `shell.json`, it is canonical. Until you customize anything, the shell reads Omarchy's default file. The moment you drag a widget or run an `omarchy bar` command, your file takes over, and there is no merge with the defaults. New default widgets in future releases will not appear on your bar. `omarchy bar defaults` restores the shipped layout. ## Your turn: quiet the machine for a talk You are about to present for an hour. You want no pop-ups, no screen locking, and a warm screen you can leave on. The three hotkeys are in the tables above. ```exercise [ { "type": "predict", "task": "Which hotkey silences notifications? Write it like `Super + Ctrl + X`.", "accept": ["/^super\\s*\\+\\s*ctrl\\s*\\+\\s*,$/i"], "hint": "It uses the comma key, and it is in the Notifications table." }, { "type": "task", "task": "Turn on do not disturb and stay awake, confirm both indicators appear in the bar (hover the center if they are hidden), then turn both off again.", "reveal": "Super + Ctrl + , for silencing and Super + Ctrl + I for stay awake. Press each again to turn it off.", "checklist": ["Pressed the silencing hotkey and saw the crossed-out bell", "Pressed the stay awake hotkey and saw the coffee cup", "Turned both back off"] } ] ``` Check yourself before moving on: ```quiz [ { "q": "You set idle.screensaver to 150 and idle.lock to 300 in shell.json. When does the lock screen appear if you stay idle?", "choices": [ "300 seconds after the screensaver ends", "300 seconds after you went idle", "450 seconds after you went idle" ], "answer": 1, "explain": "Both values count from the moment you went idle, not from each other.", "why": ["The values are not chained to each other.", null, "That would add the two numbers, but each is measured from the same start."] }, { "q": "You drag a widget on the bar. Weeks later a new Omarchy release adds a default widget, but it never shows up. Why?", "choices": [ "Dragging disabled updates for the bar", "Your own shell.json now replaces the defaults without merging", "Widgets can only be added from the menu" ], "answer": 1, "explain": "Once you have your own shell.json it is canonical. Run omarchy bar defaults for a clean slate." }, { "q": "Which statement about do not disturb is correct?", "choices": [ "Silenced notifications are deleted", "Silenced notifications go to the notification history", "Do not disturb blocks every notification, including Omarchy's own confirmations" ], "answer": 1, "explain": "Nothing is lost: history opens with Super + Shift + Alt + ,. Omarchy's own confirmations and critical command-line alerts still get through." } ] ``` ## Recap 1. The bar is part of the Omarchy shell, with left, center, and right sections, and some widgets appear only when relevant. 2. Right and middle clicks, plus scrolling, hold much of the bar's behavior. 3. Panels open with `Super + Ctrl + A`, `W`, `B`, `D`, and `P`, and the arrows, `Return`, `Tab`, and `Escape` work inside them. 4. Toggles are modes: night light (`Super + Ctrl + N`), silencing (`Super + Ctrl + ,`), and stay awake (`Super + Ctrl + I`), each with a menu entry and a command. 5. Idle timings live in `shell.json`, and both numbers count from when you went idle. 6. Your own `shell.json` replaces the defaults entirely, and `omarchy bar defaults` resets it. Next up, [The omarchy Command](03-the-omarchy-command.md): the same switches from the terminal, and how to explore them safely. --- # The omarchy Command The menu and the bar are for your hands. The `omarchy` command is for everything else: scripts, your own hotkeys, and the moment you are already in a terminal and a menu would be a detour. Every action behind the menu has a command, and the manual calls this especially useful when an AI agent is helping you configure the machine. You do not need to memorize it. You need to know how it is organized and how to ask it what it can do. ## One command, many groups Run `omarchy` with nothing after it. It prints the command center. This is the shape the manual shows, trimmed: ```console $ omarchy Omarchy command center Usage: omarchy [args...] omarchy commands [--all] [--json] [--check] omarchy --help omarchy --help Common commands: omarchy update Update Omarchy and system packages omarchy theme list List available themes omarchy theme set Apply a theme omarchy font list List available fonts omarchy screenshot Take a screenshot omarchy debug Print debugging information Groups: agent AI coding agent usage data audio Audio input and output controls bar Omarchy shell bar layout and settings ... ``` *What just happened:* Omarchy listed the most common commands and then every **group**. A group is a family of related commands, like `theme`, `pkg`, `toggle`, or `capture`. The structure is always `omarchy [arguments]`. Version 4.0.4 has dozens of groups. A few you will meet early: | Group | What it controls | |---|---| | `theme`, `font` | Appearance | | `pkg` | Installing and removing packages | | `update`, `channel`, `snapshot` | Keeping the system current and recoverable | | `toggle`, `reminder`, `notification` | The modes and messages from Phase 2 | | `bar`, `plugin`, `menu` | The shell and its widgets | | `capture` | Screenshots and screen recording | | `restart` | Restarting one component, such as the shell, Wi-Fi, or audio | | `debug`, `version` | Diagnostics | ## Asking the command what it can do Every group and every command answers `--help`: ```bash omarchy capture --help omarchy capture screenshot --help ``` Typing a group name alone, such as `omarchy capture`, lists its commands with their arguments. The manual shows the capture group returning lines like `omarchy capture screenshot [smart|region|windows|fullscreen] [slurp|copy|save] [--editor=]`. Square brackets mean optional, angle brackets mean you fill it in, and `|` means choose one. To list everything at once, use `omarchy commands`. Add `--all` to include commands marked hidden, and `--json` for output a program can read. ## Hyphens and spaces are the same thing Omarchy's commands are programs named `omarchy--`, and `omarchy ` is a friendlier way to call them. These pairs are identical: | Spaced form | Hyphenated form | |---|---| | `omarchy update` | `omarchy-update` | | `omarchy pkg add jq` | `omarchy-pkg-add jq` | | `omarchy snapshot create` | `omarchy-snapshot create` | | `omarchy theme set ` | `omarchy-theme-set ` | You will see both forms in the manual, in menu definitions, and in other people's config files. Do not let it confuse you. The hyphenated form is also what keybinding files tend to use. ## Safe to explore: commands that only read Start with these. They print information and change nothing: ```bash omarchy version # which Omarchy you are running omarchy channel current # stable, rc, edge, or dev omarchy theme current # the active theme omarchy theme list # every theme you can apply omarchy font list # every monospace font you can apply omarchy network status # active network state omarchy reminder show # your pending reminders omarchy weather location # where Omarchy thinks you are omarchy toggle idle status # stay-awake state, as JSON ``` ## Everyday commands that change something small These change a setting you can change back: ```bash omarchy theme set # apply a theme omarchy font set # set the monospace font omarchy toggle nightlight # same as Super + Ctrl + N omarchy reminder 20 'Stand up' # minutes, then a message omarchy bar position bottom # move the bar omarchy restart shell # restart the Omarchy shell ``` `omarchy restart` is the gentle first move when something misbehaves. It has targets for the shell, Wi-Fi, Bluetooth, audio, and the trackpad, and restarting one component is far cheaper than rebooting. [When Omarchy Breaks](/guides/when-omarchy-breaks) builds a whole troubleshooting routine on it. ## Commands that return true or false Some commands answer a yes-or-no question through their **exit status**, which makes them usable in scripts. Exit status is the hidden number every Unix command leaves behind: zero means success or true, anything else means failure or false. The `&&` operator runs the next command only when the first one succeeds. ```console $ omarchy pkg present jq && echo "jq is installed" jq is installed ``` *What just happened:* `omarchy pkg present` returns true only when every named package is installed. Its sibling `omarchy pkg missing` is true when any named package is absent, and `omarchy battery present` checks for a battery. The manual's example for toggles uses the same idea: `omarchy-toggle-enabled screensaver-off && echo "screensaver is off"`. The shell is covered properly in [The Terminal and Shell](/guides/the-terminal-and-shell). You only need `&&` here. ## Commands that overwrite or erase: read first This is where the CLI earns respect. The same tool that sets a theme can also reset your whole configuration. Their summaries say what they do, and you should read them before running: | Command | What it does | Cost | |---|---|---| | `omarchy update` | Updates Omarchy and system packages, asking first unless you pass `-y` | Large and intentional. See the software guide | | `omarchy refresh hyprland` | Overwrites all your Hyprland Lua configs in `~/.config/hypr` with the defaults | Your edits there are replaced | | `omarchy refresh shell` | Resets `shell.json` to the defaults | Your bar layout and idle timings are replaced | | `omarchy reinstall configs` | Resets Omarchy user configs to the shipped defaults, described as destructive | Your config changes are overwritten | | `omarchy reinstall` | Reinstalls the default packages and resets configs | Same, plus package changes | | `omarchy system factory reset` | Returns the machine to its freshly installed state | Everything you added | ⚠️ **Gotcha.** A `refresh` or `reinstall` is a fix for a corrupted config, not a tidy-up. If your config files hold changes you care about, copy them somewhere first. The manual warns that after `omarchy reinstall`, "all your user config changes to the Omarchy defaults will be overwritten". A habit that costs nothing: run `omarchy --help` before any command you did not write yourself. ## Using the command from your own hotkey Because every menu action is a command, you can bind any of them to a key. Your personal bindings live in `~/.config/hypr/bindings.lua`, in Lua. The shipped template shows the pattern, which is a key combination, a description, and a command: ```lua o.bind("SUPER + SHIFT + R", "Stand up reminder", "omarchy reminder 20 'Stand up'") ``` Press `Super + K` first to check that your chosen combination is free. Making bindings and the rest of your config comfortable is the subject of [Making Omarchy Comfortable](/guides/making-omarchy-comfortable). ## Your turn: read before you run ```exercise [ { "type": "predict", "task": "`omarchy-pkg-add` and `omarchy pkg add` are two spellings of one command. Which one of these is NOT a valid way to call the update command: `omarchy update`, `omarchy-update`, or `omarchy_update`? Write the invalid one.", "accept": ["omarchy_update"], "hint": "The two valid forms use a space or a hyphen between omarchy and the command." }, { "type": "task", "task": "Run `omarchy`, pick any group, then run `omarchy --help`. Find one read-only command and one that changes something, and say which is which from the summary text.", "reveal": "Examples: `omarchy theme current` (reads) and `omarchy theme set ` (changes). The summaries tell you: 'Show current theme' versus 'Apply an Omarchy theme'.", "checklist": ["Listed the groups", "Opened a group's help", "Classified one read-only and one changing command"] } ] ``` Check yourself before moving on: ```quiz [ { "q": "In omarchy capture screenshot [smart|region|windows|fullscreen], what do the square brackets and the pipes mean?", "choices": [ "The argument is optional, and you choose one of the listed words", "You must type all four words, separated by pipes", "The brackets are literal characters you type" ], "answer": 0, "explain": "Brackets mean optional, pipes mean choose one. Angle brackets, as in , mean a value you fill in." }, { "q": "Your Hyprland config has odd behavior and you have personal edits in it. You are tempted to run omarchy refresh hyprland. What is the right first step?", "choices": [ "Run it, because refresh only reloads the config", "Back up the files you care about, because it overwrites your Hyprland Lua configs with the defaults", "Run a factory reset instead, which is safer" ], "answer": 1, "explain": "Refresh replaces your files with the shipped defaults. A copy first means you can recover your own changes.", "why": ["Refresh does not merely reload. It overwrites.", null, "A factory reset is the most destructive option on the list."] }, { "q": "What does omarchy pkg present jq && echo done print when jq is not installed?", "choices": ["done", "Nothing, because present returns false and && skips the echo", "An error saying jq is missing, then done"], "answer": 1, "explain": "present is true only when every named package is installed. When it returns false, && does not run the echo." } ] ``` ## Recap 1. `omarchy` on its own prints the command center, and the shape is always `omarchy [arguments]`. 2. Every group and command answers `--help`, and `omarchy commands` lists them all. 3. `omarchy update` and `omarchy-update` are the same command, spaced or hyphenated. 4. Read-only commands are safe to explore, and `restart` is the gentle first fix. 5. Commands such as `pkg present` return true or false, which makes them usable with `&&`. 6. `refresh`, `reinstall`, and `system factory reset` overwrite or erase, so back up and read `--help` first. This guide covered the three ways to control Omarchy. Next, [Installing and Updating Software on Omarchy](/guides/installing-and-updating-software-on-omarchy) puts the `pkg` and `update` groups to real work.