How to Use the Command 'hyprctl' (with Examples)

The hyprctl command is a powerful tool for users of the Hyprland Wayland compositor, which allows users to control different aspects of their window management and system configuration environments. By leveraging hyprctl, users can dynamically interact with their system’s settings and configurations, manipulate outputs and inputs, and retrieve useful information about the system’s state.

Reload Hyprland Configuration

Code:

hyprctl reload

Motivation: The “reload” command is essential when you have made changes to your Hyprland configuration file and want these changes to take effect immediately without restarting the entire session. This saves time and effort for users who are frequently customizing their environment, as it allows for instant application of new settings, aiding in quicker iterations and ensuring a smoother workflow.

Explanation:

• reload: The command reload reloads the current configuration, allowing any updates made to the configuration files to be applied instantly.

Example Output:

Hyprland configuration reloaded successfully.

Return the Active Window Name

Code:

hyprctl activewindow

Motivation: Knowing the active window can be useful for various reasons, such as scripting automated tasks that depend on contextual actions, developing productivity tools that log or manipulate window-specific data, or simply for personal curiosity regarding the system’s active state.

Explanation:

• activewindow: This argument asks hyprctl to fetch the title or identifier of the window currently in focus, providing insights into what the user is actively interacting with at any given moment.

Example Output:

Navigator - Mozilla Firefox

List All Connected Input Devices

Code:

hyprctl devices

Motivation: Listing input devices is crucial for troubleshooting peripheral connectivity issues, customizing input device settings, and developing or configuring input device-related applications. This command caters to users who need detailed information about all connected input hardware.

Explanation:

• devices: This command requests a list of all input devices connected to the system, detailing each device’s properties, such as name, type, and status.

Example Output:

Device: Logitech USB Optical Mouse
Type: Pointer
Status: Active

List All Outputs with Respective Properties

Code:

hyprctl workspaces

Motivation: For users managing multiple monitors or complex workspace layouts, understanding the configuration and status of each output is critical. This helps in optimizing screen layouts, managing display settings, and ensuring that all screens are utilized effectively.

Explanation:

• workspaces: This command provides a list of all output devices along with their properties, such as resolution, refresh rate, and position, aiding users in visualizing and managing their display setup.

Example Output:

Output: HDMI-A-1
Resolution: 1920x1080
Refresh Rate: 60Hz
Position: 0x0

Call a Dispatcher

Code:

hyprctl dispatch dispatcher

Motivation: Dispatchers in Hyprland are used to handle various system events or actions programmatically. This command is useful for developers and advanced users who are automating or scripting complex sequences of actions in response to system events, improving overall efficiency and customization of system behavior.

Explanation:

• dispatch: This argument follows with a specific dispatcher name, which executes a predefined action or event handler associated with that dispatcher, allowing users to trigger certain behaviors programmatically.

Example Output:

Dispatcher 'example_dispatcher' called successfully.

Set a Configuration Keyword Dynamically

Code:

hyprctl keyword keyword value

Motivation: Dynamically setting configuration keywords is invaluable for users who wish to experiment with fine-tuning system settings on-the-fly without permanently changing configuration files. This flexibility is particularly convenient for temporary adjustments and explorations.

Explanation:

• keyword: This represents the configuration keyword you wish to change.
• value: This is the new value assigned to the configuration keyword, effectively updating the system setting in real-time.

Example Output:

Keyword 'example_keyword' set to 'value' successfully.

Display Version

Code:

hyprctl version

Motivation: Knowing the software version is critical for debugging issues, ensuring compatibility with other software, and when seeking support or reporting bugs. This command helps users confirm the exact version of Hyprland they’re using.

Explanation:

• version: This command queries the current version of the Hyprland Wayland compositor installed, and provides it to the user.

Example Output:

Hyprland Version: 0.2.3 Build: 2023-02-15

Conclusion

The hyprctl command provides efficient and immediate access to managing the Hyprland environment, facilitating an enhanced experience for users who wish to optimize and customize their workflow dynamically. Whether it’s reconfiguring settings, querying system state, or automating tasks, hyprctl enables a wide range of capabilities that cater to both casual users and advanced developers.