What Are the Most Common Hyprland Commands? A Complete hyprctl Reference

The most common Hyprland commands are dispatch, keyword, reload, kill, monitors, workspaces, and clients, all accessed via the hyprctl CLI utility that queries and controls the Wayland compositor at runtime.

Hyprland is a dynamic tiling Wayland compositor that exposes runtime control through the hyprctl command-line tool. Understanding these commands allows you to manage windows, modify configuration on-the-fly, and query system state without restarting your session.

Control and Execution Commands

dispatch

The dispatch command calls internal dispatchers to perform actions like opening applications or moving windows. According to hyprctl/src/main.cpp, this is the primary mechanism for triggering compositor actions programmatically.

# Run a dispatcher – open a terminal

hyprctl dispatch "hl.dsp.exec_cmd('alacritty')"

kill

The kill command enters kill-mode, allowing you to click any window to close it immediately. This provides a mouse-based alternative to keyboard shortcuts for terminating unresponsive applications.

# Enter kill-mode to click-close a window

hyprctl kill

Configuration Management Commands

keyword

Change configuration keywords dynamically without editing the config file. This modifies values like border sizes or gaps in real-time, as documented in docs/hyprctl.1.rst.

# Change a config keyword (border size) on the fly

hyprctl keyword general:border_size 5

reload

Forces an immediate reload of the configuration file. This picks up changes made to static config files and applies them to the current session.

# Reload the config after editing it

hyprctl reload

eval

Executes arbitrary Lua code when using a Lua-based configuration provider. This enables advanced scripting capabilities through the interface defined in src/config/lua/bindings/LuaBindingsDispatchers.cpp.

# Evaluate Lua directly (e.g., bind a shortcut)

hyprctl eval 'hl.bind("SUPER+SHIFT+Q", hl.dsp.exec_cmd("firefox"))'

State Query Commands

version

Prints detailed build information including version, commit hash, branch, and build flags. This is useful for bug reporting and verifying installation integrity.

# Show version / build info

hyprctl version

monitors

Lists all connected outputs with their properties, resolutions, and positions. This command queries the compositor's internal monitor state.

# List monitors and their properties

hyprctl monitors

workspaces

Displays all workspaces and their current attributes, including which monitors they reside on and whether they contain windows.

# List workspaces and their attributes

hyprctl workspaces

clients

Lists all window clients with their titles, classes, workspace assignments, and geometry. The output includes every open window managed by the compositor.

# List all client windows

hyprctl clients

devices

Shows all recognized input devices, including keyboards, mice, and touchpads, along with their internal identifiers.

activewindow

Returns the title of the currently focused window. This is commonly used in status bars or scripts that need to display the active application name.

# Get the title of the active window

hyprctl activewindow

layers

Lists all Wayland layer surfaces such as panels, notification centers, and overlays. These are managed separately from regular application windows.

splash

Displays the current random splash message shown during compositor startup.

status

Prints internal status information including config format, backend type, and other runtime diagnostics.

Implementation Details

The command parsing logic resides in hyprctl/src/main.cpp, which handles argument processing and client-side communication. The IPC implementation on the compositor side is located in src/ipc/s1/Commands.cpp, which processes requests from hyprctl and executes the corresponding internal functions.

Summary

• Use hyprctl dispatch to execute window management actions and launch applications.
• Modify runtime configuration with hyprctl keyword without restarting.
• Query system geometry using hyprctl monitors, workspaces, and clients.
• Reload static configuration changes using hyprctl reload.
• Access advanced Lua scripting capabilities through hyprctl eval.

Frequently Asked Questions

What is the difference between hyprctl dispatch and keyword?

The dispatch command triggers actions like opening windows or changing layouts, while the keyword command modifies configuration values dynamically. Dispatchers perform operations, whereas keywords adjust settings that affect how the compositor behaves.

How do I reload my Hyprland configuration without logging out?

Run hyprctl reload from any terminal or bind it to a key combination in your configuration. This forces the compositor to re-parse its configuration file and apply changes immediately without terminating your session.

Can I use hyprctl commands in shell scripts?

Yes, hyprctl is designed for scripting. Commands like hyprctl activewindow or hyprctl workspaces return parseable text that you can use in shell pipelines, while hyprctl dispatch allows scripts to control window focus and application launching programmatically.

Where are hyprctl commands defined in the source code?

Command definitions are split between hyprctl/src/main.cpp for client-side parsing and src/ipc/s1/Commands.cpp for server-side IPC handling. The Lua integration for the eval command is implemented in src/config/lua/bindings/LuaBindingsDispatchers.cpp.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}