Overview of hyprctl
hyprctl is the official command-line control and IPC interface for Hyprland. It allows you to trigger compositor actions, query internal state in structured JSON, dynamically adjust appearance keywords at runtime, and build custom desktop scripts.
# Standard invocation
hyprctl [options] <command> [args]
# Output pure JSON for shell scripting
hyprctl -j <command>Dispatch Actions (Dispatches)
Dispatcher commands execute immediate actions in the compositor (such as focusing, moving, or resizing windows):
| Command & Arguments | Description | Example |
|---|---|---|
| hyprctl dispatch exec <app> | Launches any application inside the Hyprland context. | hyprctl dispatch exec alacritty |
| hyprctl dispatch killactive | Closes the currently focused active window immediately. | hyprctl dispatch killactive |
| hyprctl dispatch togglefloating | Toggles floating mode for the focused window. | hyprctl dispatch togglefloating |
| hyprctl dispatch workspace <id|name> | Switches the active monitor to specified workspace. | hyprctl dispatch workspace 3 |
| hyprctl dispatch movetoworkspace <id> | Moves the focused window to another workspace. | hyprctl dispatch movetoworkspace 2 |
| hyprctl dispatch resizeactive <dx> <dy> | Resizes the active floating or tiled window by pixel delta. | hyprctl dispatch resizeactive 20 0 |
| hyprctl notify <icon> <ms> <color> <msg> | Displays a desktop notification box directly through compositor. | hyprctl notify 1 3000 “rgb(41,156,69)” “Nitro Ready!” |
Querying State (hyprctl -j)
Query compositor internals in plain text or JSON format for parsing with jq or shell scripts:
| Query Command | JSON Flag | Description | Example |
|---|---|---|---|
| hyprctl monitors | -j | Lists connected displays, resolutions, refresh rates, and scale factors. | hyprctl monitors -j | jq ‘.[].name’ |
| hyprctl activewindow | -j | Outputs detailed properties (class, title, address, PID) of focused window. | hyprctl activewindow -j |
| hyprctl clients | -j | Lists all open windows across all workspaces with coordinates and geometry. | hyprctl clients -j | jq length |
| hyprctl workspaces | -j | Lists all active workspaces, monitor bindings, and tile count. | hyprctl workspaces -j |
| hyprctl version | - | Prints Hyprland version, commit hash, build flags, and compiler. | hyprctl version |
Runtime Keyword Modification
Use hyprctl keyword to adjust appearance, layout, or animations in memory without needing to restart Hyprland or edit files on disk:
| Keyword Variable | Value Format | Description | Example |
|---|---|---|---|
| general:gaps_in | <pixels> | Modifies inner gaps between tiled windows on the fly. | hyprctl keyword general:gaps_in 12 |
| general:gaps_out | <pixels> | Modifies outer gaps between screen edges and windows. | hyprctl keyword general:gaps_out 20 |
| decoration:blur:enabled | <true|false> | Enables or disables Kawase dual-filter background blur. | hyprctl keyword decoration:blur:enabled false |
| decoration:rounding | <radius> | Dynamically changes corner rounding radius. | hyprctl keyword decoration:rounding 16 |
| hyprctl reload | - | Re-parses and applies all configuration files immediately. | hyprctl reload |
IPC Event Socket Scripting
Hyprland exposes UNIX domain sockets under $XDG_RUNTIME_DIR/hypr/$HYPRLAND_INSTANCE_SIGNATURE/ for streaming compositor events in real time (e.g. workspace changes, window focus, monitor connect):
# Stream live events directly using socat
SOCKET="$XDG_RUNTIME_DIR/hypr/$HYPRLAND_INSTANCE_SIGNATURE/.socket2.sock"
socat -U - UNIX-CONNECT:"$SOCKET" | while read -r line; do
echo "Event received: $line"
done