hyprland-wiki/pages/Configuring/Using-hyprctl.md

346 lines
8.3 KiB
Markdown
Raw Normal View History

---
weight: 12
title: Using hyprctl
---
2022-08-12 20:46:36 +02:00
`hyprctl` is a utility for controlling some parts of the compositor from a CLI
or a script. If you install with `make install`, or any package, it should
automatically be installed.
To check if `hyprctl` is installed, simply execute it by issuing `hyprctl` in
the terminal.
If it's not, go to the repo root and `/hyprctl`. Issue a `make all` and then
`sudo cp ./hyprctl /usr/bin`.
{{< callout type=warning >}}
2022-08-13 17:00:36 +02:00
_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.
2022-08-13 17:00:36 +02:00
2024-03-17 13:44:39 +01:00
For live event handling, see the [socket2](../../IPC/).
2022-08-13 17:00:36 +02:00
{{< /callout >}}
2022-08-13 17:00:36 +02:00
## Commands
2022-08-12 20:46:36 +02:00
### dispatch
2022-08-12 20:46:36 +02:00
Issue a `dispatch` to call a keybind dispatcher with an arg.
2022-08-12 20:46:36 +02:00
An arg has to be present, for dispatchers without parameters it can be anything.
To pass an argument starting with `-` or `--`, such as command line options to
`exec` programs, pass `--` as an option. This will disable any subsequent
parsing of options by _hyprctl_.
2022-08-12 20:46:36 +02:00
Examples:
```sh
2022-08-12 20:46:36 +02:00
hyprctl dispatch exec kitty
hyprctl dispatch -- exec kitty --single-instance
2022-08-12 20:46:36 +02:00
hyprctl dispatch pseudo x
```
Returns: `ok` on success, an error message on fail.
See [Dispatchers](../Dispatchers) for a list of dispatchers.
### keyword
2022-08-12 20:46:36 +02:00
issue a `keyword` to call a config keyword dynamically.
Examples:
```sh
2022-08-12 20:46:36 +02:00
hyprctl keyword bind SUPER,O,pseudo
hyprctl keyword general:border_size 10
2023-01-05 14:37:13 +01:00
hyprctl keyword monitor DP-3,1920x1080@144,0x0,1
2022-08-12 20:46:36 +02:00
```
Returns: `ok` on success, an error message on fail.
### reload
2022-08-12 20:46:36 +02:00
Issue a `reload` to force reload the config.
2022-08-12 20:46:36 +02:00
### kill
Issue a `kill` to get into a kill mode, where you can kill an app by clicking on
2022-08-12 20:46:36 +02:00
it. You can exit it with ESCAPE.
Kind of like xkill.
### setcursor
2022-08-13 01:47:48 +02:00
Sets the cursor theme and reloads the cursor manager. Will set the theme for
everything except GTK, because GTK.
2022-08-12 20:46:36 +02:00
2024-03-18 18:45:06 +01:00
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.
2022-08-12 20:46:36 +02:00
params: theme and size
e.g.:
2022-08-13 01:47:48 +02:00
```sh
2022-08-12 20:46:36 +02:00
hyprctl setcursor Bibata-Modern-Classic 24
```
2022-11-05 19:09:03 +01:00
### output
Allows you to add and remove fake outputs to your preferred backend.
2024-06-06 00:05:28 +02:00
Usage:
2022-11-05 19:09:03 +01:00
2024-06-06 00:05:28 +02:00
```sh
hyprctl output create [backend] (name)
```
or
```sh
hyprctl output remove [name]
```
2022-11-05 19:09:03 +01:00
2024-06-06 00:05:28 +02:00
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.)
2022-11-05 19:09:03 +01:00
2024-06-06 00:05:28 +02:00
{{< callout type=info >}}
2022-11-05 19:09:03 +01:00
2024-06-06 00:05:28 +02:00
`create` and `remove` can also be `add` or `destroy`, respectively.
2022-11-05 19:09:03 +01:00
2024-06-06 00:05:28 +02:00
{{< /callout >}}
2024-06-06 00:05:28 +02:00
Available backends:
- `wayland`: Creates an output as a Wayland window. This will only work if you're already running Hyprland with the Wayland backend.
- `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.
2022-11-05 19:09:03 +01:00
2024-06-06 00:05:28 +02:00
For example, to create a headless output named "test":
```sh
hyprctl output create headless test
```
And to remove it:
```sh
hyprctl output remove test
2022-11-05 19:09:03 +01:00
```
### switchxkblayout
2022-12-03 16:59:13 +01:00
Sets the xkb layout index for a keyboard.
For example, if you set:
2022-12-03 16:59:13 +01:00
```ini
device {
name=my-epic-keyboard-v1
2022-12-17 23:41:47 +01:00
kb_layout=us,pl,de
2022-12-03 16:59:13 +01:00
}
```
You can use this command to switch between them.
2023-03-13 21:48:26 +01:00
```sh
hyprctl switchxkblayout [DEVICE] [CMD]
2022-12-03 16:59:13 +01:00
```
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.
2023-03-13 21:48:26 +01:00
Example command for a typical keyboard:
2023-03-13 21:48:26 +01:00
```sh
hyprctl switchxkblayout at-translated-set-2-keyboard next
```
{{< callout type=info >}}
2023-03-13 21:48:26 +01:00
If you want a single variant ie. pl/dvorak on one layout but us/qwerty on the
other, xkb parameters can still be blank, however the amount of comma-separated
parameters have to match. Alternatively, a single parameter can be specified for
it to apply to all three.
2023-03-13 21:48:26 +01:00
```ini
input {
kb_layout = pl,us,ru
kb_variant = dvorak,,
kb_options = caps:ctrl_modifier
}
```
{{< /callout >}}
2022-12-03 16:59:13 +01:00
2023-01-24 20:14:39 +01:00
### 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
2023-01-24 20:14:39 +01:00
```
To disable:
2023-01-24 20:14:39 +01:00
```sh
hyprctl seterror disable
```
### setprop
Sets a window prop. Can be locked by adding `lock` at the end. If `lock` is not
added, will be unlocked. Locking means a dynamic windowrule _cannot_ override
this setting.
2023-01-24 20:14:39 +01:00
Prop List:
| prop | comment |
| --- | --- |
| animationstyle | string, cannot be locked |
| rounding | int, -1 means not overriden |
2023-06-04 21:36:17 +02:00
| bordersize | int, -1 means not overriden |
2023-01-24 20:14:39 +01:00
| forcenoblur | 0/1 |
| forceopaque | 0/1|
| forceopaqueoverriden | 0/1 |
| forceallowsinput | 0/1, forceinput rule |
| forcenoanims | 0/1 |
| forcenoborder | 0/1 |
2023-05-31 21:14:33 +02:00
| forcenodim | 0/1 |
2023-01-24 20:14:39 +01:00
| forcenoshadow | 0/1 |
| nofocus | 0/1 |
2023-01-24 20:14:39 +01:00
| windowdancecompat | 0/1 |
| nomaxsize | 0/1 |
| minsize | vec2 (`x y`) |
| maxsize | vec2 (`x y`) |
2023-01-24 20:14:39 +01:00
| dimaround | 0/1 |
2023-08-08 18:53:03 +02:00
| keepaspectratio | 0/1 |
2023-01-24 20:14:39 +01:00
| alphaoverride | 0/1, makes the next setting be override instead of multiply |
| alpha | float 0.0 - 1.0 |
| alphainactiveoverride | 0/1, makes the next setting be override instead of multiply |
| alphainactive | float 0.0 - 1.0 |
2024-04-08 00:19:17 +02:00
| alphafullscreenoverride | 0/1, makes the next setting be override instead of multiply |
| alphafullscreen | float 0.0 - 1.0 |
2024-04-09 17:15:04 +02:00
| activebordercolor | gradient, -1 means not set |
| inactivebordercolor | gradient, -1 means not set |
2023-01-24 20:14:39 +01:00
2023-01-24 20:16:22 +01:00
```sh
hyprctl setprop address:0x13371337 forcenoanims 1 lock # with locking
hyprctl setprop address:0x13371337 nomaxsize 0 # without locking
```
2023-03-20 17:03:55 +01:00
### notify
Sends a notification using the built-in Hyprland notification system.
```sh
hyprctl notify [ICON] [TIME_MS] [COLOR] [MESSAGE]
```
For example:
2023-03-20 17:03:55 +01:00
```sh
hyprctl notify -1 10000 "rgb(ff1ea3)" "Hello everyone!"
```
Icon of `-1` means "No icon"
Color of `0` means "Default color for icon"
Icon list:
2023-03-20 17:03:55 +01:00
```
WARNING = 0
INFO = 1
HINT = 2
ERROR = 3
CONFUSED = 4
OK = 5
```
Optionally, you can specify a font size of the notification like so:
```sh
hyprctl notify -1 10000 "rgb(ff0000)" "fontsize:35 This text is big"
```
The default font-size is 13.
### dismissnotify
Dismisses all or up to AMOUNT notifications.
```sh
hyprctl dismissnotify # dismiss all notifications
hyprctl dismissnotify 2 # dismiss the oldest 2 notifications
hyprctl dismissnotify -1 # dismiss all notifications (same as no arguments)
```
2022-08-12 20:46:36 +02:00
## Info
2022-10-26 14:20:18 +02:00
```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
2022-08-12 20:46:36 +02:00
workspaces - lists all workspaces with their properties
activeworkspace - gets the active workspace and its properties
2023-10-21 03:28:46 +02:00
workspacerules - gets the list of defined workspace rules
2022-08-12 20:46:36 +02:00
clients - lists all windows with their properties
devices - lists all connected keyboards and mice
decorations [window] - lists all decorations and their info
2023-01-06 14:33:14 +01:00
binds - lists all registered binds
activewindow - gets the active window name and its properties
2022-08-12 20:46:36 +02:00
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
2024-03-21 16:19:42 +01:00
rollinglog - prints tail of the log
locked - prints whether the current session is locked.
2022-08-12 20:46:36 +02:00
```
For the getoption command, the option name should be written as
`section:option`, e.g.:
```sh
hyprctl getoption general:border_size
# For nested sections:
hyprctl getoption input:touchpad:disable_while_typing
```
See [Variables](../Variables) for sections and options you can use.
## Batch
2022-08-12 20:46:36 +02:00
You can also use `--batch` to specify a batch of commands to execute.
2022-08-12 20:46:36 +02:00
e.g.
```sh
2022-08-12 20:46:36 +02:00
hyprctl --batch "keyword general:border_size 2 ; keyword general:gaps_out 20"
```
`;` separates the commands
## Flags
2022-08-12 20:46:36 +02:00
You can specify flags for the request like this:
```sh
2022-08-12 20:46:36 +02:00
hyprctl -j monitors
```
flag list:
```txt
2022-08-12 20:46:36 +02:00
j -> output in JSON
2023-08-08 18:08:07 +02:00
i -> select instance (id or index in hyprctl instances)
2022-08-12 20:46:36 +02:00
```