IPC

Sweets exposes a small control socket for querying state and dispatching commands. The bundled sweetctl CLI is the easiest way to use it.

Socket

The compositor listens on a Unix socket:

$XDG_RUNTIME_DIR/sweets-<WAYLAND_DISPLAY>.sock

and exports SWEETS_SOCKET to processes it spawns. sweetctl finds the socket via $SWEETS_SOCKET, falling back to deriving the path from $WAYLAND_DISPLAY.

Protocol

One request per connection: the client sends a single command line, the server replies and closes. Responses begin with OK or ERR <message>; query data follows on subsequent lines. Unknown commands are rejected (ERR). sweetctl prints the response and exits non-zero on ERR.

The one exception is subscribe: that connection stays open and the server keeps streaming event lines until the client disconnects.

Pass -j/--json before the command to get the read queries as machine-readable JSON instead of text.

The server documents itself: sweetctl help lists every command it accepts, so the authoritative reference is always the running compositor, not this page.

sweetctl help              # every command, with a one-line summary
sweetctl help output       # just the forms of one command
sweetctl -j help           # the command list as JSON

help <command> filters to one command's forms; an unknown name replies ERR. commands is an alias for help.

Commands

Examples

sweetctl version
sweetctl config
sweetctl config-sources
sweetctl outputs
sweetctl output DP-1
sweetctl output DP-1 scale 1.5
sweetctl output DP-1 mode 2560 1440 144
sweetctl output DP-1 position 0 0
sweetctl output DP-1 transform 90
sweetctl output DP-1 power off
sweetctl output all power on
sweetctl inputs
sweetctl input ELAN
sweetctl input ELAN accel_speed -0.25
sweetctl input "Logitech USB Optical Mouse" accel_profile flat
sweetctl views
sweetctl workspace 2
sweetctl reload
sweetctl action toggle_floating
sweetctl action focus_left
sweetctl action workspace 3
sweetctl action layout tabbed
sweetctl action spawn foot
sweetctl subscribe focus view workspace layout
sweetctl subscribe focus title

Sweets also reloads sweets.lua automatically when it — or any included file — changes. The IPC command is useful as a fallback or for scripts; config-sources lists exactly which files the watcher is tracking.

JSON output

Add -j (or --json) before the command and the read queries emit a single JSON value on stdout instead of the line-oriented text — the shape scripts and status bars actually want to parse:

sweetctl -j outputs
sweetctl -j views | jq '.[] | select(.focused) | .title'
sweetctl -j workspaces | jq '.workspaces[] | select(.active) | .index'
sweetctl -j config | jq -r .mod_key

The flag applies to every read query: version, outputs, output <name>, workspaces, views, config, config-sources, config-error, inputs, and input <name>. Arrays (outputs, views, inputs) come back as JSON arrays; everything else is a JSON object. Strings are properly escaped, so window titles and device names are always valid JSON.

How the client behaves in -j mode, so it composes cleanly in a pipeline:

• Success prints only the JSON document to stdout (the OK status line is stripped), exit code 0. Pipe straight into jq.
• Errors print the message to stderr (not stdout) and exit non-zero, so a failed query never feeds malformed data into a parser.
• Mutating commands (output ... scale, action ..., workspace, close, reload, …) accept -j too: on success they print nothing and exit 0; on failure the message goes to stderr with a non-zero exit. Use the exit code.

Example shapes:

// sweetctl -j outputs
[{"name":"DP-1","width":2560,"height":1440,"refresh":144.000,"x":0,"y":0,"scale":1.00,"workspace":1}]

// sweetctl -j views
[{"output":"DP-1","workspace":1,"app_id":"foot","title":"~","floating":false,
  "minimized":false,"fullscreen":false,"maximized":false,"focused":true,"icon":"foot"}]

// sweetctl -j workspaces
{"workspaces":[{"output":"DP-1","index":1,"windows":2,"layout":"tile",
  "master_position":"left","active":true}],"special":null}

// sweetctl -j config-error   (when the config is valid)
{"error":false}

Nullable fields are explicit: app_id, icon, and a window title-less client report null, and special is null when the scratchpad is empty.

Query output

output <name>

Reports the live geometry of a single output, e.g.:

OK
output DP-1
enabled true
position 0,0
size 2560x1440
refresh 144.000
scale 1.00
transform normal
usable 0,32 2560x1408
active_workspace 1
master 50.0

config

Reports the live values after any reloads, e.g.:

OK
mod_key SUPER
background #12121C
gap_inner 8
gap_outer 8
smart_gaps true
master 50
new_window master
border_width 2
border_focused #C27AFF
border_unfocused #333338
pointer_follow_focus true
pointer_follow_focus_restore true
pointer_follow_workspace true
pointer_follow_new_window true
pointer_hide_when_following false

config-sources

Lists every Lua file the running config was built from — the main file plus each sweets.include target, in load order. This is exactly the set the reload watcher tracks, so it is handy for confirming an include actually took effect:

OK
count 4
source /usr/share/sweets/sweets.lua
source /home/ns/.config/sweets/sweets.lua
source /home/ns/.config/sweets/parts/binds.lua
source /home/ns/.config/sweets/parts/rules.lua

Paths are absolute and canonical. count 0 with no source lines means no config file was found and the compositor is running on built-in defaults.

Status-bar recipe: a config-health module

Pairing config-error with config-sources gives a bar a small "is my config OK" indicator: show a warning when the last reload failed, and list the loaded files in the tooltip so a hover reveals exactly what is active. This Waybar custom module does both — it reads the two queries and prints one JSON line (using jq so the multi-line tooltip is escaped into valid JSON):

#!/bin/sh
# config-error -> health; config-sources -> tooltip file list
err=$(sweetctl config-error)
if printf '%s' "$err" | grep -q '^error true'; then
  msg=$(printf '%s' "$err" | sed -n 's/^message //p')
  jq -cn --arg t "config ⚠" --arg tip "$msg" \
    '{text:$t, class:"error", tooltip:$tip}'
else
  files=$(sweetctl config-sources | sed -n 's/^source //p')
  count=$(printf '%s\n' "$files" | grep -c .)
  tip=$(printf 'config OK — %s files\n%s' "$count" "$files")
  jq -cn --arg t "config ✔" --arg tip "$tip" \
    '{text:$t, class:"ok", tooltip:$tip}'
fi

"custom/config": {
  "exec": "~/.config/sweets/scripts/config-health.sh",
  "return-type": "json",
  "interval": 5,
  "on-click": "sweetctl reload"
}

Because the file set only changes on a reload, a short interval (or a signal-driven refresh after sweetctl reload) is plenty — there is no event to subscribe to for config changes.

config-error

Reports the most recent config load or reload failure, so a status bar can show it without scraping the log. The compositor keeps running on the last good configuration; this is the same error the on-screen bar displays.

When the current config is valid:

OK
error false

After a failed load or reload, error true is followed by the failing file, the 1-based line (omitted when unknown), and the full message:

OK
error true
file /home/ns/.config/sweets/sweets.lua
line 9
message /home/ns/.config/sweets/sweets.lua:9: '}' expected (to close '{' at line 6) near '='

The error clears the moment a later edit reloads cleanly. Poll this after a reload, or pair it with the bar described in Error reporting.

inputs

Reports connected input devices. Physical libinput pointers include the same touchpad / mouse type used by sweets.input(selector, { ... }); touch, tablet, tablet-pad, and switch devices are listed too:

OK
input keyboard libinput=true name="AT Translated Set 2 keyboard"
input pointer type=touchpad libinput=true name="ELAN1200:00 04F3:30BA Touchpad"
input pointer type=mouse libinput=true name="Logitech USB Optical Mouse"
input touch libinput=true name="ELAN Touchscreen"
input tablet libinput=true name="Wacom Pen and multitouch sensor Pen stylus"
input tablet_pad libinput=true name="Wacom ExpressKey Remote Pad"
input switch libinput=true name="Lid Switch"

Use a unique part of the quoted name with sweets.input("name:TEXT", { ... }). Use the same unique substring with input <name> to inspect one device:

OK
kind pointer
type touchpad
name "ELAN1200:00 04F3:30BA Touchpad"
libinput true
sysname event4
id bus=0x0018 vendor=0x04f3 product=0x30ba
tap_fingers 3
tap supported=true current=true default=false
tap_drag supported=true current=true default=true
tap_drag_lock supported=true current=false default=false
natural_scroll supported=true current=true default=false
left_handed supported=true current=false default=false
middle_emulation supported=false
disable_while_typing supported=true current=true default=true
accel supported=true current=-0.250 default=0.000
accel_profiles flat adaptive
accel_profile current=adaptive default=adaptive

Live input tuning

Use the same unique device-name substring to change one supported setting right away:

sweetctl input ELAN tap true
sweetctl input ELAN natural_scroll true
sweetctl input ELAN accel_speed -0.25
sweetctl input "Logitech USB Optical Mouse" accel_profile flat

Boolean values accept true / false or on / off. The supported settings are tap, tap_drag, tap_drag_lock, natural_scroll, left_handed, middle_emulation, disable_while_typing, accel_speed (-1.0 through 1.0), and accel_profile (adaptive or flat). Sweets rejects settings a device cannot support.

Actions

action <name> [arg] runs a window-manager command by name. The names and arguments are exactly the ones sweets.bind accepts, so anything reachable from a keybind is reachable from a script, launcher, or status bar without binding a key for it.

sweetctl action focus_right
sweetctl action toggle_fullscreen
sweetctl action workspace 3
sweetctl action cycle_layout prev
sweetctl action master_position right
sweetctl action spawn foot -e htop

The reply is OK, or ERR <message> when the action name is unknown or its argument is missing or invalid (an out-of-range workspace, an unknown layout, and so on) — the compositor state is left untouched in that case.

Tile-only actions (master resize, master_position, grid_balance) no-op when the active workspace is not that layout, matching keybind behavior. See Key bindings for the full argument reference and aliases.

Events

Status bars and scripts usually want to redraw when something changes instead of polling on a timer. subscribe turns a connection into a live event stream:

sweetctl subscribe focus view workspace layout
# or, for everything:
sweetctl subscribe all

The server replies OK once, then writes one line per event for as long as the connection stays open. Press Ctrl-C (or close the socket) to stop.

Each line is event <name> followed by a compact payload describing what changed, so a bar can update straight from the stream without an extra query:

app_id and title are always double-quoted and escaped exactly like the --json strings, so a title with spaces, quotes, or newlines never breaks the line — one event is always one line. app_id is "" when the client set none. The output/ws pair is present whenever the window is on a workspace.

title is split out from view on purpose: titles change often (every shell command, every browser tab), so a bar that only tracks the window set can subscribe to view and avoid being woken on every title tick, while a bar that displays the focused title subscribes to focus and title.

view stays a bare notification — "the set changed, re-read it" — because no single window identifies the change. Everything else carries enough to redraw without a round trip:

# Print the focused window's title as it changes, no re-query needed
sweetctl subscribe focus title | while read -r _ _ rest; do
  echo "$rest"   # e.g. output=DP-1 ws=2 app_id="foot" title="~"
done

When you do need fuller state (window list, counts), re-query — ideally the --json form — on the matching event:

# Re-render a workspace/window indicator on every relevant change
sweetctl subscribe view workspace layout | while read -r _; do
  sweetctl -j workspaces
  sweetctl -j views
done

This is all a bar needs to track a monocle stack indicator like [2/5]: workspaces reports windows=N layout=monocle, and views marks the visible (focused) window and its order.