wlclock(1)

💖 wlclock — bestie edition 💖

okay so this is the manual page for wlclock(1), version 1.0.1, and honestly? she's iconic. let's get into it 🫶

---

✨ NAME ✨

wlclock — a digital analog clock for Wayland. yes, it says "digital analog," we don't make the rules, we just vibe with them 💅

---

🌸 DESCRIPTION 🌸

so basically wlclock puts an analog clock on your Wayland desktop. that's the whole thing. that's her job. she's doing it beautifully. ✨

she's inspired by xclock(1), and the default config was literally hand-picked to mimic it — like, a loving tribute, no cap. BUT. and this is the important part bestie: unlike xclock, wlclock is not a regular window. she's a desktop-widget. main character energy, but she stays in her lane. 👑

heads up: your Wayland compositor must implement the Layer-Shell and XDG-Output for wlclock to work. no implementation, no clock. it's giving prerequisites, fr fr. 😭

---

🎀 OPTIONS 🎀

every single flag, present and accounted for. nothing skipped, we don't do that here. 💖

• -h, --help — show the help message and dip out. ✨
• -V, --version — show the version and exit. she's telling you who she is.
• -v, --verbose — crank up the logging verbosity. more words! more info! 💬
• --background-colour <colour> — the background colour of the clock. default is "#FFFFFF". 🤍
• --border-colour <colour> — the border colour of the clock. default is "#000000". 🖤
• --border-size <size>, --border-size <top> <right> <bottom> <left> — set the border size. you either give her one argument to set every border at once, or four arguments to do each side individually, like a lil custom fit. default border size is 1. 📏
• --clock-colour <colour> — the colour of the clock elements. default is "#000000". ⏰
• --corner-radius <radius>, --corner-radius <top-left> <top-right> <bottom-right> <bottom-left> — the radius of the corners. expects either one argument to round all four corners equally, or four arguments for individual corner radii. if you go high enough with the values, wlclock becomes completely round (circle clock era 🌕). set it to 0 to turn corner roundness off entirely. default radius is 0. 🎀
• --exclusive-zone <option> — the exclusive zone of the surface. options are "true", "false" or "stationary".
  • "true" → the compositor is told it shouldn't obstruct wlclock's surface with other surfaces.
  • "false" → the compositor is told it can place other surfaces over or under wlclock's surface.
  • "stationary" → the compositor is told that wlclock's surface shouldn't be moved around to accommodate other layer shell surfaces, and that it can freely place other surfaces over or under her.
  • the default is "stationary".
  • > real talk: the exact implementation is compositor dependant. a compositor may just straight up ignore the requested exclusive zone of surfaces. so... yeah. 🙈
• --hand-width <size> — the width of the clock hands. if you set it to 0, wlclock draws xclock-like clock hands. default is 0. 🕰️
• --layer <layer> — the layer of the layer surface. can be "overlay", "top", "bottom" or "background". typically "bottom" and "background" end up underneath regular windows, while "top" and "overlay" end up above them — but the exact placement on the z axis depends on how the compositor implements it. default layer is "overlay". 🌈
• --margin <size>, --margin <top> <right> <bottom> <left> — set the margin. either one argument for all margins, or four arguments for each one individually. default margin is 0. 📐
• --marking-width <size> — the width of the markings on the clock face. default is 1. 🔢
• --namespace <namespace> — the namespace of the layers surface. some compositors treat layer surfaces differently depending on their namespace, so this is your lil label. default is "wlclock". 🏷️
• --no-input — with this flag, wlclock asks the compositor to not send her input events. result: mouse events pass straight through wlclock to the windows beneath her. ghost clock behaviour 👻
• --output <output name> — the name of the output where wlclock should show up. output names are compositor dependant. if you set it to "all" or "*", wlclock shows on all outputs — and that's the default behaviour. 🖥️✨
• --position <position> — set the position of the clock. can be "center", "top", "right", "bottom", "left", "top-right", "top-left", "bottom-right" and "bottom-left". defaults to "center". 📍
• --size <size> — the size of the clock, without borders. default size is 165. 📦
• --snap — with this flag, the hour hand instantly snaps to the next position once the new hour begins, instead of slowly creeping over the course of the hour. no more gradual drift, we go straight to the point 💥

---

🌈 COLOURS 🌈

wlclock can parse hex code colours and read RGB values directly. she's flexible like that. 💅

the supported formats are:

• "#RRGGBB" and "#RRGGBBAA" — hex code colours
• "0xRRGGBB" and "0xRRGGBBAA" — hex code colours, the 0x way
• "rgb(rrr,ggg,bbb)" and "rgba(rrr,ggg,bbb,aaa)" — RGB colours

---

👑 AUTHORS 👑

Leon Henrik Plickat <leonhenrik.plickat@stud.uni-goettingen.de>

---

and that's the whole page, bestie!! 🫶 she's wlclock(1), she's Version 1.0.1, and this manual was dated 2025-10-20 — so if you're reading this way in the future, hi, hope the clock still slays. 💖✨🎀🦋