Add documentation to Omarchy commands

bin/omarchy-battery-remaining

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

bin/omarchy-branch-set

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

bin/omarchy-channel-set

@@ -1,5 +1,18 @@
 #!/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.
+
 if (($# == 0)); then
   echo "Usage: omarchy-channel-set [stable|edge|dev]"
   exit 1

bin/omarchy-cmd-apple-display-brightness

@@ -1,5 +1,7 @@
 #!/bin/bash
 
+# Adjust the brightness on Apple Studio Displays and Apple XDR Displays using asdcontrol.
+
 if [[ $# -eq 0 ]]; then
   echo "Adjust Apple Display Brightness by passing +5000 or -5000 (or any range from 0-60000)"
 else

bin/omarchy-cmd-audio-switch

@@ -1,5 +1,7 @@
 #!/bin/bash
 
+# Switch between audio outputs while preserving the mute status. By default mapped to Super + Mute.
+
 focused_monitor="$(hyprctl monitors -j | jq -r '.[] | select(.focused == true).name')"
 
 sinks=$(pactl -f json list sinks | jq '[.[] | select((.ports | length == 0) or ([.ports[]? | .availability != "not available"] | any))]')

bin/omarchy-cmd-first-run

@@ -1,5 +1,7 @@
 #!/bin/bash
 
+# Finish the installation of Omarchy with items that can only be done after logging in.
+
 set -e
 
 FIRST_RUN_MODE=~/.local/state/omarchy/first-run.mode

bin/omarchy-cmd-missing

@@ -1,5 +1,7 @@
 #!/bin/bash
 
+# Returns true if any of the commands passed in as arguments are missing on the system.
+
 for cmd in "$@"; do
   if ! command -v "$cmd" &>/dev/null; then
     exit 0

bin/omarchy-cmd-present

@@ -1,5 +1,7 @@
 #!/bin/bash
 
+# Returns true if all the commands passed in as arguments exit on the system.
+
 for cmd in "$@"; do
   command -v "$cmd" &>/dev/null || exit 1
 done

bin/omarchy-cmd-reboot

@@ -1,5 +1,8 @@
 #!/bin/bash
 
+# Reboot command that first closes all application windows (thus giving them a chance to save state).
+# This is particularly helpful for applications like Chromium that otherwise won't shutdown cleanly.
+
 omarchy-state clear re*-required
 
 # Schedule the reboot to happen after closing windows (detached from terminal)

bin/omarchy-cmd-screenrecord

@@ -1,5 +1,8 @@
 #!/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.
+
 [[ -f ~/.config/user-dirs.dirs ]] && source ~/.config/user-dirs.dirs
 OUTPUT_DIR="${OMARCHY_SCREENRECORD_DIR:-${XDG_VIDEOS_DIR:-$HOME/Videos}}"
 

bin/omarchy-cmd-screensaver

@@ -1,5 +1,7 @@
 #!/bin/bash
 
+# Run the Omarchy screensaver using random effects from TTE.
+
 screensaver_in_focus() {
   hyprctl activewindow -j | jq -e '.class == "org.omarchy.screensaver"' >/dev/null 2>&1
 }

bin/omarchy-cmd-screenshot

@@ -1,5 +1,8 @@
 #!/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.
+
 [[ -f ~/.config/user-dirs.dirs ]] && source ~/.config/user-dirs.dirs
 OUTPUT_DIR="${OMARCHY_SCREENSHOT_DIR:-${XDG_PICTURES_DIR:-$HOME/Pictures}}"
 

bin/omarchy-cmd-share

@@ -1,5 +1,7 @@
 #!/bin/bash
 
+# Share clipboard, file, or folder using LocalSend. Bound to Super + Ctrl + S by default.
+
 if (($# == 0)); then
   echo "Usage: omarchy-cmd-share [clipboard|file|folder]"
   exit 1

bin/omarchy-cmd-shutdown

@@ -1,5 +1,8 @@
 #!/bin/bash
 
+# Shutdown command that first closes all application windows (thus giving them a chance to save state).
+# This is particularly helpful for applications like Chromium that otherwise won't shutdown cleanly.
+
 omarchy-state clear re*-required
 
 # Schedule the shutdown to happen after closing windows (detached from terminal)

bin/omarchy-cmd-terminal-cwd

@@ -1,5 +1,8 @@
 #!/bin/bash
 
+# Returns the current working directory of the active terminal window,
+# so a new terminal window can be started in the same directory.
+
 # 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-debug

@@ -1,5 +1,7 @@
 #!/bin/bash
 
+# Return exhaustive debugging information about the system to help diagnose problems.
+
 NO_SUDO=false
 PRINT_ONLY=false
 

bin/omarchy-dev-add-migration

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

bin/omarchy-drive-info

@@ -1,6 +1,7 @@
 #!/bin/bash
 
-# Drive, like /dev/nvme0, to display information about
+# Returns drive information about a given volumne, like /dev/nvme0, which is used by omarchy-drive-select.
+
 if (($# == 0)); then
   echo "Usage: omarchy-drive-info [/dev/drive]"
   exit 1

bin/omarchy-drive-select

@@ -1,6 +1,6 @@
 #!/bin/bash
 
-# Select a drive from a list with info that includes space and brand
+# 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,5 +1,7 @@
 #!/bin/bash
 
+# Set a new encryption password for a drive selected.
+
 encrypted_drives=$(blkid -t TYPE=crypto_LUKS -o device)
 
 if [[ -n $encrypted_drives ]]; then

bin/omarchy-font-current

@@ -1,3 +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.
+
 grep -oP 'font-family:\s*["'\'']?\K[^;"'\'']+' ~/.config/waybar/style.css | head -n1

bin/omarchy-font-list

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

bin/omarchy-font-set

@@ -1,8 +1,11 @@
 #!/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.
+
 font_name="$1"
 
-if [[ -n "$font_name" && "$font_name" != "CNCLD" ]]; then
+if [[ -n "$font_name" ]]; then
   if fc-list | grep -iq "$font_name"; then
     if [[ -f ~/.config/alacritty/alacritty.toml ]]; then
       sed -i "s/family = \".*\"/family = \"$font_name\"/g" ~/.config/alacritty/alacritty.toml

bin/omarchy-hook

@@ -1,5 +1,7 @@
 #!/bin/bash
 
+# Run a named hook, like post-update (available in ~/.config/omarchy/hooks/post-update).
+
 set -e
 
 if [[ $# -lt 1 ]]; then

bin/omarchy-hyprland-workspace-toggle-gaps

@@ -1,5 +1,7 @@
 #!/bin/bash
 
+# Toggles the window gaps on the active workspace between no gaps and the default 10/5/2.
+
 workspace_id=$(hyprctl activeworkspace -j | jq -r .id)
 gaps=$(hyprctl workspacerules -j | jq -r ".[] | select(.workspaceString==\"$workspace_id\") | .gapsOut[0] // 0")
 

bin/omarchy-install-chromium-google-account

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

bin/omarchy-install-dev-env

@@ -1,5 +1,7 @@
 #!/bin/bash
 
+# Install one of the supported development environments. Usually called via Install > Development > * in the Omarchy Menu.
+
 if [[ -z "$1" ]]; then
   echo "Usage: omarchy-install-dev-env <ruby|node|bun|go|laravel|symfony|php|python|elixir|phoenix|rust|java|ocaml|dotnet|clojure>" >&2
   exit 1

bin/omarchy-install-docker-dbs

@@ -1,5 +1,8 @@
 #!/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.
+
 options=("MySQL" "PostgreSQL" "Redis" "MongoDB" "MariaDB" "MSSQL")
 
 if [[ "$#" -eq 0 ]]; then

bin/omarchy-install-dropbox

@@ -1,5 +1,7 @@
 #!/bin/bash
 
+# 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-steam

@@ -1,5 +1,7 @@
 #!/bin/bash
 
+# Install and launch Steam after first letting the user pick the correct grahics card drivers.
+
 set -e
 
 echo "Now pick dependencies matching your graphics card"

bin/omarchy-install-tailscale

@@ -1,5 +1,7 @@
 #!/bin/bash
 
+# Install the Tailscale mesh VPN service, the tsui TUI management app, and a web app for the Tailscale Admin Console.
+
 curl -fsSL https://tailscale.com/install.sh | sh
 curl -fsSL https://neuralink.com/tsui/install.sh | bash
 

bin/omarchy-install-terminal

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

bin/omarchy-install-vscode

@@ -1,5 +1,7 @@
 #!/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.
+
 echo "Installing VSCode..."
 omarchy-pkg-add visual-studio-code-bin
 

bin/omarchy-install-xbox-controllers

@@ -1,5 +1,7 @@
 #!/bin/bash
 
+# Install support for using Xbox controllers with Steam/RetroArch/etc.
+
 set -e
 
 # Install xpadneo to ensure controllers work out of the box

bin/omarchy-launch-about

@@ -1,3 +1,5 @@
 #!/bin/bash
 
+# 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,3 +1,5 @@
 #!/bin/bash
 
+# Launch the Omarchy audio controls TUI (provided by wiremix).
+
 omarchy-launch-or-focus-tui wiremix

bin/omarchy-launch-bluetooth

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

bin/omarchy-launch-browser

@@ -1,5 +1,8 @@
 #!/bin/bash
 
+# Launch the default browser as determined by xdg-settings.
+# Automatically converts --private into the correct flag for the given browser.
+
 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,5 +1,8 @@
 #!/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-cmd-present "$EDITOR" || EDITOR=nvim
 
 case "$EDITOR" in

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

@@ -1,4 +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.
+
 cmd="$*"
 exec setsid uwsm-app -- xdg-terminal-exec --app-id=org.omarchy.terminal --title=Omarchy -e bash -c "omarchy-show-logo; $cmd; if [ \$? -ne 130 ]; then omarchy-show-done; fi"

bin/omarchy-launch-opencode

@@ -1,3 +1,5 @@
 #!/bin/bash
 
+# Launch opencode in a terminal that has first been placed in ~/Work.
+
 exec setsid uwsm-app -- xdg-terminal-exec --app-id=org.omarchy.opencode -e bash -c 'cd ~/Work; opencode'

bin/omarchy-launch-or-focus

@@ -1,5 +1,8 @@
 #!/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.
+
 if (($# == 0)); then
   echo "Usage: omarchy-launch-or-focus [window-pattern] [launch-command]"
   exit 1

bin/omarchy-launch-or-focus-tui

@@ -1,5 +1,8 @@
 #!/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.
+
 APP_ID="org.omarchy.$(basename "$1")"
 LAUNCH_COMMAND="omarchy-launch-tui $@"
 

bin/omarchy-launch-or-focus-webapp

@@ -1,5 +1,8 @@
 #!/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.
+
 if (($# == 0)); then
   echo "Usage: omarchy-launch-or-focus-webapp [window-pattern] [url-and-flags...]"
   exit 1
@@ -9,4 +12,4 @@ WINDOW_PATTERN="$1"
 shift
 LAUNCH_COMMAND="omarchy-launch-webapp $@"
 
-exec omarchy-launch-or-focus "$WINDOW_PATTERN" "$LAUNCH_COMMAND"
+exec omarchy-launch-or-focus "$WINDOW_PATTERN" "$LAUNCH_COMMAND"

bin/omarchy-launch-screensaver

@@ -1,5 +1,7 @@
 #!/bin/bash
 
+# 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

bin/omarchy-launch-tui

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

bin/omarchy-launch-walker

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

bin/omarchy-launch-webapp

@@ -1,5 +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).
+
 browser=$(xdg-settings get default-web-browser)
 
 case $browser in

bin/omarchy-launch-wifi

@@ -1,4 +1,7 @@
 #!/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.
+
 rfkill unblock wifi
 omarchy-launch-or-focus-tui impala

bin/omarchy-lock-screen

@@ -1,5 +1,7 @@
 #!/bin/bash
 
+# Locks the system using hyprlock, but not before ensuring 1password has also been locked, and the screensaver stopped.
+
 # Lock the screen
 pidof hyprlock || hyprlock &
 

bin/omarchy-menu

@@ -1,5 +1,7 @@
 #!/bin/bash
 
+# Launch the Omarchy Menu or takes a parameter to jump straight to a submenu.
+
 export PATH="$HOME/.local/share/omarchy/bin:$PATH"
 
 # Set to true when going directly to a submenu, so we can exit directly

bin/omarchy-menu-keybindings

@@ -1,7 +1,6 @@
 #!/bin/bash
 
-# A script to display Hyprland keybindings defined in your configuration
+# Display Hyprland keybindings defined in your configuration using walker for an interactive search menu.
-# using walker for an interactive search menu.
 
 declare -A KEYCODE_SYM_MAP
 

bin/omarchy-migrate

@@ -1,5 +1,7 @@
 #!/bin/bash
 
+# Run all pending migrations to bring the system in line with the installed version.
+
 # Where we store an empty file for each migration that has already been performed.
 STATE_DIR="$HOME/.local/state/omarchy/migrations"
 mkdir -p "$STATE_DIR"

bin/omarchy-notification-dismiss

@@ -1,5 +1,7 @@
 #!/bin/bash
 
+# Dismiss a mako notification on the basis of its summary. Used by the first-run notifications to dismiss them after clicking for action.
+
 if (($# == 0)); then
   echo "Usage: omarchy-notification-dismiss <summary>"
   exit 1

bin/omarchy-pkg-add

@@ -1,5 +1,7 @@
 #!/bin/bash
 
+# Add the named packages to the system if they're missing. Returns false if it couldn't be done.
+
 if omarchy-pkg-missing "$@"; then
   sudo pacman -S --noconfirm --needed "$@" || exit 1
 fi

bin/omarchy-pkg-aur-accessible

@@ -1,4 +1,7 @@
 #!/bin/bash
 
+# Returns true if the AUR is up and available.
+# Used by omarchy-update-system-pkgs to ensure the AUR is available before updating packages from it.
+
 curl -sf --connect-timeout 30 --retry 3 --retry-delay 3 -A "omarchy-update" \
   "https://aur.archlinux.org/rpc/?v=5&type=info&arg=base" >/dev/null

bin/omarchy-pkg-aur-install

@@ -1,5 +1,7 @@
 #!/bin/bash
 
+# Show a fuzzy-finder TUI for picking new AUR packages to install.
+
 fzf_args=(
   --multi
   --preview 'yay -Siia {1}'

bin/omarchy-pkg-drop

@@ -1,5 +1,7 @@
 #!/bin/bash
 
+# Remove all the named packages from the system if they're installed (otherwise ignore).
+
 for pkg in "$@"; do
   if pacman -Q "$pkg" &>/dev/null; then
     sudo pacman -Rns --noconfirm "$pkg"

bin/omarchy-pkg-install

@@ -1,5 +1,7 @@
 #!/bin/bash
 
+# Show a fuzzy-finder TUI for picking new Arch and OPR packages to install.
+
 fzf_args=(
   --multi
   --preview 'pacman -Sii {1}'

bin/omarchy-pkg-missing

@@ -1,5 +1,7 @@
 #!/bin/bash
 
+# Returns true if any of the named packages are missing from the system (or false if they're all there).
+
 for pkg in "$@"; do
   if ! pacman -Q "$pkg" &>/dev/null; then
     exit 0

bin/omarchy-pkg-present

@@ -1,5 +1,7 @@
 #!/bin/bash
 
+# Returns true if all of the named packages are installed on the system (or false if any of them are missing).
+
 for pkg in "$@"; do
   pacman -Q "$pkg" &>/dev/null || exit 1
 done

bin/omarchy-pkg-remove

@@ -1,5 +1,7 @@
 #!/bin/bash
 
+# Show a fuzzy-finder TUI for picking packages installed on the system to be removed.
+
 fzf_args=(
   --multi
   --preview 'yay -Qi {1}'

bin/omarchy-powerprofiles-list

@@ -1,5 +1,8 @@
 #!/bin/bash
 
+# Returns a list of all the available power profiles on the system.
+# Used by the Omarchy Menu under Setup > Power Profile.
+
 powerprofilesctl list |
   awk '/^\s*[* ]\s*[a-zA-Z0-9\-]+:$/ { gsub(/^[*[:space:]]+|:$/,""); print }' |
   tac

bin/omarchy-refresh-applications

@@ -1,5 +1,7 @@
 #!/bin/bash
 
+# Ensure all default .desktop, web apps, and TUIs are installed.
+
 # Copy and sync icon files
 mkdir -p ~/.local/share/icons/hicolor/48x48/apps/
 cp ~/.local/share/omarchy/applications/icons/*.png ~/.local/share/icons/hicolor/48x48/apps/
@@ -10,8 +12,9 @@ mkdir -p ~/.local/share/applications
 cp ~/.local/share/omarchy/applications/*.desktop ~/.local/share/applications/
 cp ~/.local/share/omarchy/applications/hidden/*.desktop ~/.local/share/applications/
 
-# Refresh the webapps
+# Refresh the webapps and TUIs
 bash $OMARCHY_PATH/install/packaging/icons.sh
 bash $OMARCHY_PATH/install/packaging/webapps.sh
+bash $OMARCHY_PATH/install/packaging/tuis.sh
 
 update-desktop-database ~/.local/share/applications

bin/omarchy-refresh-chromium

@@ -1,5 +1,7 @@
 #!/bin/bash
 
+# Refresh the ~/.config/chromium-flags.conf file from the Omarchy defaults.
+
 CONFIG_FILE="$HOME/.config/chromium-flags.conf"
 INSTALL_GOOGLE_ACCOUNTS=false
 

bin/omarchy-refresh-config

@@ -1,6 +1,8 @@
 #!/bin/bash
 
-# This script deploys ~/.local/share/omarchy/config/X/Y/Z -> ~/.config/X/Y/Z
+# Copies the named config from ~/.local/share/omarchy/config/X/Y/Z -> ~/.config/X/Y/Z.
+# If the config already exists, a backup of the existing will be taken as .bak.TIMESTAMP.
+
 config_file=$1
 
 if [[ -z "$config_file" ]]; then
@@ -9,8 +11,8 @@ if [[ -z "$config_file" ]]; then
 
   Must provide a file path from the .config directory to be refreshed.
   To copy ~/.local/share/omarchy/config/hypr/hyprlock.conf to ~/.config/hypr/hyprlock.conf
-    
+
-    $0 hypr/hyprlock.conf     
+    $0 hypr/hyprlock.conf
 USAGE
   exit 1
 fi

bin/omarchy-refresh-fastfetch

@@ -1,3 +1,5 @@
 #!/bin/bash
 
+# Overwrite the user config for fastfetch with the Omarchy default.
+
 omarchy-refresh-config fastfetch/config.jsonc

bin/omarchy-refresh-hypridle

@@ -1,4 +1,6 @@
 #!/bin/bash
 
+# Overwrite the user config for hypridle with the Omarchy default and restart the service.
+
 omarchy-refresh-config hypr/hypridle.conf
 omarchy-restart-hypridle

bin/omarchy-refresh-hyprland

@@ -1,5 +1,7 @@
 #!/bin/bash
 
+# Overwrite all the user configs in ~/.config/hypr with the Omarchy defaults.
+
 omarchy-refresh-config hypr/autostart.conf
 omarchy-refresh-config hypr/bindings.conf
 omarchy-refresh-config hypr/input.conf

bin/omarchy-refresh-hyprlock

@@ -1,3 +1,5 @@
 #!/bin/bash
 
+# Overwrite the user config for hyprlock with the Omarchy default.
+
 omarchy-refresh-config hypr/hyprlock.conf

bin/omarchy-refresh-hyprsunset

@@ -1,4 +1,6 @@
 #!/bin/bash
 
+# Overwrite the user config for hyprsunset with the Omarchy default and restart the service.
+#
 omarchy-refresh-config hypr/hyprsunset.conf
 omarchy-restart-hyprsunset

bin/omarchy-refresh-limine

@@ -1,5 +1,7 @@
 #!/bin/bash
 
+# Overwrite the user config for the Limine bootloader and rebuild it.
+
 if [[ -f /boot/EFI/Linux/omarchy_linux.efi ]] && [[ -f /boot/EFI/Linux/$(cat /etc/machine-id)_linux.efi ]]; then
   echo "Cleanup extra UKI"
   sudo rm -f /boot/EFI/Linux/$(cat /etc/machine-id)_linux.efi

bin/omarchy-refresh-pacman

@@ -1,5 +1,8 @@
 #!/bin/bash
 
+# Overwrite the package configuration for /etc/pacman with the Omarchy default of using its dedicated mirrors and repositories, then update all packages.
+# This is used after switching between Omarchy release channels to ensure the right packages for the right channel are available.
+
 # Take backup of existing files
 sudo cp -f /etc/pacman.conf /etc/pacman.conf.bak
 sudo cp -f /etc/pacman.d/mirrorlist /etc/pacman.d/mirrorlist.bak

bin/omarchy-refresh-plymouth

@@ -1,5 +1,7 @@
 #!/bin/bash
 
+# Overwrite the user config for the Plymouth drive decryption and boot sequence with the Omarchy default and rebuild it.
+
 sudo cp ~/.local/share/omarchy/default/plymouth/* /usr/share/plymouth/themes/omarchy/
 sudo plymouth-set-default-theme omarchy
 

bin/omarchy-refresh-swayosd

@@ -1,5 +1,7 @@
 #!/bin/bash
 
+# Overwrite the user configs for swayosd (controls on-screen feedback for changing volume/songs etc) with the Omarchy defaults and restart the service.
+
 omarchy-refresh-config swayosd/config.toml
 omarchy-refresh-config swayosd/style.css
 omarchy-restart-swayosd

bin/omarchy-refresh-walker

@@ -1,5 +1,7 @@
 #!/bin/bash
 
+# Overwrite the user configs for the Walker application launcher (which also powers the Omarchy Menu) and restart the services.
+
 # Ensure walker is set to autostart
 mkdir -p ~/.config/autostart/
 cp $OMARCHY_PATH/default/walker/walker.desktop ~/.config/autostart/

bin/omarchy-refresh-waybar

@@ -1,5 +1,7 @@
 #!/bin/bash
 
+# Overwrite the user configs for the Waybar menu bar with the Omarchy defaults and restart the service.
+
 omarchy-refresh-config waybar/config.jsonc
 omarchy-refresh-config waybar/style.css
 omarchy-restart-waybar

bin/omarchy-reinstall

@@ -1,5 +1,7 @@
 #!/bin/bash
 
+# Attempt to reinstall all default Omarchy packages and reset all the default configs.
+
 set -e
 
 if [ "$EUID" -eq 0 ]; then