Introduction

HyprL heavily relies on shell scripts to automate tasks, manage configurations, and provide a seamless user experience. Understanding where these scripts are located and how they function is key to customizing and extending your HyprL desktop. Most scripts are written in Bash, taking advantage of its power for system automation.

Script Locations

Scripts in HyprL are organized into several logical directories:

Hyprland Scripts (`~/.config/hypr/scripts/`)

This directory contains scripts directly related to Hyprland’s behavior, often executed via exec-once in autostart.conf or through keybindings.

xdg.sh: Sets up XDG desktop portals for screen sharing and desktop integration.
wallpaper.sh: Manages setting wallpapers using swww and integrates with color generation tools like matugen.
screenshot.sh: Provides advanced screenshot functionality (area selection, window capture, editing).
toggle-animations.sh: Toggles Hyprland animations on or off.
keybindings.sh: Displays a Rofi menu of all active keybindings.
cleanup.sh: A script for system cleanup tasks.

HyprL Management Scripts (`~/.config/hyprL/scripts/`)

These scripts are part of the HyprL management system, handling updates, shell switching, and other core functionalities.

installupdates.sh: A comprehensive script for updating system and AUR packages, and checking for HyprL updates.
shell.sh: An interactive script to switch between different shell configurations (bash, zsh, fish).

Top-Level Tools (`~/dotfiles/tools/`)

These are the main user-facing tools that provide interactive management and utility functions for the entire HyprL environment. They are often symlinked to ~/.local/bin/ for easy access from the terminal.

hyprL.sh: The central command-line interface for all HyprL operations (e.g., hyprL config, hyprL tutorial).
hyprL-config.sh: An interactive menu-driven tool for managing various HyprL settings like themes, monitors, and wallpapers.
first-time-tutorial.sh: The interactive tutorial for new users.
optimize-performance.sh: Automatically optimizes HyprL settings based on detected hardware.

Making Scripts Executable

For a script to run, it must have executable permissions. The HyprL installer automatically sets these, but if you create new scripts or encounter “Permission denied” errors, you can manually set them:

chmod +x /path/to/your/script.sh

To make all scripts in your HyprL configuration executable:

find ~/.config -name "*.sh" -exec chmod +x {} \;

Integrating Scripts with Keybindings

Many scripts are designed to be triggered by Hyprland keybindings. You can define these in your ~/.config/hypr/conf/keybindings/default.conf file using the exec dispatch command.

Example:

bind = $mainMod, Print, exec, ~/.config/hypr/scripts/screenshot.sh
bind = $mainMod SHIFT, A, exec, ~/.config/hypr/scripts/toggle-animations.sh

Common Scripting Examples

Wallpaper Management (`wallpaper.sh`)

This script handles setting your desktop background and integrating with color generation.

#!/bin/bash
if [ -z "$1" ]; then
    # Select random wallpaper from ~/.wallpaper/
    WALLPAPER=$(find ~/.wallpaper -type f \( -name "*.jpg" -o -name "*.png" -o -name "*.jpeg" \) | shuf -n 1)
else
    WALLPAPER="$1"
fi

if [ -f "$WALLPAPER" ]; then
    echo "Setting wallpaper: $WALLPAPER"
    swww img "$WALLPAPER" --transition-fps 60 --transition-type wipe --transition-duration 2
    
    # Generate colors with matugen
    matugen image "$WALLPAPER" --mode dark --type scheme-content
    
    # Reload waybar to apply new colors
    killall waybar
    sleep 1
    ~/.config/waybar/launch.sh &
else
    echo "Wallpaper not found: $WALLPAPER"
fi

Screenshot Utility (`screenshot.sh`)

A versatile script for capturing screenshots.

#!/bin/bash
# Screenshot script with multiple options

case "$1" in
    --area)
        # Select area and copy to clipboard
        grim -g "$(slurp)" - | wl-copy
        notify-send "Screenshot" "Area copied to clipboard"
        ;;
    --window)
        # Screenshot active window
        grim -g "$(hyprctl activewindow -j | jq -r '"\(.at[0]),\(.at[1]) \(.size[0])x\(.size[1])"')" - | wl-copy
        notify-send "Screenshot" "Window copied to clipboard"
        ;;
    --edit)
        # Screenshot area and open in editor
        grim -g "$(slurp)" /tmp/screenshot.png
        swappy -f /tmp/screenshot.png
        ;;
    *)
        # Full screen screenshot
        grim ~/Pictures/Screenshots/screenshot-$(date +%Y%m%d-%H%M%S).png
        notify-send "Screenshot" "Saved to ~/Pictures/Screenshots/"
        ;;
esac

Animation Toggle (`toggle-animations.sh`)

A simple script to switch animations on/off.

#!/bin/bash
# Toggles Hyprland animations on/off

ANIM_CONF="$HOME/.config/hypr/conf/animation.conf"

if grep -q "source = ~/.config/hypr/conf/animations/disabled.conf" "$ANIM_CONF"; then
    # Animations are currently disabled, enable them
    sed -i 's|source = ~/.config/hypr/conf/animations/disabled.conf|source = ~/.config/hypr/conf/animations/default.conf|' "$ANIM_CONF"
    notify-send "Animations" "Enabled"
else
    # Animations are currently enabled, disable them
    sed -i 's|source = ~/.config/hypr/conf/animations/.*.conf|source = ~/.config/hypr/conf/animations/disabled.conf|' "$ANIM_CONF"
    notify-send "Animations" "Disabled"
fi

hyprctl reload

HyprL Configuration Tool (`hyprL-config.sh`)

An example of an interactive menu-driven script.

#!/bin/bash
# HyprL Configuration Manager
# Interactive tool for managing HyprL settings

# ... (script content as read previously) ...

Shells and Scripting Languages

While most scripts in HyprL are written for bash or zsh (which is the default shell), you can use any scripting language supported by your system (e.g., Python, Perl) by ensuring the script has a proper shebang line (e.g., #!/usr/bin/python3) and executable permissions.

Table of Contents

Introduction

Script Locations

Hyprland Scripts (~/.config/hypr/scripts/)

HyprL Management Scripts (~/.config/hyprL/scripts/)

Top-Level Tools (~/dotfiles/tools/)