wlcctrl(1)

📦

version 1.3.2 · 3 versions

1.3.2 · arch rolling (latest)
1.3.2 · ubuntu stonking
1.3.1.1 · ubuntu resolute

💅 wlcctrl(1) — the kylin-wayland-compositor CLI bestie 🎀

okay so this is the general commands manual page for wlcctrl(1), and honestly? it's giving "tiny utility, huge power." grab a snack, we're going through everything. 🍓

✨ NAME ✨

wlcctrl — a command line utility for kylin-wayland-compositor. no cap, that's the whole name section 🫶

🌸 SYNOPSIS 🌸

wlcctrl [command] [options...]

🦋 GLOBAL OPTIONS 🦋

these are the base-level besties that work with basically everything 💖

--help — pops a help message and dips. quit. gone. slay.
-v, --version — shows the wlcctrl version and bounces.
--exec <str> — runs a shell command, literally just hands it over.
--sleep <int_ms> — sets sleep time in milliseconds. it can be combined with other commands, which is highkey the whole point ✨

example:

wlcctrl --keydown a --sleep 1000 --keyup a wlcctrl --mousepress 1 --sleep 200 --mouserelease 1

--path <str> — sets the screenshot save path (PNG format). if you set it multiple times, it uses the last value. main character value only 💅

with --windowcapture: sets the window screenshot saved path.

with --workspacecapture: sets the workspace screenshot saved path.

with --fullscreencapture: sets the screen/output screenshot saved path.

example:

wlcctrl --windowcapture uuid --path "/home/kylin/xxx.png"

-o <o_uuid> — specifies the output device by UUID. set it more than once and again, it uses the last value. consistent queen 👑

⌨️ KEYBOARD OPTIONS ⌨️

--keystring <string> — sends a string that gets typed into the focused client. heads up though: no commands can chain after keystring. it's the last one at the party, periodt 🙈
--key <key> — sends key events. single key or a whole key combination, your call.

Note: CapsLock(58), NumLock(69), ScrollLock(70) may not switch states normally. For reliable lock key functionality, use ydotool instead. (yes this is a real caveat, don't come for me 😭)

Key mappings:

"PrintScreen" -> "sys_req" "esc" -> "escape" "ctrl" -> "control_l" "shift" -> "shift_l" "alt" -> "alt_l" "winleft" -> "super_l" "enter" -> "return"

Valid keys: escape, return, shift_l, shift_r, control_l, control_r, meta_l, meta_r, alt_l, alt_r, page_up, page_down, menu, caps_lock, pause, break, print, sys_req, scroll_lock, num_lock, etc.

Multiple keys separated by +.

examples:

wlcctrl --key control_l+alt_l+t wlcctrl --key ctrl+alt+t wlcctrl --key super_l

--keyup <key> — releases a single key. bye bestie 👋
--keydown <key> — presses a single key.

with --keyup: means pressing and releasing a key.

otherwise: means the state of a key being pressed individually, and the command defaults to releasing the key upon completion. it always cleans up after itself, we love a responsible icon 🌈

🖱️ POINTER OPTIONS 🖱️

--mousebutton <button> — clicks a mouse button.

Button codes:

1 = BTN_LEFT 2 = BTN_RIGHT 3 = BTN_MIDDLE 4 = BTN_EXTRA 5 = BTN_SIDE 6 = BTN_FORWARD 7 = BTN_BACK

example:

wlcctrl --mousebutton 2

--mousepress [button] — presses a mouse button.

Button codes:

1 = BTN_LEFT 2 = BTN_RIGHT 3 = BTN_MIDDLE 4 = BTN_EXTRA 5 = BTN_SIDE 6 = BTN_FORWARD 7 = BTN_BACK

with --mouserelease means pressing and releasing a mouse button.

with --mousemove can be combined into a drag-and-drop action. iconic combo honestly 🫶

otherwise: means the state of an individual mouse button being pressed, and the command defaults to releasing the mouse button upon completion.

example: Click a mouse button.

wlcctrl --mousepress 2 --mouserelease 2

example: Complete a drag-and-drop action.

/wlcctrl --mousemove 500,600 --mousepress 1 --mousemove 100,200 --mouserelease 1

--mouserelease [button] — releases a mouse button.

--mousemove <dx,dy> — moves the cursor. dx = right displacement, dy = down displacement. only non-negative numbers allowed. Units: pixels.

example:

wlcctrl --mousemove 100,500

--scroll [-x <dx>] [-y <dy>] — scrolls the cursor. negative numbers are allowed here, so go off 😌

examples:

wlcctrl --scroll -y 10 wlcctrl --scroll -x 10 -y 20

--getmouselocation — gets the current mouse position. where is she 👀

🪟 TOPLEVEL OPTIONS 🪟

-l, --list — lists the names of all known toplevel.
--windowmove <w_uuid> [options...] — moves the window to a specified position.
- -x <dx> — dx is the displacement in the positive-right direction.
- -y <dy> — dy is the displacement in the positive-downward direction.

Only non-negative numbers are allowed.

example:

wlcctrl --windowmove 182fcd8f-6136-413b-aa1b-c77b066ebe23 -x 200 -y 400

--windowsize <w_uuid> [options...] — resizes the window. w_uuid: this is the UUID of the toplevel device.
- -w <width> — width is the desired window width.
- -h <height> — height is the desired window height.

Units are pixels.

example:

wlcctrl --windowsize 182fcd8f-6136-413b-aa1b-c77b066ebe23 -w 800 -h 600

--windowminimize <w_uuid> — minimizes the window. w_uuid is the UUID of the toplevel. nap time 😴
--windowmaximize <w_uuid> — maximizes the window. the default output device is the primary display. w_uuid is the UUID of the toplevel.

with -o: sets the output device for the action.

example:

wlcctrl --windowmaximize <w_uuid> -o <o_uuid>

--windowfullscreen <w_uuid> — fullscreens the window. the default output device is the primary display. w_uuid is the UUID of the toplevel.

with -o: sets the output device for the action.

example:

wlcctrl --windowfullscreen <w_uuid> -o <o_uuid>

--windowenter <w_uuid:uuid> — adds the window into the specified workspace. w_uuid is the UUID of the toplevel. uuid is the workspace that window is to be entered.
--windowleave <w_uuid:uuid> — removes the window from the specified workspace. w_uuid is the UUID of the toplevel. uuid is the workspace that window is to be left.
--movewindowtoworkspace <w_uuid:uuid> — moves the window to the specified workspace. w_uuid is the UUID of the toplevel. uuid is the workspace that window moved to.
--movewindowtooutput <w_uuid:o_uuid> — moves the window to the specified output device. w_uuid is the UUID of the toplevel. o_uuid is the UUID of the output device.
--windowmap <w_uuid> — restores the window. w_uuid is the UUID of the toplevel. she's back 💖
--windowclose <w_uuid> — closes the window. w_uuid is the UUID of the toplevel.
--windowkill <app_id> — force closes all windows of the specified app_id. not a gentle "please leave," it's a "you're done" 💀
--windowactivate <w_uuid> — activates the specified window. w_uuid is the UUID of the toplevel.
--windowcapture <w_uuid> — takes a screenshot of a window. saved by default in the current working directory. w_uuid is the UUID of the toplevel. 📸
--getactivewindow — gets the current active window.
--getwindowname <w_uuid> — queries the app ID, title, icon and pid of a specific window. w_uuid is the UUID of the toplevel.
--getwindowgeometry <w_uuid> — queries the geometry of a specific window. w_uuid is the UUID of the toplevel.
--search <name> — obtains the window UUID list by checking if the regular expression pattern matches the window app_id, icon and title.

🌈 OUTPUT OPTIONS 🌈

--outputs — lists the name of all known outputs.
--getdisplaygeometry <o_uuid> — gets the geometry of a specified output. o_uuid is the UUID of the output device.
--fullscreencapture — takes a fullscreen screenshot. saves the file to the current working directory by default. by default, captures a fullscreen image of the primary display.

example:

wlcctrl --fullscreencapture

with -o: sets the output device for the action.

example:

wlcctrl --fullscreencapture -o <o_uuid>

--setarea <x,y,width,height> — area screenshot. sets the position and size of the rectangular region. the default output device is the primary display.

x is X coordinate of the screenshot area in output coordinate. y is Y coordinate of the screenshot area in output coordinate. width is Width of the screenshot area. height is Height of the screenshot area.

with -o: sets the output device for the area.

with --path: sets the screenshot save path.

example:

wlcctrl --setarea 10,40,500,100 --path "/home/kylin/xxx.png"
wlcctrl --setarea 10,40,500,500 --path "/home/kylin/xxx111.png" -o d4d40b7b-5e2e-396a-eaa2-7b5efea5a3ec

--getpixelcolor <x,y> — gets the RGBA value of a pixel at a specified position. the default output device is the primary display. x is X coordinate of the point in output coordinate. y is Y coordinate of the point in output coordinate.

with -o: sets the output device for the pixel location.

example:

wlcctrl --getpixelcolor 100,3

🧚 WORKSPACE OPTIONS 🧚

--workspace — lists the name of all known workspaces.
--workspacecapture <uuid:o_uuid> — takes a screenshot of a workspace. saves the file to the current working directory by default. uuid is the workspace that needs to be captured. o_uuid is the UUID of the output device.
--workspaceadd <num> — adds new workspaces. if num is unspecified, a workspace will be added by default. new space, who dis ✨
--workspaceremove <uuid> — removes the specified workspace. uuid: the workspace that needs to be operated on.
--workspaceactive <uuid> — activates the specified workspace. uuid is the workspace that needs to be operated on.

okay that's literally the whole thing, go forth and control some wayland compositor windows bestie 💜

this masterpiece of a manual page is dated 2026-11-03, and yes it's the wlcctrl(1) page — signed, sealed, delivered, group-chat approved 🎀🔥

📦 where this page comes from

arch rolling: kylin-wayland-compositor 1.3.2-1 · MIT AND CC0-1.0 AND GPL-3.0-or-later AND HPND-sell-variant AND LGPL-2.1-or-later AND MIT-CMU
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms