hyprctl

Reload Hyprland configuration

$ hyprctl reload

$ hyprctl activewindow

$ hyprctl devices

$ hyprctl workspaces

$ hyprctl dispatch [dispatcher]

$ hyprctl keyword [keyword] [value]

$ hyprctl version

hyprctl [SUBCOMMAND] [ARGUMENTS]...

monitors [-j|--json]
    List all monitors with geometry, scale, active workspace, etc.
-j: JSON output.

workspaces [-j|--json]
    List all workspaces, including lastused, monitor, windows count.
-j: JSON.

clients [-j|--json]
    List all client windows with PID, class, title, workspace.
-j: JSON.

activewindow [-j|--json]
    Print info on the currently focused window.
-j: JSON.

dispatch [params] [--batch]
    Send dispatcher commands (e.g., exec, workspace, movetoworkspace).
--batch: Multiple dispatches from stdin/file.

keyword [value]
    Set a config keyword live (e.g., general:gaps_in=5).

notify [title] [text] [time(ms)] [bg-color] [border-color] [border-size(px)] [font] [icon-path]
    Display an on-screen notification.

version
    Print Hyprland version.

cursorpos [-w]
    Print absolute cursor position.
-w: Relative to focused workspace.

splash
    Toggle splash text rendering.

reload
    Reload Hyprland configuration.

getsoption
    Get value of a layout-specific option.

getoption
    Get value of a config keyword.

devices [-j|--json]
    List input devices.
-j: JSON.

device [-j|--json]
    Get details for specific input device.
-j: JSON.

listspecialworkspace [-j|--json]
    List clients in special workspace.
-j: JSON.

getspecialworkspace [-i]
    Get ID of special workspace client.
-i: All IDs.

listrules [-a]
    List window rules.
-a: All active rules.

help []
    Show usage help.

hyprctl is the command-line interface (CLI) tool for Hyprland, a highly customizable, dynamic tiling Wayland compositor for Linux. It enables users to query the current session state, dispatch runtime actions, modify live configuration, and manage notifications via IPC (Inter-Process Communication) over a Unix socket.

Key uses include listing monitors, workspaces, and clients; switching workspaces or moving windows; executing programs; toggling layouts; and scripting desktop behaviors. Outputs are human-readable by default but support JSON mode (-j) for easy parsing in scripts, making it ideal for status bars (e.g., Waybar), keybind integrations, or automation.

For example, hyprctl monitors shows display info, while hyprctl dispatch exec firefox launches an app. It requires Hyprland to be running and accesses the socket at $XDG_RUNTIME_DIR/hypr/$HYPRLAND_INSTANCE_SIGNATURE/.socket2.sock. hyprctl is lightweight, fast, and essential for power users scripting their Wayland environment.

Requires running Hyprland instance and socket access.
JSON output recommended for scripting; human-readable may change.
Not all dispatchers listed—use hyprctl dispatch or docs for full list.

Run multiple: hyprctl dispatch --batch "exec kitty; workspace 2; movetoworkspace 1"
Or pipe: echo 'exec code; togglefloating' | hyprctl dispatch --batch

Use jq: hyprctl monitors -j | jq '.[0].focused' for first monitor focus state.

exec/appopen, killactive, workspace <num>, movetoworkspace <num> [<addr>], togglefloating/fullscreen, layoutmsg, exit. Full list: Hyprland docs or hyprctl dispatch.

Developed by vaxry as part of Hyprland (formerly hyprwm), first released in October 2022 with v0.1.0. Evolved rapidly from i3/Sway inspiration, adding unique features like animations and gestures. hyprctl IPC mirrors swaymsg but optimized for Hyprland's renderer and plugins. Now at v0.40+ (2024), with community-driven expansions.

hyprland(1), swaymsg(1), i3-msg(1)