Completion should not include --help

The unified `omarchy` dispatcher is the user-facing entry point

AGENTS.md

@@ -12,6 +12,7 @@
 All commands start with `omarchy-`. Prefixes indicate purpose:
 
 - `cmd-` - check if commands exist, misc utility commands
+- `capture-` - screenshots, screen recordings, and other capture tools
 - `pkg-` - package management helpers
 - `hw-` - hardware detection (return exit codes for use in conditionals)
 - `refresh-` - copy default config to user's `~/.config/`

applications/hidden/lstopo.desktop

@@ -0,0 +1,2 @@
+[Desktop Entry]
+Hidden=true

bin/omarchy-ac-present

@@ -1,6 +1,6 @@
 #!/bin/bash
 
-# Returns true if AC power is connected.
+# omarchy:summary=Returns true if AC power is connected.
 
 for ac in /sys/class/power_supply/AC* /sys/class/power_supply/ADP*; do
   [[ -r $ac/online && $(cat "$ac/online") == "1" ]] && exit 0

bin/omarchy-audio-input-mute

@@ -0,0 +1,11 @@
+#!/bin/bash
+
+# omarchy:summary=Toggle microphone mute. Dell XPS and ThinkPad systems get special handling for the hardware LED.
+
+if omarchy-hw-match "XPS"; then
+  omarchy-audio-input-mute-xps
+elif omarchy-hw-match "ThinkPad"; then
+  omarchy-audio-input-mute-thinkpad
+else
+  omarchy-swayosd-client --input-volume mute-toggle
+fi

bin/omarchy-audio-input-mute-thinkpad

@@ -1,7 +1,6 @@
 #!/bin/bash
 
-# Toggle microphone mute on ThinkPad systems. Uses wpctl for reliable toggling
-# and syncs the platform::micmute LED via brightnessctl.
+# omarchy:summary=Toggle microphone mute on ThinkPad systems. Uses wpctl for reliable toggling
 
 wpctl set-mute @DEFAULT_AUDIO_SOURCE@ toggle >/dev/null
 
@@ -17,7 +16,6 @@ fi
 
 brightnessctl --device="platform::micmute" set "$led_value" >/dev/null 2>&1 || true
 
-swayosd-client \
-  --monitor "$(omarchy-hyprland-monitor-focused)" \
+omarchy-swayosd-client \
   --custom-message "$osd_message" \
   --custom-icon "$osd_icon"

bin/omarchy-audio-input-mute-xps

@@ -1,7 +1,6 @@
 #!/bin/bash
 
-# Toggle microphone mute on Dell XPS systems. Uses wpctl for reliable toggling
-# and syncs the ALSA capture switch so the hardware mic mute LED follows state.
+# omarchy:summary=Toggle microphone mute on Dell XPS systems. Uses wpctl for reliable toggling
 
 wpctl set-mute @DEFAULT_AUDIO_SOURCE@ toggle >/dev/null
 

bin/omarchy-audio-output-switch

@@ -1,6 +1,6 @@
 #!/bin/bash
 
-# Switch between audio outputs while preserving the mute status. By default mapped to Super + Mute.
+# omarchy:summary=Switch between audio outputs while preserving the mute status. By default mapped to Super + Mute.
 
 sinks=$(pactl -f json list sinks | jq '[.[] | select((.ports | length == 0) or ([.ports[]? | .availability != "not available"] | any))]')
 sinks_count=$(echo "$sinks" | jq '. | length')

bin/omarchy-battery-capacity

@@ -1,7 +1,6 @@
 #!/bin/bash
 
-# Returns the battery full capacity in Wh (rounded to whole number).
-# Used by omarchy-battery-status for displaying battery capacity.
+# omarchy:summary=Returns the battery full capacity in Wh (rounded to whole number).
 
 battery_info=$(upower -i $(upower -e | grep BAT))
 

bin/omarchy-battery-monitor

@@ -1,6 +1,6 @@
 #!/bin/bash
 
-# Designed to be run by systemd timer every 30 seconds and alerts if battery is low
+# omarchy:summary=Designed to be run by systemd timer every 30 seconds and alerts if battery is low
 
 BATTERY_THRESHOLD=10
 NOTIFICATION_FLAG="/run/user/$UID/omarchy_battery_notified"

bin/omarchy-battery-present

@@ -1,7 +1,6 @@
 #!/bin/bash
 
-# Returns true if a battery is present on the system.
-# Used by the battery monitor and other battery-related checks.
+# omarchy:summary=Returns true if a battery is present on the system.
 
 for bat in /sys/class/power_supply/BAT*; do
   [[ -r $bat/present ]] &&

bin/omarchy-battery-remaining

@@ -1,7 +1,6 @@
 #!/bin/bash
 
-# Returns the battery percentage remaining as an integer.
-# Used by the battery monitor and the Ctrl + Shift + Super + B hotkey.
+# omarchy:summary=Returns the battery percentage remaining as an integer.
 
 upower -i $(upower -e | grep BAT) | awk '/percentage/ { 
     print int($2)

bin/omarchy-battery-remaining-time

@@ -1,6 +1,6 @@
 #!/bin/bash
 
-# Returns the battery time remaining (to empty or full) in a compact format.
+# omarchy:summary=Returns the battery time remaining (to empty or full) in a compact format.
 
 battery_info=$(upower -i $(upower -e | grep BAT))
 

bin/omarchy-battery-status

@@ -1,7 +1,6 @@
 #!/bin/bash
 
-# Returns a formatted battery status string with percentage and power draw/charge.
-# Used by the battery notification hotkey (Ctrl + Shift + Super + B).
+# omarchy:summary=Returns a formatted battery status string with percentage and power draw/charge.
 
 battery_info=$(upower -i $(upower -e | grep BAT))
 

bin/omarchy-branch-set

@@ -1,6 +1,7 @@
 #!/bin/bash
 
-# Set the branch for Omarchy's git repository.
+# omarchy:summary=Set the branch for Omarchy's git repository.
+# omarchy:args=<master|rc|dev>
 
 if (($# == 0)); then
   echo "Usage: omarchy-branch-set [master|rc|dev]"

bin/omarchy-brightness-display

@@ -1,7 +1,7 @@
 #!/bin/bash
 
-# Adjust brightness on the most likely display device.
-# Usage: omarchy-brightness-display <step>
+# omarchy:summary=Adjust brightness on the most likely display device.
+# omarchy:args=<step>
 
 step="${1:-+5%}"
 
@@ -14,6 +14,31 @@ for candidate in amdgpu_bl* intel_backlight acpi_video*; do
   fi
 done
 
+# Current brightness percentage
+current=$(brightnessctl -d "$device" -m | cut -d',' -f4 | tr -d '%')
+
+# Apply non-uniform step size: 1% steps if at or below 5%, otherwise set an
+# absolute target percentage to avoid raw backlight rounding causing uneven OSD steps.
+if [[ $step == "+5%" ]]; then
+  if (( current < 5 )); then
+    (( target = current + 1 ))
+  else
+    (( target = current + 5 ))
+  fi
+
+  (( target > 100 )) && target=100
+  step="$target%"
+elif [[ $step == "5%-" ]]; then
+  if (( current <= 5 )); then
+    (( target = current - 1 ))
+  else
+    (( target = current - 5 ))
+  fi
+
+  (( target < 1 )) && target=1
+  step="$target%"
+fi
+
 # Set the actual brightness of the display device.
 brightnessctl -d "$device" set "$step" >/dev/null
 

bin/omarchy-brightness-display-apple

@@ -1,6 +1,7 @@
 #!/bin/bash
 
-# Adjust the brightness on Apple Studio Displays and Apple XDR Displays using asdcontrol.
+# omarchy:summary=Adjust the brightness on Apple Studio Displays and Apple XDR Displays using asdcontrol.
+# omarchy:requires-sudo=true
 
 if (( $# == 0 )); then
   echo "Adjust Apple Display Brightness by passing +5000 or -5000 (or any range from 0-60000)"

bin/omarchy-brightness-keyboard

@@ -1,7 +1,7 @@
 #!/bin/bash
 
-# Adjust keyboard backlight brightness using available steps.
-# Usage: omarchy-brightness-keyboard <up|down|cycle>
+# omarchy:summary=Adjust keyboard backlight brightness using available steps.
+# omarchy:args=<up|down|cycle>
 
 direction="${1:-up}"
 

bin/omarchy-capture-screenrecording

@@ -1,9 +1,10 @@
 #!/bin/bash
 
-# Start and stop a screenrecording, which will be saved to ~/Videos by default.
-# Alternative location can be set via OMARCHY_SCREENRECORD_DIR or XDG_VIDEOS_DIR ENVs.
-# Resolution is capped to 4K for monitors above 4K, native otherwise.
-# Override via --resolution= (e.g. --resolution=1920x1080, --resolution=0x0 for native).
+# omarchy:summary=Start or stop screen recording
+# omarchy:group=capture
+# omarchy:args=[--with-desktop-audio] [--with-microphone-audio] [--with-webcam] [--webcam-device=<device>] [--resolution=<size>] [--stop-recording]
+# omarchy:examples=omarchy screenrecord | omarchy capture screenrecord --with-desktop-audio
+# omarchy:aliases=omarchy screenrecord
 
 [[ -f ~/.config/user-dirs.dirs ]] && source ~/.config/user-dirs.dirs
 OUTPUT_DIR="${OMARCHY_SCREENRECORD_DIR:-${XDG_VIDEOS_DIR:-$HOME/Videos}}"
@@ -164,12 +165,17 @@ finalize_recording() {
   latest=$(cat "$RECORDING_FILE" 2>/dev/null)
   [[ -f $latest ]] || return
 
+  # Re-encode only when the first GOP contains discardable warmup packets — stream copy can't
+  # trim those (it rewinds to the keyframe). Clean recordings stay on the fast stream-copy path.
+  local video_codec=(-c:v copy)
+  if ffprobe -v error -select_streams v:0 -read_intervals %+0.2 -show_entries packet=flags -of csv=p=0 "$latest" 2>/dev/null | grep -q D; then
+    video_codec=(-c:v libx264 -preset veryfast -crf 20)
+  fi
+
   # Trim the first frame, and normalize audio to -14 LUFS if present, in a single pass
-  local args=(-y -ss 0.1 -i "$latest")
+  local args=(-y -ss 0.1 -i "$latest" "${video_codec[@]}")
   if ffprobe -v error -select_streams a -show_entries stream=codec_type -of csv=p=0 "$latest" 2>/dev/null | grep -q audio; then
-    args+=(-af loudnorm=I=-14:TP=-1.5:LRA=11 -c:v copy)
-  else
-    args+=(-c copy)
+    args+=(-af loudnorm=I=-14:TP=-1.5:LRA=11)
   fi
 
   local processed="${latest%.mp4}-processed.mp4"

bin/omarchy-capture-screenshot

@@ -1,8 +1,10 @@
 #!/bin/bash
 
-# Take a screenshot of the whole screen, a specific window, or a user-drawn region.
-# Saves to ~/Pictures by default, but that can be changed via OMARCHY_SCREENSHOT_DIR or XDG_PICTURES_DIR ENVs.
-# Editor defaults to Satty but can be changed via --editor=<name> or OMARCHY_SCREENSHOT_EDITOR env
+# omarchy:summary=Take a screenshot
+# omarchy:group=capture
+# omarchy:args=[smart|region|windows|fullscreen] [slurp|copy] [--editor=<name>]
+# omarchy:examples=omarchy screenshot | omarchy capture screenshot region
+# omarchy:aliases=omarchy screenshot
 
 [[ -f ~/.config/user-dirs.dirs ]] && source ~/.config/user-dirs.dirs
 OUTPUT_DIR="${OMARCHY_SCREENSHOT_DIR:-${XDG_PICTURES_DIR:-$HOME/Pictures}}"
@@ -63,6 +65,13 @@ get_rectangles() {
   hyprctl clients -j | jq -r --arg ws "$active_workspace" '.[] | select(.workspace.id == ($ws | tonumber)) | "\(.at[0]),\(.at[1]) \(.size[0])x\(.size[1])"'
 }
 
+# Keep hyprpicker alive until after grim captures so the screenshot sees the
+# frozen overlay rather than live content shifting during teardown.
+cleanup_freeze() {
+  [[ -n $PID ]] && kill $PID 2>/dev/null
+}
+trap cleanup_freeze EXIT
+
 # Select based on mode
 case "$MODE" in
 region)
@@ -70,14 +79,12 @@ region)
   PID=$!
   sleep .1
   SELECTION=$(slurp 2>/dev/null)
-  kill $PID 2>/dev/null
   ;;
 windows)
   hyprpicker -r -z >/dev/null 2>&1 &
   PID=$!
   sleep .1
   SELECTION=$(get_rectangles | slurp -r 2>/dev/null)
-  kill $PID 2>/dev/null
   ;;
 fullscreen)
   SELECTION=$(hyprctl monitors -j | jq -r "${JQ_MONITOR_GEO} .[] | select(.focused == true) | format_geo")
@@ -88,7 +95,6 @@ smart | *)
   PID=$!
   sleep .1
   SELECTION=$(echo "$RECTS" | slurp 2>/dev/null)
-  kill $PID 2>/dev/null
 
   # If the selection area is L * W < 20, we'll assume you were trying to select whichever
   # window or output it was inside of to prevent accidental 2px snapshots

bin/omarchy-channel-set

@@ -1,17 +1,8 @@
 #!/bin/bash
 
-# Set the Omarchy channel, which dictates what git branch and package repository is used.
-#
-# Stable uses the master branch, which only sees updates on official releases, and
-# the stable package repository, which typically lags the edge by a month to ensure
-# better compatibility.
-#
-# Edge tracks the latest package repository, but still relies on the master branch,
-# so new packages which require config changes may cause conflicts or errors.
-#
-# Dev tracks the active development dev branch, which may include partial or broken updates,
-# as well as the latest package repository. This should only be used by Omarchy developers
-# and people with a lot of experience managing Linux systems.
+# omarchy:summary=Set the Omarchy channel, which dictates what git branch and package repository is used.
+# omarchy:args=<stable|rc|edge|dev>
+# omarchy:requires-sudo=true
 
 if (($# == 0)); then
   echo "Usage: omarchy-channel-set [stable|rc|edge|dev]"

bin/omarchy-cmd-mic-mute

@@ -1,11 +0,0 @@
-#!/bin/bash
-
-# Toggle microphone mute. Dell XPS and ThinkPad systems get special handling for the hardware LED.
-
-if omarchy-hw-match "XPS"; then
-  omarchy-cmd-mic-mute-xps
-elif omarchy-hw-match "ThinkPad"; then
-  omarchy-cmd-mic-mute-thinkpad
-else
-  omarchy-swayosd-client --input-volume mute-toggle
-fi

bin/omarchy-cmd-missing

@@ -1,6 +1,6 @@
 #!/bin/bash
 
-# Returns true if any of the commands passed in as arguments are missing on the system.
+# omarchy:summary=Check whether any required commands are missing
 
 for cmd in "$@"; do
   if ! command -v "$cmd" &>/dev/null; then

bin/omarchy-cmd-present

@@ -1,6 +1,6 @@
 #!/bin/bash
 
-# Returns true if all the commands passed in as arguments exit on the system.
+# omarchy:summary=Check whether all required commands are available
 
 for cmd in "$@"; do
   command -v "$cmd" &>/dev/null || exit 1

bin/omarchy-cmd-terminal-cwd

@@ -1,9 +1,7 @@
 #!/bin/bash
 
-# Returns the current working directory of the active terminal window,
-# so a new terminal window can be started in the same directory.
+# omarchy:summary=Print the current working directory of the active terminal window
 
-# Go from current active terminal to its child shell process and run cwd there
 terminal_pid=$(hyprctl activewindow | awk '/pid:/ {print $2}')
 shell_pid=$(pgrep -P "$terminal_pid" | tail -n1)
 

bin/omarchy-config-direct-boot

@@ -1,7 +1,7 @@
 #!/bin/bash
 
-# Add an EFI boot entry for the Omarchy UKI, allowing the system to boot directly
-# without a bootloader like Limine. Requires UEFI firmware and a built UKI.
+# omarchy:summary=Add or remove an EFI boot entry for the Omarchy UKI, allowing the system to boot directly
+# omarchy:requires-sudo=true
 
 if [[ ! -d /sys/firmware/efi ]]; then
   echo "Error: System is not booted in UEFI mode" >&2
@@ -23,23 +23,36 @@ if cat /sys/class/dmi/id/bios_vendor 2>/dev/null | grep -qi "Apple"; then
   exit 1
 fi
 
-uki_file=$(find /boot/EFI/Linux/ -name "omarchy*.efi" -printf "%f\n" 2>/dev/null | head -1)
+existing_entry=$(efibootmgr | grep -E "^Boot[0-9A-Fa-f]+\*? Omarchy([[:space:]]|$)" | head -1)
 
-if [[ -z $uki_file ]]; then
-  echo "Error: No Omarchy UKI found in /boot/EFI/Linux/" >&2
-  exit 1
-fi
-
-boot_source=$(findmnt -n -o SOURCE /boot)
-disk=$(echo "$boot_source" | sed 's/p\?[0-9]*$//')
-part=$(echo "$boot_source" | grep -o 'p\?[0-9]*$' | sed 's/^p//')
-
-if gum confirm "Setup direct boot (so snapshot booting must be done via bios)?"; then
-  echo "Creating EFI boot entry for $uki_file"
-
-  sudo efibootmgr --create \
-    --disk "$disk" \
-    --part "$part" \
-    --label "Omarchy" \
-    --loader "\\EFI\\Linux\\$uki_file"
+if [[ -n $existing_entry ]]; then
+  boot_num=$(echo "$existing_entry" | sed -n 's/^Boot\([0-9A-Fa-f]\+\).*/\1/p')
+
+  if gum confirm "Disable direct boot (remove Omarchy EFI entry)?"; then
+    echo "Removing EFI boot entry $boot_num"
+    sudo efibootmgr --bootnum "$boot_num" --delete-bootnum >/dev/null
+  fi
+
+  exit 0
+else
+  uki_file=$(find /boot/EFI/Linux/ -name "omarchy*.efi" -printf "%f\n" 2>/dev/null | head -1)
+
+  if [[ -z $uki_file ]]; then
+    echo "Error: No Omarchy UKI found in /boot/EFI/Linux/" >&2
+    exit 1
+  fi
+
+  boot_source=$(findmnt -n -o SOURCE /boot)
+  disk=$(echo "$boot_source" | sed 's/p\?[0-9]*$//')
+  part=$(echo "$boot_source" | grep -o 'p\?[0-9]*$' | sed 's/^p//')
+
+  if gum confirm "Setup direct boot (so snapshot booting must be done via bios)?"; then
+    echo "Creating EFI boot entry for $uki_file"
+
+    sudo efibootmgr --create \
+      --disk "$disk" \
+      --part "$part" \
+      --label "Omarchy" \
+      --loader "\\EFI\\Linux\\$uki_file"
+  fi
 fi

bin/omarchy-debug

@@ -1,6 +1,9 @@
 #!/bin/bash
 
-# Return exhaustive debugging information about the system to help diagnose problems.
+# omarchy:summary=Print debugging information
+# omarchy:args=[--no-sudo] [--print]
+# omarchy:examples=omarchy debug --print --no-sudo
+# omarchy:requires-sudo=true
 
 NO_SUDO=false
 PRINT_ONLY=false

bin/omarchy-dev-add-migration

@@ -1,7 +1,6 @@
 #!/bin/bash
 
-# Creates a new Omarchy migration named after the unix timestamp of the last commit.
-# Only intended for Omarchy developers.
+# omarchy:summary=Creates a new Omarchy migration named after the unix timestamp of the last commit.
 
 cd ~/.local/share/omarchy
 migration_file="$HOME/.local/share/omarchy/migrations/$(git log -1 --format=%cd --date=unix).sh"

bin/omarchy-dev-benchmark

@@ -0,0 +1,111 @@
+#!/bin/bash
+
+# omarchy:summary=Measure Omarchy CLI response times
+# omarchy:args=[--repeat=<count>]
+# omarchy:examples=omarchy dev benchmark | omarchy dev benchmark --repeat=10
+
+set -euo pipefail
+
+OMARCHY_BIN_DIR=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)
+CLI="$OMARCHY_BIN_DIR/omarchy"
+REPEAT=5
+
+show_help() {
+  cat <<'EOF'
+Usage:
+  omarchy dev benchmark [--repeat=<count>]
+
+Measure response times for common Omarchy CLI surfaces.
+
+Options:
+  --repeat=<count>  Number of times to run each case (default: 5)
+EOF
+}
+
+now_us() {
+  local now="${EPOCHREALTIME/./}"
+  printf '%s' "$now"
+}
+
+format_ms() {
+  local us="$1"
+  printf '%d.%03d' "$(( us / 1000 ))" "$(( us % 1000 ))"
+}
+
+run_case() {
+  local label="$1"
+  shift
+  local total_us=0
+  local min_us=0
+  local max_us=0
+  local elapsed_us=0
+  local start_us=0
+  local end_us=0
+  local status=0
+
+  for (( i = 1; i <= REPEAT; i++ )); do
+    start_us=$(now_us)
+    if "$@" >/dev/null; then
+      status=0
+    else
+      status=$?
+    fi
+    end_us=$(now_us)
+
+    if (( status != 0 )); then
+      printf '%-34s failed (exit %d)\n' "$label" "$status"
+      return "$status"
+    fi
+
+    elapsed_us=$(( end_us - start_us ))
+    total_us=$(( total_us + elapsed_us ))
+
+    if (( i == 1 || elapsed_us < min_us )); then
+      min_us=$elapsed_us
+    fi
+
+    if (( elapsed_us > max_us )); then
+      max_us=$elapsed_us
+    fi
+  done
+
+  printf '%-34s avg %8s ms  min %8s ms  max %8s ms\n' \
+    "$label" \
+    "$(format_ms "$(( total_us / REPEAT ))")" \
+    "$(format_ms "$min_us")" \
+    "$(format_ms "$max_us")"
+}
+
+while (( $# > 0 )); do
+  case "$1" in
+  --repeat=*)
+    REPEAT="${1#*=}"
+    ;;
+  --help | -h)
+    show_help
+    exit 0
+    ;;
+  *)
+    echo "Unknown option: $1" >&2
+    show_help >&2
+    exit 2
+    ;;
+  esac
+  shift
+done
+
+if [[ ! $REPEAT =~ ^[0-9]+$ ]] || (( REPEAT < 1 )); then
+  echo "--repeat must be a positive integer" >&2
+  exit 2
+fi
+
+printf 'Omarchy CLI benchmark (%d runs each)\n\n' "$REPEAT"
+run_case "omarchy" "$CLI"
+run_case "omarchy --help" "$CLI" --help
+run_case "omarchy commands" "$CLI" commands
+run_case "omarchy commands --json" "$CLI" commands --json
+run_case "omarchy commands --all --json" "$CLI" commands --all --json
+run_case "omarchy theme set --help" "$CLI" theme set --help
+run_case "omarchy screenshot --help" "$CLI" screenshot --help
+run_case "omarchy restart --help" "$CLI" restart --help
+run_case "omarchy theme current" "$CLI" theme current

bin/omarchy-dev-bin-metadata

@@ -0,0 +1,86 @@
+#!/bin/bash
+
+# omarchy:summary=Show Omarchy bin metadata fields and defaults
+# omarchy:args=[--json]
+
+set -euo pipefail
+
+show_json() {
+  jq -n '{
+    ok: true,
+    defaults: {
+      group: "first filename segment after omarchy-",
+      name: "remaining filename segments with dashes converted to spaces",
+      route: "omarchy <group> <name>",
+      binary: "filename",
+      requires_sudo: false
+    },
+    fields: [
+      {name: "summary", required: true, type: "string", note: "One-line human and agent-facing description."},
+      {name: "group", required: false, type: "string", note: "Only set when the route group should differ from the filename-derived group."},
+      {name: "name", required: false, type: "string", note: "Only set when the route name should differ from the filename-derived name. May be empty for root commands."},
+      {name: "args", required: false, type: "string", note: "Only set when the command accepts arguments."},
+      {name: "examples", required: false, type: "string", note: "Pipe-separated examples."},
+      {name: "aliases", required: false, type: "string", note: "Pipe-separated alternate routes, e.g. omarchy screenshot."},
+      {name: "requires-sudo", required: false, type: "true", default: false, note: "Only include when true."}
+    ]
+  }'
+}
+
+show_help() {
+  cat <<'EOF'
+Omarchy bin metadata
+
+Metadata lives in the top comment block of each executable bin/omarchy-* file.
+Keep it slim: define only fields that are required or override defaults.
+
+Required:
+  # omarchy:summary=<one-line description>
+
+Inferred defaults:
+  group         first filename segment after omarchy-
+  name          remaining filename segments, with dashes converted to spaces
+  route         omarchy <group> <name>
+  binary        filename
+  requires-sudo false
+
+Optional fields:
+  # omarchy:group=<group>                  route override only
+  # omarchy:name=<name>                    route override only; may be empty
+  # omarchy:args=<args>                    only if the command accepts args
+  # omarchy:examples=<cmd> | <cmd>         pipe-separated examples
+  # omarchy:aliases=<route> | <route>      pipe-separated alternate routes
+  # omarchy:requires-sudo=true             only when true
+
+Do not define:
+  binary      inferred from filename
+  usage       derived from route + args
+  false flags or empty args
+
+Examples:
+  # omarchy:summary=Restart Walker and related user services
+
+  # omarchy:summary=Take a screenshot
+  # omarchy:group=capture
+  # omarchy:args=[smart|region|windows|fullscreen] [slurp|copy] [--editor=<name>]
+  # omarchy:examples=omarchy screenshot | omarchy capture screenshot region
+  # omarchy:aliases=omarchy screenshot
+EOF
+}
+
+case "${1:-}" in
+--json)
+  show_json
+  ;;
+--help | -h)
+  show_help
+  ;;
+"")
+  show_help
+  ;;
+*)
+  echo "Unknown option: $1" >&2
+  show_help >&2
+  exit 2
+  ;;
+esac

bin/omarchy-drive-info

@@ -1,6 +1,7 @@
 #!/bin/bash
 
-# Returns drive information about a given volumne, like /dev/nvme0, which is used by omarchy-drive-select.
+# omarchy:summary=Print drive information such as size, model, and mount details
+# omarchy:args=<drive>
 
 if (($# == 0)); then
   echo "Usage: omarchy-drive-info [/dev/drive]"

bin/omarchy-drive-select

@@ -1,6 +1,6 @@
 #!/bin/bash
 
-# Select a drive from a list with info that includes space and brand. Used by omarchy-drive-set-password.
+# omarchy:summary=Select a drive from a list with info that includes space and brand. Used by omarchy-drive-set-password.
 
 if (($# == 0)); then
   drives=$(lsblk -dpno NAME | grep -E '/dev/(sd|hd|vd|nvme|mmcblk|xv)')

bin/omarchy-drive-set-password

@@ -1,11 +1,12 @@
 #!/bin/bash
 
-# Set a new encryption password for a drive selected.
+# omarchy:summary=Set a new encryption password for a drive selected.
+# omarchy:requires-sudo=true
 
 encrypted_drives=$(blkid -t TYPE=crypto_LUKS -o device)
 
 if [[ -n $encrypted_drives ]]; then
-  if (( $(wc -l <<<encrypted_drives) == 1 )); then
+  if (( $(wc -l <<<"$encrypted_drives") == 1 )); then
     drive_to_change="$encrypted_drives"
   else
     drive_to_change="$(omarchy-drive-select "$encrypted_drives")"

bin/omarchy-first-run

@@ -1,6 +1,7 @@
 #!/bin/bash
 
-# Finish the installation of Omarchy with items that can only be done after logging in.
+# omarchy:summary=Finish the installation of Omarchy with items that can only be done after logging in.
+# omarchy:requires-sudo=true
 
 set -e
 

bin/omarchy-font-current

@@ -1,6 +1,6 @@
 #!/bin/bash
 
-# Returns the name of the current monospace font being used by extracting it from the Waybar stylesheet.
-# This can be changed using omarchy-font-set.
+# omarchy:summary=Show current monospace font
+# omarchy:examples=omarchy font current
 
 grep -oP 'font-family:\s*["'\'']?\K[^;"'\'']+' ~/.config/waybar/style.css | head -n1

bin/omarchy-font-list

@@ -1,5 +1,6 @@
 #!/bin/bash
 
-# Returns a list of all the monospace fonts available on the system that can be set using omarchy-font-set.
+# omarchy:summary=List available monospace fonts
+# omarchy:examples=omarchy font list | omarchy font set "CaskaydiaMono Nerd Font"
 
 fc-list :spacing=100 -f "%{family[0]}\n" | grep -v -i -E 'emoji|signwriting|omarchy' | sort -u

bin/omarchy-font-set

@@ -1,7 +1,8 @@
 #!/bin/bash
 
-# Set the system-wide monospace font that should be used by the terminal, hyprlock, waybar, swayosd, etc.
-# The font name must be one of the ones returned by omarchy-font-list.
+# omarchy:summary=Set the system monospace font
+# omarchy:args=<font-name>
+# omarchy:examples=omarchy font list | omarchy font set "CaskaydiaMono Nerd Font"
 
 font_name="$1"
 

bin/omarchy-haptic-touchpad

@@ -1,5 +1,7 @@
 #!/usr/bin/env python3
 
+# omarchy:summary=Run the Synaptics touchpad haptic feedback daemon
+
 """Haptic feedback daemon for Synaptics touchpads with Manual Trigger.
 
 Monitors touchpad button press events and sends haptic pulses via HID

bin/omarchy-hibernation-available

@@ -1,6 +1,7 @@
 #!/bin/bash
 
-# Check if hibernation is supported
+# omarchy:summary=Check if hibernation is supported
+
 if [[ ! -f /sys/power/image_size ]]; then
   exit 1
 fi

bin/omarchy-hibernation-remove

@@ -1,7 +1,7 @@
 #!/bin/bash
 
-# Removes hibernation setup: disables swap, removes swapfile, removes fstab entry,
-# removes resume hook, and removes suspend-then-hibernate configuration.
+# omarchy:summary=Remove hibernation setup including swap and boot resume settings
+# omarchy:requires-sudo=true
 
 MKINITCPIO_CONF="/etc/mkinitcpio.conf.d/omarchy_resume.conf"
 

bin/omarchy-hibernation-setup

@@ -1,7 +1,7 @@
 #!/bin/bash
 
-# Creates a swap file in the btrfs subvolume, adds the swap file to /etc/fstab,
-# adds a resume hook to mkinitcpio, and configures suspend-then-hibernate.
+# omarchy:summary=Set up hibernation with swap and boot resume configuration
+# omarchy:requires-sudo=true
 
 if [[ ! -f /sys/power/image_size ]]; then
   echo -e "Hibernation is not supported on your system" >&2

bin/omarchy-hook

@@ -1,6 +1,7 @@
 #!/bin/bash
 
-# Run a named hook, like post-update (available in ~/.config/omarchy/hooks/post-update).
+# omarchy:summary=Run a named hook, like post-update (available in ~/.config/omarchy/hooks/post-update).
+# omarchy:args=[name] [args...]
 
 set -e
 

bin/omarchy-hw-asus-expertbook-b9406

@@ -0,0 +1,5 @@
+#!/bin/bash
+
+# omarchy:summary=Detect ASUS ExpertBook B9406 series laptops on Intel Panther Lake.
+
+omarchy-hw-match "B9406" && omarchy-hw-intel-ptl

bin/omarchy-hw-asus-rog

@@ -1,6 +1,6 @@
 #!/bin/bash
 
-# Detect whether the computer is an Asus ROG machine.
+# omarchy:summary=Detect whether the computer is an Asus ROG machine.
 
 [[ $(cat /sys/class/dmi/id/sys_vendor 2>/dev/null) == "ASUSTeK COMPUTER INC." ]] &&
    grep -q "ROG" /sys/class/dmi/id/product_family 2>/dev/null

bin/omarchy-hw-dell-xps-oled

@@ -1,6 +1,6 @@
 #!/bin/bash
 
-# Match Dell XPS systems with LG OLED panel on Intel Panther Lake (Xe3) GPU.
+# omarchy:summary=Match Dell XPS systems with LG OLED panel on Intel Panther Lake (Xe3) GPU.
 
 omarchy-hw-match "XPS" \
   && omarchy-hw-intel-ptl \

bin/omarchy-hw-external-monitors

@@ -1,7 +1,6 @@
 #!/bin/bash
 
-# Returns true when an external monitor is physically connected.
-# Uses kernel DRM state so the result is independent of Hyprland's startup timing.
+# omarchy:summary=Returns true when an external monitor is physically connected.
 
 for status in /sys/class/drm/card*-*/status; do
   [[ "$status" == *-eDP-*/status ]] && continue

bin/omarchy-hw-framework16

@@ -1,6 +1,6 @@
 #!/bin/bash
 
-# Detect whether the computer is a Framework Laptop 16.
+# omarchy:summary=Detect whether the computer is a Framework Laptop 16.
 
 [[ $(cat /sys/class/dmi/id/sys_vendor 2>/dev/null) == "Framework" ]] &&
   omarchy-hw-match "Laptop 16"

bin/omarchy-hw-hybrid-gpu

@@ -1,3 +1,9 @@
 #!/bin/bash
 
-(($(lspci | grep -cE 'VGA|3D|Display') >= 2))
+# omarchy:summary=Detect whether the system has an active hybrid GPU configuration
+
+if command -v supergfxctl &>/dev/null; then
+  supergfxctl -s 2>/dev/null | grep -qw Hybrid
+else
+  (($(lspci | grep -cE 'VGA|3D|Display') >= 2))
+fi

bin/omarchy-hw-intel

@@ -1,5 +1,5 @@
 #!/bin/bash
 
-# Detect whether the computer has an Intel CPU.
+# omarchy:summary=Detect whether the computer has an Intel CPU.
 
 [[ $(grep -m1 "vendor_id" /proc/cpuinfo 2>/dev/null | cut -d: -f2 | tr -d ' ') == "GenuineIntel" ]]

bin/omarchy-hw-intel-ptl

@@ -1,5 +1,5 @@
 #!/bin/bash
 
-# Detect whether the computer has an Intel Panther Lake GPU.
+# omarchy:summary=Detect whether the computer has an Intel Panther Lake GPU.
 
 lspci | grep -iE 'vga|3d|display' | grep -qi 'panther lake'

bin/omarchy-hw-match

@@ -1,7 +1,7 @@
 #!/bin/bash
 
-# Match against the computer's DMI product name or product family (case-insensitive).
-# Usage: omarchy-hw-match "XPS" or omarchy-hw-match "ThinkPad"
+# omarchy:summary=Match against the computer's DMI product name or product family (case-insensitive).
+# omarchy:args=<pattern>
 
 grep -qi "$1" /sys/class/dmi/id/product_name 2>/dev/null ||
 grep -qi "$1" /sys/class/dmi/id/product_family 2>/dev/null

bin/omarchy-hw-recover-internal-monitor

@@ -1,8 +1,6 @@
 #!/bin/bash
 
-# Clear the internal-monitor-disable toggle if no external display is connected.
-# Runs before the graphical session so Hyprland doesn't block on having no output
-# to render to when the user rebooted with the external unplugged.
+# omarchy:summary=Clear the internal-monitor-disable toggle if no external display is connected.
 
 TOGGLE="$HOME/.local/state/omarchy/toggles/hypr/internal-monitor-disable.conf"
 

bin/omarchy-hw-surface

@@ -1,6 +1,6 @@
 #!/bin/bash
 
-# Detect whether the computer is a Microsoft Surface device.
+# omarchy:summary=Detect whether the computer is a Microsoft Surface device.
 
 [[ $(cat /sys/class/dmi/id/sys_vendor 2>/dev/null) == "Microsoft Corporation" ]] &&
   omarchy-hw-match "Surface"

bin/omarchy-hw-touchpad

@@ -1,4 +1,6 @@
 #!/bin/bash
 
+# omarchy:summary=Print the detected Hyprland touchpad or trackpad device name
+
 device=$(hyprctl devices -j | jq -r '[.mice[] | .name | select(test("touchpad|trackpad"; "i"))] | first // empty')
 [[ -n $device ]] && echo "$device"

bin/omarchy-hw-touchscreen

@@ -0,0 +1,6 @@
+#!/bin/bash
+
+# omarchy:summary=Print the detected Hyprland touchscreen or tablet device name
+
+device=$(hyprctl devices -j | jq -r '[.touch[]?.name, .tablets[]?.name] | first // empty')
+[[ -n $device ]] && echo "$device"

bin/omarchy-hw-vulkan

@@ -1,6 +1,6 @@
 #!/bin/bash
 
-# Detect whether Vulkan is available.
+# omarchy:summary=Detect whether Vulkan is available.
 
 [[ -d /usr/share/vulkan/icd.d ]] &&
   find /usr/share/vulkan/icd.d -maxdepth 1 -name "*.json" -print -quit | grep -q .

bin/omarchy-hyprland-active-window-transparency-toggle

@@ -1,5 +1,5 @@
 #!/bin/bash
 
-# Toggles transparency for the currently focused window.
+# omarchy:summary=Toggles transparency for the currently focused window.
 
 hyprctl dispatch setprop "address:$(hyprctl activewindow -j | jq -r '.address')" opaque toggle

bin/omarchy-hyprland-monitor-focused

@@ -1,5 +1,5 @@
 #!/bin/bash
 
-# Print the name of the currently focused Hyprland monitor.
+# omarchy:summary=Print the name of the currently focused Hyprland monitor.
 
 hyprctl monitors -j | jq -r '.[] | select(.focused == true).name'

bin/omarchy-hyprland-monitor-internal

@@ -1,6 +1,14 @@
 #!/bin/bash
 
+# omarchy:summary=Enable, disable, toggle, or recover the internal laptop display
+# omarchy:args=<on|off|toggle|recover>
+
 TOGGLE="internal-monitor-disable"
+TOGGLE_FLAG="$HOME/.local/state/omarchy/toggles/hypr/$TOGGLE.conf"
+MIRROR_TOGGLE="internal-monitor-mirror"
+
+# Get internal monitor name dynamically
+INTERNAL=$(hyprctl monitors -j | jq -r '.[] | select(.name | contains("eDP")).name' | head -n 1)
 
 enable() {
   if omarchy-hyprland-toggle-enabled "$TOGGLE"; then
@@ -9,14 +17,15 @@ enable() {
 }
 
 disable() {
-  if omarchy-hw-external-monitors; then
-    if omarchy-hyprland-toggle-disabled "$TOGGLE"; then
-      omarchy-hyprland-toggle --enabled-notification "󰍹    Laptop display disabled" "$TOGGLE"
-    fi
-  else
+  if ! omarchy-hw-external-monitors; then
     notify-send -u low "󰍹    Can't disable the only active display"
     exit 1
   fi
+  if omarchy-hyprland-toggle-disabled "$TOGGLE" && omarchy-hyprland-toggle-disabled "$MIRROR_TOGGLE"; then
+    echo "monitor=$INTERNAL,disable" >"$TOGGLE_FLAG"
+    notify-send -u low "󰍹    Laptop display disabled"
+    hyprctl reload
+  fi
 }
 
 recover() {

bin/omarchy-hyprland-monitor-internal-mirror

@@ -0,0 +1,58 @@
+#!/bin/bash
+
+# omarchy:summary=Enable, disable, toggle, or recover mirroring the internal display to an external monitor
+# omarchy:args=<on|off|toggle|recover>
+
+TOGGLE="internal-monitor-mirror"
+TOGGLE_FLAG="$HOME/.local/state/omarchy/toggles/hypr/$TOGGLE.conf"
+DISABLE_TOGGLE="internal-monitor-disable"
+
+# Get names dynamically
+INTERNAL=$(hyprctl monitors -j | jq -r '.[] | select(.name | contains("eDP")).name' | head -n 1)
+# Get the first available external monitor
+EXTERNAL=$(hyprctl monitors -j | jq -r '.[] | select(.name | contains("eDP") | not).name' | head -n 1)
+
+enable() {
+  if [[ -z "$EXTERNAL" ]]; then
+    notify-send -u low "󰍹    No external monitors found for mirror"
+    exit 1
+  fi
+
+  if [[ -z "$INTERNAL" ]]; then
+    notify-send -u low "󰍹    No laptop monitor found to mirror"
+    exit 1
+  fi
+
+  if omarchy-hyprland-toggle-enabled "$DISABLE_TOGGLE"; then
+    omarchy-hyprland-toggle "$DISABLE_TOGGLE"
+  fi
+
+  if omarchy-hyprland-toggle-disabled "$TOGGLE"; then
+    echo "monitor=$EXTERNAL, preferred, auto, 1, mirror, $INTERNAL" > "$TOGGLE_FLAG"
+    notify-send -u low "󰍹    Mirroring enabled ($EXTERNAL)"
+    hyprctl reload
+  fi
+}
+
+disable() {
+  if omarchy-hyprland-toggle-enabled "$TOGGLE"; then
+    omarchy-hyprland-toggle --disabled-notification "󰍹    Extended mode restored" "$TOGGLE"
+  fi
+}
+
+recover() {
+  if ! omarchy-hw-external-monitors && omarchy-hyprland-toggle-enabled "$TOGGLE"; then
+    omarchy-hyprland-toggle "$TOGGLE"
+  fi
+}
+
+case "$1" in
+  on) enable ;;
+  off) disable ;;
+  toggle) if omarchy-hyprland-toggle-enabled "$TOGGLE"; then disable; else enable; fi ;;
+  recover) recover ;;
+  *)
+    echo "Usage: $(basename "$0") {on|off|toggle|recover}" >&2
+    exit 1
+    ;;
+esac

bin/omarchy-hyprland-monitor-scaling-cycle

@@ -1,6 +1,7 @@
 #!/bin/bash
 
-# Get the active monitor (the one with the cursor)
+# omarchy:summary=Cycle scaling for the focused Hyprland monitor
+
 MONITOR_INFO=$(hyprctl monitors -j | jq -r '.[] | select(.focused == true)')
 ACTIVE_MONITOR=$(echo "$MONITOR_INFO" | jq -r '.name')
 CURRENT_SCALE=$(echo "$MONITOR_INFO" | jq -r '.scale')

bin/omarchy-hyprland-monitor-watch

@@ -1,7 +1,6 @@
 #!/bin/bash
 
-# Listen on Hyprland's event socket and recover the internal display whenever
-# a monitor is removed.
+# omarchy:summary=Watch Hyprland monitor events and recover monitor toggles when a monitor is removed
 
 SOCKET="$XDG_RUNTIME_DIR/hypr/$HYPRLAND_INSTANCE_SIGNATURE/.socket2.sock"
 
@@ -9,6 +8,7 @@ socat -U - "UNIX-CONNECT:$SOCKET" | while read -r event; do
   case "$event" in
     monitorremoved\>\>*|monitorremovedv2\>\>*)
       omarchy-hyprland-monitor-internal recover
+      omarchy-hyprland-monitor-internal-mirror recover
       ;;
   esac
 done

bin/omarchy-hyprland-toggle

@@ -1,6 +1,7 @@
 #!/bin/bash
 
-# Toggle permanent Hyprland flags by copying them into a directory that's sourced entirely.
+# omarchy:summary=Toggle permanent Hyprland flags by copying them into a directory that's sourced entirely.
+# omarchy:args=[--enabled-notification <text>] [--disabled-notification <text>] <flag-name>
 
 ENABLED_NOTIFICATION=""
 DISABLED_NOTIFICATION=""

bin/omarchy-hyprland-toggle-disabled

@@ -1,5 +1,6 @@
 #!/bin/bash
 
-# Check if a Hyprland toggle is currently disabled (missing).
+# omarchy:summary=Check if a Hyprland toggle is currently disabled (missing).
+# omarchy:args=<flag-name>
 
 [[ ! -f "$HOME/.local/state/omarchy/toggles/hypr/$1.conf" ]]

bin/omarchy-hyprland-toggle-enabled

@@ -1,5 +1,6 @@
 #!/bin/bash
 
-# Check if a Hyprland toggle is currently enabled.
+# omarchy:summary=Check if a Hyprland toggle is currently enabled.
+# omarchy:args=<flag-name>
 
 [[ -f "$HOME/.local/state/omarchy/toggles/hypr/$1.conf" ]]

bin/omarchy-hyprland-window-close-all

@@ -1,6 +1,7 @@
 #!/bin/bash
 
-# Close all open windows
+# omarchy:summary=Close all open windows
+
 hyprctl clients -j | \
   jq -r ".[].address" | \
   xargs -I{} hyprctl dispatch closewindow address:{}

bin/omarchy-hyprland-window-gaps-toggle

@@ -1,5 +1,5 @@
 #!/bin/bash
 
-# Toggles the window gaps globally between no gaps and the default.
+# omarchy:summary=Toggles the window gaps globally between no gaps and the default.
 
 omarchy-hyprland-toggle window-no-gaps

bin/omarchy-hyprland-window-pop

@@ -1,19 +1,7 @@
 #!/bin/bash
 
-# Toggle to pop-out a tile to stay fixed on a display basis.
-
-# Usage:
-# omarchy-hyprland-window-pop [width height [x y]]
-#
-# Arguments:
-#   width   Optional. Width of the floating window. Default: 1300
-#   height  Optional. Height of the floating window. Default: 900
-#   x       Optional. X position of the window. Must provide both X and Y to take effect.
-#   y       Optional. Y position of the window. Must provide both X and Y to take effect.
-#
-# Behavior:
-#   - If the window is already pinned, it will be unpinned and removed from the pop layer.
-#   - If the window is not pinned, it will be floated, resized, moved/centered, pinned, brought to top, and popped.
+# omarchy:summary=Toggle to pop-out a tile to stay fixed on a display basis.
+# omarchy:args=[width height x y]
 
 width=${1:-1300}
 height=${2:-900}

bin/omarchy-hyprland-window-single-square-aspect-toggle

@@ -1,6 +1,6 @@
 #!/bin/bash
 
-# Toggle single-window square aspect ratio.
+# omarchy:summary=Toggle single-window square aspect ratio.
 
 omarchy-hyprland-toggle \
   --enabled-notification "      Enable single-window square aspect ratio" \

bin/omarchy-hyprland-workspace-layout-toggle

@@ -1,6 +1,6 @@
 #!/bin/bash
 
-# Toggle the layout on the current active workspace between dwindle and scrolling
+# omarchy:summary=Toggle the layout on the current active workspace between dwindle and scrolling
 
 ACTIVE_WORKSPACE=$(hyprctl activeworkspace -j | jq -r '.id')
 CURRENT_LAYOUT=$(hyprctl activeworkspace -j | jq -r '.tiledLayout')

bin/omarchy-install-chromium-google-account

@@ -1,7 +1,6 @@
 #!/bin/bash
 
-# Allow Chromium to sign in to Google accounts by adding the correct
-# oauth client id and secret to ~/.config/chromium-flags.conf.
+# omarchy:summary=Allow Chromium to sign in to Google accounts by adding the required OAuth credentials
 
 if [[ -f ~/.config/chromium-flags.conf ]]; then
   CONF=~/.config/chromium-flags.conf

bin/omarchy-install-dev-env

@@ -1,6 +1,10 @@
 #!/bin/bash
 
-# Install one of the supported development environments. Usually called via Install > Development > * in the Omarchy Menu.
+# omarchy:summary=Install a supported development environment
+# omarchy:name=dev-env
+# omarchy:args=<ruby|node|bun|deno|go|laravel|symfony|php|python|elixir|phoenix|rust|java|zig|ocaml|dotnet|clojure|scala>
+# omarchy:examples=omarchy install dev-env ruby | omarchy install dev-env node
+# omarchy:requires-sudo=true
 
 if [[ -z $1 ]]; then
   echo "Usage: omarchy-install-dev-env <ruby|node|bun|deno|go|laravel|symfony|php|python|elixir|phoenix|rust|java|zig|ocaml|dotnet|clojure|scala>" >&2

bin/omarchy-install-docker-dbs

@@ -1,7 +1,7 @@
 #!/bin/bash
 
-# Install one of the supported databases in a Docker container with the suitable development options.
-# Usually called via Install > Development > Docker DB from the Omarchy Menu.
+# omarchy:summary=Install one of the supported databases in a Docker container with the suitable development options.
+# omarchy:requires-sudo=true
 
 options=("MySQL" "PostgreSQL" "Redis" "MongoDB" "MariaDB" "MSSQL")
 

bin/omarchy-install-dropbox

@@ -1,6 +1,6 @@
 #!/bin/bash
 
-# Install and start the Dropbox service. Must then be authenticated via the web.
+# omarchy:summary=Install and start the Dropbox service. Must then be authenticated via the web.
 
 echo "Installing all dependencies..."
 omarchy-pkg-add dropbox dropbox-cli libappindicator-gtk3 python-gpgme nautilus-dropbox

bin/omarchy-install-geforce-now

@@ -1,6 +1,6 @@
 #!/bin/bash
 
-# Install and launch Geforce Now.
+# omarchy:summary=Install and launch Geforce Now.
 
 set -e
 

bin/omarchy-install-nordvpn

@@ -1,6 +1,7 @@
 #!/bin/bash
 
-# Install the NordVPN service with optional GUI.
+# omarchy:summary=Install the NordVPN service with optional GUI.
+# omarchy:requires-sudo=true
 
 echo "Installing NordVPN..."
 omarchy-pkg-aur-add nordvpn-bin

bin/omarchy-install-once

@@ -1,6 +1,7 @@
 #!/bin/bash
 
-# Install the ONCE service, enable its background service, and launch the TUI.
+# omarchy:summary=Install the ONCE service, enable its background service, and launch the TUI.
+# omarchy:requires-sudo=true
 
 echo "Installing ONCE..."
 omarchy-pkg-add once-bin

bin/omarchy-install-steam

@@ -1,6 +1,7 @@
 #!/bin/bash
 
-# Install and launch Steam after first letting the user pick the correct grahics card drivers.
+# omarchy:summary=Install Steam and graphics drivers selected for this system
+# omarchy:requires-sudo=true
 
 set -e
 

bin/omarchy-install-tailscale

@@ -1,6 +1,7 @@
 #!/bin/bash
 
-# Install the Tailscale mesh VPN service and a web app for the Tailscale Admin Console.
+# omarchy:summary=Install the Tailscale mesh VPN service and a web app for the Tailscale Admin Console.
+# omarchy:requires-sudo=true
 
 echo -e "\nInstalling Tailscale..."
 omarchy-pkg-add tailscale

bin/omarchy-install-terminal

@@ -1,6 +1,8 @@
 #!/bin/bash
 
-# Install one of the approved terminals and set it as the default for Omarchy (Super + Return etc).
+# omarchy:summary=Install one of the approved terminals and set it as the default for Omarchy (Super + Return etc).
+# omarchy:args=<alacritty|ghostty|kitty>
+# omarchy:requires-sudo=true
 
 if (($# == 0)); then
   echo "Usage: omarchy-install-terminal [alacritty|ghostty|kitty]"

bin/omarchy-install-vscode

@@ -1,6 +1,6 @@
 #!/bin/bash
 
-# Install VSCode and configure it to use the gnome-libsecret password store, not to update automatically, and to use the current Omarchy theme.
+# omarchy:summary=Install VS Code and configure Omarchy defaults for secrets, updates, and theme
 
 echo "Installing VSCode..."
 omarchy-pkg-add visual-studio-code-bin

bin/omarchy-install-xbox-controllers

@@ -1,6 +1,7 @@
 #!/bin/bash
 
-# Install support for using Xbox controllers with Steam/RetroArch/etc.
+# omarchy:summary=Install support for using Xbox controllers with Steam/RetroArch/etc.
+# omarchy:requires-sudo=true
 
 set -e
 

bin/omarchy-launch-about

@@ -1,5 +1,5 @@
 #!/bin/bash
 
-# Launch the fastfetch TUI that gives information about the current system.
+# omarchy:summary=Launch the fastfetch TUI that gives information about the current system.
 
 exec omarchy-launch-or-focus-tui "bash -c 'fastfetch; read -n 1 -s'"

bin/omarchy-launch-audio

@@ -1,5 +1,5 @@
 #!/bin/bash
 
-# Launch the Omarchy audio controls TUI (provided by wiremix).
+# omarchy:summary=Launch the Omarchy audio controls TUI (provided by wiremix).
 
 omarchy-launch-or-focus-tui wiremix

bin/omarchy-launch-bluetooth

@@ -1,7 +1,6 @@
 #!/bin/bash
 
-# Launch the Omarchy bluetooth controls TUI (provided by bluetui).
-# Also attempts to unblock bluetooth service if rfkill had blocked it.
+# omarchy:summary=Launch the Omarchy bluetooth controls TUI (provided by bluetui).
 
 rfkill unblock bluetooth
 exec omarchy-launch-or-focus-tui bluetui

bin/omarchy-launch-browser

@@ -1,7 +1,7 @@
 #!/bin/bash
 
-# Launch the default browser as determined by xdg-settings.
-# Automatically converts --private into the correct flag for the given browser.
+# omarchy:summary=Launch the default browser as determined by xdg-settings.
+# omarchy:args=[url]
 
 default_browser=$(xdg-settings get default-web-browser)
 browser_exec=$(sed -n 's/^Exec=\([^ ]*\).*/\1/p' {~/.local,~/.nix-profile,/usr}/share/applications/$default_browser 2>/dev/null | head -1)

bin/omarchy-launch-editor

@@ -1,7 +1,7 @@
 #!/bin/bash
 
-# Launch the default editor as determined by $EDITOR (set via ~/.config/uwsm/default) (or nvim if missing).
-# Starts suitable editors in a terminal window and otherwise as a regular application.
+# omarchy:summary=Launch the default editor as determined by $EDITOR (set via ~/.config/uwsm/default) (or nvim if missing).
+# omarchy:args=<path>
 
 omarchy-cmd-present "$EDITOR" || EDITOR=nvim
 

bin/omarchy-launch-floating-terminal-with-presentation

@@ -1,7 +1,7 @@
 #!/bin/bash
 
-# Launch a floating terminal with the Omarchy logo presentation, then execute the command passed in, and finally end with the omarchy-show-done presentation.
-# Used by actions such as Update System.
+# omarchy:summary=Launch a floating terminal with the Omarchy presentation wrapper
+# omarchy:args=<command>
 
 cmd="$*"
 exec setsid uwsm-app -- xdg-terminal-exec --app-id=org.omarchy.terminal --title=Omarchy -e bash -c "omarchy-show-logo; $cmd; if (( \$? != 130 )); then omarchy-show-done; fi"

bin/omarchy-launch-or-focus

@@ -1,7 +1,7 @@
 #!/bin/bash
 
-# Launch or focus on a given command identified by the passed in window-pattern.
-# Use by some default bindings, like the one for Spotify, to ensure there is only one instance of the application open.
+# omarchy:summary=Launch an app or focus an existing window matching a pattern
+# omarchy:args=<window-pattern> <launch-command>
 
 if (($# == 0)); then
   echo "Usage: omarchy-launch-or-focus [window-pattern] [launch-command]"

bin/omarchy-launch-or-focus-tui

@@ -1,7 +1,7 @@
 #!/bin/bash
 
-# Launch or focus on a given TUI identified by the passed in as the command.
-# Use by commands like omarchy-launch-wifi to ensure there is only one wifi configuration screen open.
+# omarchy:summary=Launch a TUI or focus an existing terminal window for it
+# omarchy:args=<command> [args...]
 
 APP_ID="org.omarchy.$(basename "$1")"
 LAUNCH_COMMAND="omarchy-launch-tui $@"

bin/omarchy-launch-or-focus-webapp

@@ -1,7 +1,7 @@
 #!/bin/bash
 
-# Launch or focus on a given web app identified by the window-pattern.
-# Use by some default bindings, like the one for WhatsApp, to ensure there is only one instance of the application open.
+# omarchy:summary=Launch or focus on a given web app identified by the window-pattern.
+# omarchy:args=<window-pattern> <url-and-flags...>
 
 if (($# == 0)); then
   echo "Usage: omarchy-launch-or-focus-webapp [window-pattern] [url-and-flags...]"

bin/omarchy-launch-screensaver

@@ -1,8 +1,7 @@
 #!/bin/bash
 
-# Launch the Omarchy screensaver in the default terminal on the system with the correct font configuration.
+# omarchy:summary=Launch the Omarchy screensaver in the default terminal on the system with the correct font configuration.
 
-# Exit early if we don't have the tte show
 if ! command -v tte &>/dev/null; then
   exit 1
 fi
@@ -29,21 +28,21 @@ for m in $(hyprctl monitors -j | jq -r '.[] | .name'); do
     hyprctl dispatch exec -- \
       alacritty --class=org.omarchy.screensaver \
       --config-file ~/.local/share/omarchy/default/alacritty/screensaver.toml \
-      -e omarchy-cmd-screensaver
+      -e omarchy-screensaver
     ;;
   *ghostty*)
     hyprctl dispatch exec -- \
       ghostty --class=org.omarchy.screensaver \
       --config-file=~/.local/share/omarchy/default/ghostty/screensaver \
       --font-size=18 \
-      -e omarchy-cmd-screensaver
+      -e omarchy-screensaver
     ;;
   *kitty*)
     hyprctl dispatch exec -- \
       kitty --class=org.omarchy.screensaver \
       --override font_size=18 \
       --override window_padding_width=0 \
-      -e omarchy-cmd-screensaver
+      -e omarchy-screensaver
     ;;
   *)
     notify-send -u low "✋  Screensaver only runs in Alacritty, Ghostty, or Kitty"

bin/omarchy-launch-tui

@@ -1,5 +1,6 @@
 #!/bin/bash
 
-# Launch the TUI command passed in as an argument in the default terminal with an org.omarchy.COMMAND app id for styling.
+# omarchy:summary=Launch a TUI command in the default terminal with Omarchy styling
+# omarchy:args=<command> [args...]
 
 exec setsid uwsm-app -- xdg-terminal-exec --app-id=org.omarchy.$(basename $1) -e "$1" "${@:2}"

bin/omarchy-launch-walker

@@ -1,8 +1,7 @@
 #!/bin/bash
 
-# Launch the Walker application launcher while ensuring that it's data provider (called elephant) is running first.
+# omarchy:summary=Launch Walker and ensure its Elephant data provider is running
 
-# Ensure elephant is running before launching walker
 if ! pgrep -x elephant > /dev/null; then
   setsid uwsm-app -- elephant &
 fi

bin/omarchy-launch-webapp

@@ -1,6 +1,7 @@
 #!/bin/bash
 
-# Launch the passed in URL as a web app in the default browser (or chromium if the default doesn't support --app).
+# omarchy:summary=Launch a URL as a web app in the default supported browser
+# omarchy:args=<url>
 
 browser=$(xdg-settings get default-web-browser)
 

bin/omarchy-launch-wifi

@@ -1,7 +1,6 @@
 #!/bin/bash
 
-# Launch the Omarchy wifi controls (provided by the Impala TUI).
-# Attempts to unblock the wifi service first in case it should be been blocked.
+# omarchy:summary=Launch the Omarchy wifi controls (provided by the Impala TUI).
 
 rfkill unblock wifi
 omarchy-launch-or-focus-tui impala

bin/omarchy-menu

@@ -1,8 +1,6 @@
 #!/bin/bash
 
-# Launch the Omarchy Menu or takes a parameter to jump straight to a submenu.
-
-export PATH="$HOME/.local/share/omarchy/bin:$PATH"
+# omarchy:summary=Launch the Omarchy Menu or takes a parameter to jump straight to a submenu.
 
 # Set to true when going directly to a submenu, so we can exit directly
 BACK_TO_EXIT=false
@@ -106,7 +104,7 @@ show_trigger_menu() {
 
 show_capture_menu() {
   case $(menu "Capture" "  Screenshot\n  Screenrecord\n󰃉  Color") in
-  *Screenshot*) omarchy-cmd-screenshot ;;
+  *Screenshot*) omarchy-capture-screenshot ;;
   *Screenrecord*) show_screenrecord_menu ;;
   *Color*) pkill hyprpicker || hyprpicker -a ;;
   *) back_to show_trigger_menu ;;
@@ -141,18 +139,18 @@ show_webcam_select_menu() {
 }
 
 show_screenrecord_menu() {
-  omarchy-cmd-screenrecord --stop-recording && exit 0
+  omarchy-capture-screenrecording --stop-recording && exit 0
 
   case $(menu "Screenrecord" "  With no audio\n  With desktop audio\n  With desktop + microphone audio\n  With desktop + microphone audio + webcam") in
-  *"With no audio") omarchy-cmd-screenrecord ;;
-  *"With desktop audio") omarchy-cmd-screenrecord --with-desktop-audio ;;
-  *"With desktop + microphone audio") omarchy-cmd-screenrecord --with-desktop-audio --with-microphone-audio ;;
+  *"With no audio") omarchy-capture-screenrecording ;;
+  *"With desktop audio") omarchy-capture-screenrecording --with-desktop-audio ;;
+  *"With desktop + microphone audio") omarchy-capture-screenrecording --with-desktop-audio --with-microphone-audio ;;
   *"With desktop + microphone audio + webcam")
     local device=$(show_webcam_select_menu) || {
       back_to show_capture_menu
       return
     }
-    omarchy-cmd-screenrecord --with-desktop-audio --with-microphone-audio --with-webcam --webcam-device="$device"
+    omarchy-capture-screenrecording --with-desktop-audio --with-microphone-audio --with-webcam --webcam-device="$device"
     ;;
   *) back_to show_capture_menu ;;
   esac
@@ -160,15 +158,15 @@ show_screenrecord_menu() {
 
 show_share_menu() {
   case $(menu "Share" "  Clipboard\n  File \n  Folder") in
-  *Clipboard*) omarchy-cmd-share clipboard ;;
-  *File*) terminal bash -c "omarchy-cmd-share file" ;;
-  *Folder*) terminal bash -c "omarchy-cmd-share folder" ;;
+  *Clipboard*) omarchy-menu-share clipboard ;;
+  *File*) terminal bash -c "omarchy-menu-share file" ;;
+  *Folder*) terminal bash -c "omarchy-menu-share folder" ;;
   *) back_to show_trigger_menu ;;
   esac
 }
 
 show_toggle_menu() {
-  local options="󱄄  Screensaver\n󰔎  Nightlight\n󱫖  Idle Lock\n󰍜  Top Bar\n󱂬  Workspace Layout\n  Window Gaps\n  1-Window Ratio\n󰍹  Monitor Scaling\n"
+  local options="󱄄  Screensaver\n󰔎  Nightlight\n󱫖  Idle Lock\n󰍜  Top Bar\n󱂬  Workspace Layout\n  Window Gaps\n  1-Window Ratio\n󰍹  Monitor Scaling\n  Direct Boot\n󰟵  Passwordless Sudo"
 
   case $(menu "Toggle" "$options") in
   *Screensaver*) omarchy-toggle-screensaver ;;
@@ -179,12 +177,14 @@ show_toggle_menu() {
   *Ratio*) omarchy-hyprland-window-single-square-aspect-toggle ;;
   *Gaps*) omarchy-hyprland-window-gaps-toggle ;;
   *Scaling*) omarchy-hyprland-monitor-scaling-cycle ;;
+  *"Direct Boot"*) present_terminal omarchy-config-direct-boot ;;
+  *"Passwordless Sudo"*) present_terminal omarchy-sudo-passwordless ;;
   *) back_to show_trigger_menu ;;
   esac
 }
 
 show_hardware_menu() {
-  local options="󰛧  Laptop Display"
+  local options="󰛧  Laptop Display\n 󰍹  Mirror Display"
 
   if omarchy-hw-hybrid-gpu; then
     options="$options\n  Hybrid GPU"
@@ -194,17 +194,24 @@ show_hardware_menu() {
     options="$options\n󰟸  Touchpad"
   fi
 
+  if omarchy-hw-touchscreen; then
+    options="$options\n󰆽  Touchscreen"
+  fi
+
   case $(menu "Toggle" "$options") in
   *Laptop*) omarchy-hyprland-monitor-internal toggle ;;
+  *Mirror*) omarchy-hyprland-monitor-internal-mirror toggle;;
   *Touchpad*) omarchy-toggle-touchpad ;;
+  *Touchscreen*) omarchy-toggle-touchscreen ;;
   *"Hybrid GPU"*) present_terminal omarchy-toggle-hybrid-gpu ;;
   *) back_to show_trigger_menu ;;
   esac
 }
 
 show_style_menu() {
-  case $(menu "Style" "󰸌  Theme\n  Font\n  Background\n  Hyprland\n󱄄  Screensaver\n  About") in
+  case $(menu "Style" "󰸌  Theme\n󰟵  Unlock\n  Font\n  Background\n  Hyprland\n󱄄  Screensaver\n  About") in
   *Theme*) show_theme_menu ;;
+  *Unlock*) omarchy-launch-walker -m menus:omarchyunlocks --width 800 --minheight 400 ;;
   *Font*) show_font_menu ;;
   *Background*) show_background_menu ;;
   *Hyprland*) open_in_editor ~/.config/hypr/looknfeel.conf ;;
@@ -362,8 +369,8 @@ show_install_terminal_menu() {
 
 show_install_ai_menu() {
   ollama_pkg=$(
-    (command -v nvidia-smi &>/dev/null && echo ollama-cuda) ||
-      (command -v rocminfo &>/dev/null && echo ollama-rocm) ||
+    (omarchy-cmd-present nvidia-smi && echo ollama-cuda) ||
+      (omarchy-cmd-present rocminfo && echo ollama-rocm) ||
       echo ollama
   )
 
@@ -597,7 +604,7 @@ show_system_menu() {
 
   case $(menu "System" "$options") in
   *Screensaver*) omarchy-launch-screensaver force ;;
-  *Lock*) omarchy-lock-screen ;;
+  *Lock*) omarchy-system-lock ;;
   *Suspend*) systemctl suspend ;;
   *Hibernate*) systemctl hibernate ;;
   *Logout*) omarchy-system-logout ;;

bin/omarchy-menu-keybindings

@@ -1,6 +1,6 @@
 #!/bin/bash
 
-# Display Hyprland keybindings defined in your configuration using walker for an interactive search menu.
+# omarchy:summary=Display Hyprland keybindings defined in your configuration using walker for an interactive search menu.
 
 declare -A KEYCODE_SYM_MAP
 

bin/omarchy-menu-share

@@ -1,9 +1,13 @@
 #!/bin/bash
 
-# Share clipboard, file, or folder using LocalSend. Bound to Super + Ctrl + S by default.
+# omarchy:summary=Share clipboard, files, or folders with LocalSend
+# omarchy:group=share
+# omarchy:name=
+# omarchy:args=<clipboard|file|folder> [path...]
+# omarchy:examples=omarchy share clipboard | omarchy share file ~/Downloads/example.txt
 
 if (($# == 0)); then
-  echo "Usage: omarchy-cmd-share [clipboard|file|folder]"
+  echo "Usage: omarchy-menu-share [clipboard|file|folder]"
   exit 1
 fi