Last Updated: 3/12/2026

hyprctl CLI

hyprctl is Hyprland’s command-line control tool. It communicates with the running Hyprland instance via IPC, allowing you to query state, execute commands, and automate workflows.

Basic Usage

hyprctl [command] [arguments]

All commands require a running Hyprland session. hyprctl connects to the active instance’s socket automatically.

Common Commands

Query System State

List active windows:

hyprctl clients

Returns JSON with window details: class, title, workspace, position, size, and more.

List workspaces:

hyprctl workspaces

Shows all workspaces with window counts and active status.

Get active window:

hyprctl activewindow

Returns details about the currently focused window.

Monitor information:

hyprctl monitors

Lists all connected monitors with resolution, refresh rate, and active workspace.

Current config values:

hyprctl getoption general:gaps_in
hyprctl getoption decoration:rounding

Query any config option by its path.

Execute Commands

Dispatch actions:

hyprctl dispatch exec kitty                    # Launch application
hyprctl dispatch workspace 3                   # Switch to workspace 3
hyprctl dispatch movetoworkspace 5             # Move active window to workspace 5
hyprctl dispatch togglefloating                # Toggle floating mode
hyprctl dispatch fullscreen                    # Toggle fullscreen
hyprctl dispatch killactive                    # Close active window

The dispatch subcommand executes any action available in keybindings.

Reload configuration:

hyprctl reload

Reloads ~/.config/hypr/hyprland.conf. Useful for testing config changes programmatically.

Set config options at runtime:

hyprctl keyword general:gaps_in 10
hyprctl keyword decoration:rounding 15

Changes take effect immediately but are not persisted to the config file.

Workspace Management

Create and switch to a workspace:

hyprctl dispatch workspace 5

Move window to workspace without switching:

hyprctl dispatch movetoworkspacesilent 3

Cycle through workspaces:

hyprctl dispatch workspace e+1   # Next workspace
hyprctl dispatch workspace e-1   # Previous workspace

Window Management

Move focus:

hyprctl dispatch movefocus l    # Left
hyprctl dispatch movefocus r    # Right
hyprctl dispatch movefocus u    # Up
hyprctl dispatch movefocus d    # Down

Move windows:

hyprctl dispatch movewindow l   # Move window left
hyprctl dispatch movewindow r   # Move window right

Resize windows:

hyprctl dispatch resizeactive 20 0     # Resize width +20px
hyprctl dispatch resizeactive 0 -20    # Resize height -20px

Plugin Management

List loaded plugins:

hyprctl plugin list

Load a plugin:

hyprctl plugin load /path/to/plugin.so

Unload a plugin:

hyprctl plugin unload plugin-name

Output Formats

By default, hyprctl returns human-readable output. For scripting, use JSON:

hyprctl clients -j
hyprctl workspaces -j
hyprctl monitors -j

Scripting Examples

Focus window by class

#!/bin/bash
# Focus the first Firefox window
hyprctl dispatch focuswindow "class:firefox"

Move all windows from workspace 1 to workspace 2

#!/bin/bash
for window in $(hyprctl clients -j | jq -r '.[] | select(.workspace.id == 1) | .address'); do
    hyprctl dispatch movetoworkspacesilent 2,address:$window
done

Toggle between two workspaces

#!/bin/bash
current=$(hyprctl activeworkspace -j | jq -r '.id')
if [ "$current" -eq 1 ]; then
    hyprctl dispatch workspace 2
else
    hyprctl dispatch workspace 1
fi

IPC Socket

hyprctl communicates via a Unix socket. The socket path is:

/tmp/hypr/$HYPRLAND_INSTANCE_SIGNATURE/.socket.sock

You can interact with the socket directly using tools like socat or nc for advanced use cases.

Batch Commands

Execute multiple commands in sequence:

hyprctl --batch "dispatch workspace 3; dispatch exec kitty; dispatch togglefloating"

Commands are separated by semicolons.

Debugging and Inspection

Get Hyprland version:

hyprctl version

List all available dispatch commands:

hyprctl dispatch -- --help

Get full system info:

hyprctl systeminfo

Returns detailed information about Hyprland’s build, dependencies, and runtime environment.

Common Use Cases

1. Automate window placement: Use hyprctl in startup scripts to position windows
2. Dynamic workspace switching: Build custom workspace switchers
3. Monitor configuration: Query monitor state and adjust layouts
4. Plugin development: Test plugin behavior interactively
5. Config testing: Apply temporary config changes without editing files

Tips

• Use -j for JSON output in scripts
• Combine with jq for powerful JSON parsing
• Test dispatch commands interactively before adding them to keybindings
• Check hyprctl --help for the full command list

What’s Next

• Window Rules: Automatically control window behavior with rules