Using hyprctl

hyprctl is a utility for controlling some parts of the compositor from a CLI or a script. It is automatically installed as part of Hyprland.

Commands

eval

Issue a Lua string to execute dynamically, returns “ok” or any error raised.

hyprctl eval 'hl.dispatch(hl.dsp.focus({ workspace = "3" }))'

repl

Start an interactive Lua REPL session, or issue a Lua string and print the result through tostring(). Similar to lua interactive mode. Exit with Ctrl+D.

Usage:

hyprctl repl        # start REPL session
hyprctl repl [code] # execute code and print the result

Examples:

$ hyprctl repl 'hl.get_active_window().class'
foot

$ hyprctl repl
> for i,w in pairs(hl.get_windows()) do print(i, w.class) end
1       foot
2       firefox
3       codium
> hl.notification.create({ text = "Hello World", timeout = 2000})
HL.Notification(0x563c0a1ebe70)

dispatch

Dispatch is a shorthand for eval 'hl.dispatch(...)':

hyprctl dispatch 'hl.dsp.focus({ workspace = "3" })'

See Dispatchers for a list of dispatchers.

reload

Issue a reload to force reload the config. reload full-reset will recreate the entire config context, allowing switching to/from Lua/hyprlang. full-reset should not be used unless really necessary.

kill

Issue a kill to get into a kill mode, where you can kill an app by clicking on it. You can exit it with ESCAPE.

Kind of like xkill.

setcursor

Sets the cursor theme and reloads the cursor manager. Will set the theme for everything except GTK, because GTK.

Please note that since 0.37.0, this only accepts hyprcursor themes. For legacy XCursor themes, use the XCURSOR_THEME and XCURSOR_SIZE env vars.

params: theme and size

For example:

hyprctl setcursor Bibata-Modern-Classic 24

output

Allows you to add and remove fake outputs to your preferred backend.

Usage:

hyprctl output create [backend] (name)
# or
hyprctl output remove [name]

Where [backend] is the name of the backend and (name) is an optional name for the output. If (name) is not specified, the default naming scheme will be used (HEADLESS-2, WL-1, etc.).

Available backends:

• wayland: Creates an output as a Wayland window. This will only work if you’re already running Hyprland with the Wayland backend, i.e. as a nested session.
• headless: Creates a headless monitor output. If you’re running a VNC/RDP/Sunshine server, you should use this.
• auto: Picks a backend for you. For example, if you’re running Hyprland from the TTY, headless will be chosen.

For example, to create a headless output named “test”:

hyprctl output create headless test

And to remove it:

hyprctl output remove test

switchxkblayout

Sets the XKB layout index for a keyboard.

For example, if you set:

hl.device({
  name = "my-epic-keyboard-v1",
  kb_layout = "us,pl,de"
})

You can use this command to switch between them.

hyprctl switchxkblayout <DEVICE> <CMD>

where CMD is either next for next, prev for previous, or ID for a specific one (in the above case, us: 0, pl: 1, de: 2). You can find the DEVICE using hyprctl devices command.

DEVICE can also be current or all, self-explanatory. Current is the main keyboard from devices.

Example command for a typical keyboard:

hyprctl switchxkblayout at-translated-set-2-keyboard next

hl.config({
  input = {
    kb_layout = "pl,us,ru",
     kb_variant = "dvorak,,",
     kb_options = "caps:ctrl_modifier"
  }
})

seterror

Sets the hyprctl error string. Will reset when Hyprland’s config is reloaded.

hyprctl seterror 'rgba(66ee66ff)' hello world this is my problem

To disable:

hyprctl seterror disable

getprop

Gets a property value of a window.

hyprctl getprop <window> <property>

Where window is as described here, and property is any which can be set with set_prop.

Note that:

• If animationstyle is unset, (unset) is returned.
• min_size defaults to 20 20.
• max_size defaults to inf inf or [null,null] in JSON.

notify

Sends a notification using the built-in Hyprland notification system. Read more about it here, especially for icon and color options.

hyprctl notify <ICON> <TIME_MS> <COLOR> <MESSAGE>

To specify font size, add fonstsize:<SIZE = int>

hyprctl notify -1 10000 "rgb(ff1ea3)" "Hello everyone!"
hyprctl notify -1 10000 "rgb(ff0000)" "fontsize:35 This text is big"

hyprctl dismissnotify    # dismiss all notifications
hyprctl dismissnotify -1 # dismiss all notifications (same as no arguments)
hyprctl dismissnotify 2  # dismiss the oldest 2 notifications

Usage

version              - prints the Hyprland version along with flags, commit and branch of build.
monitors             - lists active outputs with their properties, 'monitors all' lists active and inactive outputs
workspaces           - lists all workspaces with their properties
activeworkspace      - gets the active workspace and its properties
workspacerules       - gets the list of defined workspace rules
clients              - lists all windows with their properties
devices              - lists all connected keyboards and mice
decorations [window] - lists all decorations and their info
binds                - lists all registered binds
activewindow         - gets the active window name and its properties
layers               - lists all the layers
splash               - prints the current random splash
getoption [option]   - gets the config option status (values)
cursorpos            - gets the current cursor position in global layout coordinates
animations           - gets the currently configured info about animations and beziers
instances            - lists all running instances of Hyprland with their info
layouts              - lists all layouts available (including from plugins)
configerrors         - lists all current config parsing errors
rollinglog           - prints tail of the log. Also supports -f/--follow option
locked               - prints whether the current session is locked.
descriptions         - returns a JSON with all config options, their descriptions and types.
submap               - prints the current submap the keybinds are in

For the getoption command, the option name should be written as section.option, for example:

hyprctl getoption general.border_size

# For nested sections:
hyprctl getoption input.touchpad.disable_while_typing

See Config options for sections and options you can use.

Batch

You can use the --batch flag to issue multiple commands separated with a ;.

Flags

You can specify flags for the request like this:

hyprctl -j monitors

Flag list:

• j - output in JSON
• i - select instance (id or index in hyprctl instances)
• r - force state refresh after issuing commands (e.g., layout or rule changes)