Skip to content

marceloeatworld/hyprland-ai-skill

hyprland

Flagged

This skill should be used when the user asks about "Hyprland configuration", "hyprland.lua", "hyprland.conf", "Hyprland Lua config", "hyprctl", "Hyprland keybinds", "Hyprland window rules", "Hyprland monitors", "Hyprland dispatchers", "Hyprland animations", "Hyprland workspaces", "Hyprland IPC", "Hyprland plugins", "hyprlock", "hypridle", "hyprpaper", "hyprcursor", "hyprpicker", "hyprsunset", "xdg-desktop-portal-hyprland", "Hyprland on NixOS", "Hyprland Home Manager", "Hyprland layouts", "Hyprland dwindle", "Hyprland master layout", "Hyprland FAQ", "Hyprland performance", "Hyprland Nvidia", "Hyprland screen sharing", "Hyprland special workspace", "Hyprland smart gaps", "Hyprland multi-monitor", "Hyprland tearing", or any topic related to configuring, troubleshooting, or extending the Hyprland Wayland compositor and its ecosystem tools.

FileKindSize
SKILL.mdskill md7.8 KB
references/.wiki-versionother50 B
references/animations.mdmarkdown6.1 KB
references/autostart.mdmarkdown770 B
references/binds.mdmarkdown24.0 KB
references/code-snippets.mdmarkdown16.5 KB
references/contributing.mdmarkdown19.4 KB
references/crashes-and-bugs.mdmarkdown5.9 KB
references/devices.mdmarkdown2.0 KB
references/dispatchers.mdmarkdown13.1 KB
references/environment-variables.mdmarkdown4.0 KB
references/faq.mdmarkdown13.8 KB
references/gestures.mdmarkdown8.4 KB
references/getting-started.mdmarkdown26.6 KB
references/hypr-libraries.mdmarkdown15.9 KB
references/hyprctl.mdmarkdown8.3 KB
references/hyprcursor.mdmarkdown2.2 KB
references/hypridle.mdmarkdown11.2 KB
references/hyprland-qt-support.mdmarkdown2.3 KB
references/hyprlauncher.mdmarkdown2.1 KB
references/hyprlock.mdmarkdown20.6 KB
references/hyprpaper.mdmarkdown3.4 KB
references/hyprpicker.mdmarkdown1.9 KB
references/hyprpolkitagent.mdmarkdown2.3 KB
references/hyprpwcenter.mdmarkdown436 B
references/hyprshutdown.mdmarkdown2.0 KB
references/hyprsunset.mdmarkdown4.8 KB
references/hyprsysteminfo.mdmarkdown457 B
references/ipc.mdmarkdown6.6 KB
references/layouts.mdmarkdown19.1 KB
references/lua-scripting.mdmarkdown9.6 KB
references/monitors.mdmarkdown14.1 KB
references/multi-gpu.mdmarkdown4.6 KB
references/naming-conventions.mdmarkdown4.7 KB
references/nix.mdmarkdown30.1 KB
references/notifications.mdmarkdown2.4 KB
references/nvidia.mdmarkdown1.3 KB
references/performance.mdmarkdown1.5 KB
references/permissions.mdmarkdown5.2 KB
references/plugins.mdmarkdown18.2 KB
references/start.mdmarkdown6.9 KB
references/systemd.mdmarkdown2.0 KB
references/tearing.mdmarkdown1.7 KB
references/useful-utilities.mdmarkdown47.4 KB
references/variables.mdmarkdown59.0 KB
references/virtual-gpu.mdmarkdown6.9 KB
references/window-rules.mdmarkdown19.2 KB
references/workspace-rules.mdmarkdown2.7 KB
references/xdph.mdmarkdown5.7 KB
references/xwayland.mdmarkdown2.0 KB
scripts/generate-references.shexecutablescript12.1 KB

references/hyprctl.md

View on GitHub
<!-- source: https://wiki.hypr.land/configuring/core/advanced-configuration/using-hyprctl -->
<!-- wiki commit: 41c7222 (2026-11-20 18:16:21 +0100) -->
<!-- auto-generated by scripts/generate-references.sh - DO NOT EDIT MANUALLY -->

---
weight: 20
title: 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.

> [!WARNING]
> `hyprctl` calls will be dispatched by the compositor _synchronously_, meaning any spam of the utility will cause slowdowns.
> It's recommended to use `--batch` for many control calls, and limiting the amount of info calls.
>
> For live event handling, see the [events](../events).

## Commands

### eval

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

```sh
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:

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

Examples:

```sh
$ 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(...)'`:

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

See [Dispatchers](../../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:

```sh
hyprctl setcursor Bibata-Modern-Classic 24
```

### output

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

Usage:

```sh
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.).

> [!NOTE]
> `create` and `remove` can also be `add` or `destroy`, respectively.

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":

```sh
hyprctl output create headless test
```

And to remove it:

```sh
hyprctl output remove test
```

### switchxkblayout

Sets the XKB layout index for a keyboard.

For example, if you set:

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

You can use this command to switch between them.

```sh
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:

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

> [!NOTE]
> If you want a single variant (e.g., pl/dvorak on one layout but us/qwerty on the other) XKB parameters can still be blank.
> However, the amount of comma-separated parameters has to match.
> Alternatively, a single parameter can be specified for it to apply to all three.
>
> ```lua
> 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.

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

To disable:

```sh
hyprctl seterror disable
```

### getprop

Gets a property value of a window.

```sh
hyprctl getprop <window> <property>
```

Where `window` is as described [here](../../dispatchers#parameter-explanation), and `property` is any which can be set with [set_prop](../../dispatchers/#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](../notifications), especially for icon and color options.

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

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

{{% details title="Examples" closed="true" %}}

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

### dismissnotify

Dismisses all or up to AMOUNT notifications.

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

{{% /details %}}

## Usage

```plain
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:

```sh
hyprctl getoption general.border_size

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

See [Config options](../../config-options) for sections and options you can use.

## Batch

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

> [!NOTE]
> Any semicolons inside of individual commands in the batch (e.g., multi-statement Lua code) must be backslash-escaped, and any literal backslashes must be escaped as well.
> This is *in addition to* any escaping already required by your shell.

## Flags

You can specify flags for the request like this:

```sh
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)
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 323kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 323kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 323kUpdated Claude CodeCodexVerifiedInstall