hyprctl

Reload Hyprland configuration

$ hyprctl reload

$ hyprctl activewindow

$ hyprctl devices

$ hyprctl workspaces

$ hyprctl dispatch [dispatcher]

$ hyprctl keyword [keyword] [value]

$ hyprctl version

hyprctl [arguments...]

dispatch
    Send a dispatch command to Hyprland for various actions (e.g., move window, switch workspace, execute a program).

setoption
    Set a Hyprland configuration option dynamically at runtime, overriding values in hyprland.conf.

getoption
    Retrieve the current value of a specific Hyprland configuration option.

setprop
    Set a property for a specific object, such as a window rule or a client.

getprop
    Retrieve a property for a specific object (e.g., a window's attribute).

reload
    Reload the Hyprland configuration file (hyprland.conf) without restarting the compositor.

kill
    Kill the currently active window or a specified client by its address.

workspaces
    List all active workspaces and their detailed properties (e.g., occupied, monitor, active state).

monitors
    List all connected monitors and their properties (e.g., resolution, position, active workspace).

clients
    List all active window clients and their detailed properties (e.g., title, class, address, fullscreen state).

activewindow
    Get detailed information about the currently focused window, including its class, title, and position.

version
    Display the current Hyprland and hyprctl application versions, along with build information.

help / commands
    Display a comprehensive list of all available hyprctl commands and their basic usage syntax.

hyprctl is the official command-line utility for Hyprland, a highly customizable dynamic tiling Wayland compositor. It provides a powerful interface to interact with and query the state of the running Hyprland session.

Users can use hyprctl to send commands for window management (e.g., moving windows, switching workspaces), configure settings on the fly, retrieve information about monitors, workspaces, and active clients, and even reload the Hyprland configuration without restarting. It's an essential tool for scripting custom behaviors, integrating Hyprland with other applications, and debugging. Its flexible command structure allows for granular control over various aspects of the compositor, making it a cornerstone for advanced Hyprland users and developers.

hyprctl requires the Hyprland Wayland compositor to be running for most commands to function, as it communicates with the active session.
The available commands, their arguments, and output formats are specific to the Hyprland version and may change between releases, requiring users to consult the official documentation for their installed version.
It is primarily intended for programmatic control, scripting, or advanced user configuration, rather than general interactive shell navigation.

Many hyprctl commands, particularly query commands like workspaces, monitors, and clients, output their results in JSON format. This structured output makes hyprctl highly scriptable and easy to parse with command-line JSON processors like jq, enabling powerful automation and custom workflows.

hyprctl communicates with the running Hyprland compositor instance via a Unix socket, typically located in the user's runtime directory (e.g., /tmp/hypr/<user_socket_id>/.socket.sock). This means that the command must generally be executed by the same user who is running the Hyprland session to have the necessary permissions to interact with it.

Hyprland, a dynamic tiling Wayland compositor, began its development in early 2022. hyprctl was introduced as its primary command-line interface from the project's early stages, evolving alongside the compositor to provide robust control and introspection capabilities. Its design reflects the modular and customizable nature of Hyprland, allowing users to script complex interactions and manage the environment without direct GUI interaction, becoming an integral part of the Hyprland ecosystem.

hyprland(1), wayland(7), swaymsg(1)