hatwmctl

hatwmctl (HatWM Control) is a command-line client for HatWM IPC protocol v1. It uses the Unix socket exported by HatWM at $HATWM_SOCKET, falling back to $XDG_RUNTIME_DIR/hatwm/ipc.sock.

Build

Requirements:

• Go
• Meson
• Ninja

meson setup build
meson compile -C build

Meson uses Ninja as its default backend and writes the executable to build/hatwmctl. Run tests and static analysis with:

meson test -C build

Install under /usr/local/bin:

sudo meson install -C build

For an Arch package build:

meson setup build --prefix=/usr
DESTDIR="$pkgdir" meson install -C build

To format the Go sources or run vet directly through Ninja:

meson compile -C build fmt
meson compile -C build vet

Remove files installed by Meson with sudo ninja -C build uninstall.

Commands

hatwmctl status
hatwmctl workspaces
hatwmctl windows
hatwmctl hat
hatwmctl diagnostics
hatwmctl workspace 2
hatwmctl move 3
hatwmctl toggle-tiling
hatwmctl toggle-keyboard-layout
hatwmctl toggle-fullscreen
hatwmctl focus-next
hatwmctl close
hatwmctl hat-stash
hatwmctl hat-show
hatwmctl hat-restore
hatwmctl hat-restore 12
hatwmctl hat-next
hatwmctl set-wallpaper ~/Pictures/Wallpapers/wallpaper.jpg
hatwmctl reload

status, workspaces, and windows report urgent workspaces/windows when an application requests activation from another workspace. The JSON output includes an urgent boolean on both workspace and window records.

hat-stash puts the focused window into The Hat. hat-restore summons the first entry onto the active workspace; pass a window ID to choose an entry. hat-show requests the graphical Hat picker, hat-next rotates restore order, and hat displays that order.

status reports every connected output and marks the output currently active for keyboard commands. windows includes each window's assigned output. diagnostics reports HatWM and wlroots versions, outputs, input devices, session-lock state, focused window, and optional protocol availability.

Watch all compositor events:

hatwmctl watch

Watch selected events:

hatwmctl watch workspace_changed,focus_changed window_opened

Print the server response as formatted JSON:

hatwmctl --json status
hatwmctl --json windows
hatwmctl --json watch

Use a non-default socket:

hatwmctl --socket /run/user/1000/hatwm/ipc.sock status

Shell examples

Switch workspace from a script:

hatwmctl workspace 4

Get the active workspace using jq:

hatwmctl --json status | jq -r '.result.workspace'

Print the active keyboard layout:

hatwmctl --json status | jq -r '.result.keyboard_layout'

Advance to the next layout configured by HatWM:

hatwmctl toggle-keyboard-layout

Change the wallpaper for the current session:

hatwmctl set-wallpaper ~/Pictures/Wallpapers/wallpaper.jpg

This does not rewrite HatWM's configuration file. To make the change persistent, update the wallpaper setting there as well.

The JSON form prints the complete HatWM IPC envelope, including success and result fields.