IPC
Inspect and control Sweets from scripts and panels
sweets msg lets scripts and panels read Sweets' state, run actions, and
listen for changes.
sweets msg windows
sweets msg workspaces
sweets msg outputs
sweets msg switch-workspace 3
sweets msg subscribe workspace windowMost commands print JSON. identify-input prints device IDs and names.
Add --json for compact output with the full response.
sweets msg --help lists every command.
Any program running as your user can use IPC. It can read window titles and run every action.
Queries
| Command | Returns |
|---|---|
pick-window | Click a window to get its ID |
windows, window ID | Windows: app ID, title, workspace, monitor, target geometry, state, tab group |
workspaces, workspace NUMBER [OUTPUT] | Workspaces: monitor, active, urgent, layout, windows |
outputs, output ID | Monitors: modes, position, scale, power, VRR |
inputs, input ID | Input devices and their settings |
input-activity | Last published physical device in an active identification session |
layers | Panels, launchers, and other layer surfaces |
special-workspace | Special workspaces and their windows |
scratchpads, scratchpad NAME | Named tools: active/retired state, startup, family IDs, shown host and visibility intent |
captures | Live screen and window captures |
keyboard | Keyboard layouts and the active one |
pointer | Pointer position |
status | Selected monitor, Overview, lock, gaming mode, binding mode, shortcut inhibition |
config | Config sources, reload state, watch coverage, and the last error |
binds [MODE] | All bindings, with desktop and active-layout shortcuts labeled |
window-rule ID | Which window rules matched a window |
window-appearance ID | A window's resolved opacity, blur, border, and shadow |
window-icon ID [SIZE] | A window's icon pixels, base64 |
xwayland | XWayland status |
frames, frame OUTPUT | Frame timing and direct scanout per monitor |
version | Compositor and IPC version |
system-info | OS, exact build, graphics and display information for bug reports |
{
"id": 2,
"output": "DP-1",
"active": true,
"layout": "grid",
"master_position": "left",
"windows": [42, 57]
}In per_monitor mode, name the monitor: sweets msg workspace 2 DP-1.
Check direct scanout
Run sweets msg frame DP-1 for one monitor or sweets msg frames for all
monitors. Frame queries in a batch return the same fields.
primary_planeisdirect_scanoutorcompositedfor the last completed native frame. Native HDR uses a composited primary plane.cursor_planeishardwareorsoftwarefor that frame, ornullif the monitor showed no cursor.direct_scanout_framescounts completed direct-scanout frames since the monitor was registered.
All three fields are null on nested and headless backends and until a native
monitor presents its first frame. A powered-off monitor keeps its last
assignments and count while it remains registered.
Named Scratchpads
Scratchpad queries, actions and events are covered in Scratchpads.
System information for a bug report
sweets msg system-info
sweets msg --json system-infoThe report omits monitor serial numbers, configuration paths and contents, window titles, usernames, hostnames, environment dumps, and logs. Hardware make/model and software versions are included. Long strings and unusually large collections are bounded, collection truncation is indicated in the report.
If Sweets cannot start, collect a local report instead:
sweets --system-info
sweets --system-info --jsonPick a window
sweets msg pick-windowLeft-click a window to print its ID. This keeps keyboard focus and your selected monitor unchanged.
You can pass the ID to commands such as sweets msg window ID.
Escape, right-click, or a background click prints cancelled.
After 30 seconds, it prints timed out.
Only one picker can run at a time. Close Overview or another active grab before starting one.
Wait for opening windows and gestures to finish.
With --json, the result is selected with a window ID, cancelled, or timed_out.
Selected monitor
sweets msg status includes selected_output, the monitor ID used by
monitor actions. Match it with an ID from sweets msg outputs.
It can name an empty or powered-off monitor and can differ from pointer.output.
It is null when no monitor is selected.
Subscribe to status before querying it, then query again on each invalidation.
Selection changes between empty monitors also send this event.
Overview
sweets msg overview open
sweets msg overview close
sweets msg statusRepeating open or close leaves the requested state unchanged.
Changes are refused during a swipe, a window drag, or screen lock.
Config and reload health
Show config sources, automatic reload health, and the last error:
sweets msg configIf a reload fails, Sweets keeps the last working config. To find the cause in the logs, see Troubleshooting.
Identify an input device
Run this command. Then move the mouse or press a key:
sweets msg identify-inputSweets prints the device ID and name. Use the name with an input selector. Press Ctrl+C to stop.
Requires a native Sweets session. Unplugging a device prints nothing.
Live screen and window captures
sweets msg captures
sweets msg subscribe captureEach entry shows a capture ID, the monitor or window being shared, and the Wayland client's PID when available. Browser screen shares through a portal show the portal's PID.
A modern capture session can appear even for one screenshot. For those
sessions, continuing is null. Legacy damage streams report true.
Ordinary legacy screenshots stay out of the list. Locking clears the list.
Window capture identifiers
window ID and windows include toplevel_identifier for screenshot tools.
Use it to match the exact window in the Wayland window list.
For the focused window, choose the windows entry with active: true.
The numeric id remains the value used by IPC commands.
The identifier can be null when unavailable. It expires when the window
unmaps or Sweets restarts. If the window disappears, stop the capture.
Capture permissions and screen-lock restrictions still apply.
Window icons
A window's icon has a theme name, pixel buffers, or both. Fetch the
pixels as RGBA:
sweets msg window-icon 42 | base64 -d > icon.rgbaWindow process IDs
windows, window ID, and batch window results include pid.
sweets msg window 42 | jq .data.pidThe PID belongs to the process that opened the Wayland connection. A proxy
that opens the connection will have its own PID. X11 windows and unavailable
PIDs show null.
The operating system can reuse a PID after the process exits.
Window parents
windows, window ID, and batch window results include parent.
sweets msg window 42 | jq .data.parentA dialog's parent is the ID of its parent window. It is null when
there is no open parent. The window event fires when the ID changes.
Window focus history
windows, window ID, and batch window results include focus_recency.
sweets msg window 42 | jq .data.focus_recencyHigher numbers mean more recent focus. Windows without a settled focus mark
show null. For a recent-window list, put the active window first and then
sort by focus_recency within the current session.
Sweets checks the debounce when it next records a focus change. A committed
change sends a window event. Use the focus event to track the active window.
Window geometry
window ID and windows include the intended position and size:
"target_geometry": { "position": [-790, 10], "size": [780, 580] }Values use logical pixels across all monitors. Position can be negative. Size includes borders and excludes tab bars, gaps, and shadows.
During a resize or animation, the visible window may still be elsewhere.
The field is null when the window has no target, including while minimized.
Hidden tabs can share a target. Query again when a window event arrives.
Tab groups
A window in a tab group has a group field:
"group": { "id": 7, "index": 0, "shown": true, "locked": false }index is the tab position, counting minimized tabs. shown marks the selected
tab, even when it is not on screen. locked is true when the group refuses
new tabs. Lock changes arrive as window events.
Several at once
batch fetches several items in one call:
sweets msg batch --window 42 --output DP-1 --workspace 2Actions
sweets msg focus left
sweets msg move down
sweets msg switch-workspace 3
sweets msg cycle-workspace next
sweets msg cycle-workspace previous
sweets msg move-to-workspace 4
sweets msg workspace-previous
sweets msg focus-output right
sweets msg focus-output-id DP-2
sweets msg move-to-output left
sweets msg toggle-floating
sweets msg toggle-fullscreen
sweets msg toggle-maximize
sweets msg minimize
sweets msg restore-minimized
sweets msg special-toggle [NAME]
sweets msg close
sweets msg force-closeDirections are left, right, up, and down.
For Waybar's ext/workspaces module:
"on-scroll-up": "sweets msg cycle-workspace next",
"on-scroll-down": "sweets msg cycle-workspace previous"Keyboard layout
Choose a layout from sweets msg keyboard or cycle through them:
sweets msg keyboard-layout 0
sweets msg keyboard-layout next
sweets msg keyboard-layout previousIndices start at zero, matching keyboard.active_layout.
Lua's keyboard_layout binding uses one-based indices.
Choosing the active layout returns changed: false.
For a panel language indicator, subscribe to keyboard and query again after each event.
With track_layout = "window", each window remembers its own choice.
IPC layout changes are refused while the screen is locked.
By monitor ID
A monitor picker can select the exact ID returned by sweets msg outputs:
sweets msg focus-output-id DP-2IDs are case-sensitive. A missing, disabled or powered-off monitor returns an error.
Selecting the current monitor returns changed: false.
Pointer movement follows your pointer settings.
Place a floating window
Resize or place a visible floating window without changing focus:
sweets msg set-window-floating-geometry 42 width=0.5 height=300 anchor=bottom-right x=12 y=12
sweets msg set-window-floating-geometry 42 height=400| Field | Default | Effect |
|---|---|---|
width, height | Current size | Content size. Values through 1 are work-area fractions; larger values are logical pixels, up to 16384. |
anchor | Current position | center, top-left, top, top-right, left, right, bottom-left, bottom, or bottom-right. |
x, y | 0 | Inward offsets from the anchor, in the same units. Requires anchor. |
Use an ID from sweets msg windows. Provide at least one size or anchor.
Placement uses that window's monitor. Window size limits still apply.
Hidden, minimized, tiled, maximized, or fullscreen windows cannot use this command.
Changes are refused during a pointer grab or screen lock.
By window ID
These act on a window without focusing it first:
sweets msg focus-window 42
sweets msg close-window 42
sweets msg move-window-to-workspace 42 3
sweets msg move-window-to-workspace 42 3 DP-2
sweets msg move-window-to-output-id 42 DP-2
sweets msg set-window-floating 42 on
sweets msg set-window-pinned 42 on
sweets msg set-window-urgent 42 on
sweets msg window-keep-awake 42 on
sweets msg set-window-minimized 42 off
sweets msg set-window-maximized 42 on
sweets msg set-window-fullscreen 42 onfocus-window works like clicking a taskbar entry: it restores the window and
switches to its workspace. It also reveals hidden named tools and their dialogs.
In a special workspace showing one family, selecting a hidden member selects
that family.
set-window-pinned 42 on keeps a floating window on screen across workspace
switches. Use off to unpin it. The window stays on its current workspace.
set-window-urgent 42 on marks a window for attention without focusing it.
Use off to clear the mark. Focusing the window also clears it.
window-keep-awake 42 on keeps the session awake while that window is visible.
Use reset to remove this temporary choice. The window query reports it as
keep_awake. Hiding the window or locking the session pauses its effect.
The choice survives config reloads and ends when the window unmaps or closes.
Reset leaves application and window-rule inhibition in place.
Layout
sweets msg layout grid
sweets msg cycle-layout
sweets msg reset-layout all
sweets msg cycle-master-position
sweets msg resize horizontal growOutput rotation
sweets msg output-transform DP-2 rotate90Find the exact output ID and its current transform with sweets msg outputs.
Save that value and use it to restore the original orientation afterward.
Use normal, rotate90, rotate180, rotate270, flipped, flipped90,
flipped180, or flipped270. Other monitor settings stay in place.
A config reload restores your configured settings.
The monitor must be enabled and powered on, and the session must be active and unlocked. A rotation that would overlap another monitor is refused.
Show what the display redraws
sweets msg debug-damage on
sweets msg debug-damage offChanged regions light up red until the next redraw. Screenshots, recordings, and the lock screen omit the tint. Sweets composites every output while this is on, which disables direct scanout.
The tint can flash rapidly. Avoid this tool if flashing images can trigger symptoms for you.
Session
sweets msg reload
sweets msg gaming-mode toggle
sweets msg output-power DP-1 off
sweets msg set-binding-mode resize
sweets msg reset-binding-mode
sweets msg quit --close-windows
sweets msg quitoutput-power turns one monitor on or off without moving its windows.
Use '*' for all enabled monitors, including those already turned off:
sweets msg output-power '*' off
sweets msg output-power '*' onQuote '*' to keep the shell from expanding it. These commands work while locked.
Monitors disabled in your config stay disabled.
If one monitor fails, Sweets still tries the others and reports an error.
Successful changes remain applied.
set-binding-mode enters a mode from your config. Names match exactly.
Use default or reset-binding-mode to return to normal bindings.
Mode changes are refused while the screen is locked.
quit --close-windows asks applications to close and waits while you save
your work. A notice counts the windows still open. If the wait expires, Sweets
stays open. Run the same command again to quit immediately. Locking the
screen cancels the wait.
quit starts shutdown immediately, with no confirmation.
Sweets releases window and graphics resources before ending the session.
While the screen is locked, output-power and plain quit remain available.
Events
subscribe prints one line per change:
sweets msg subscribe workspace window
sweets msg subscribe all| Event | When |
|---|---|
focus | Focus changes |
window | A window opens, closes, or moves |
window_metadata | A title or icon changes |
scratchpad | Named tool inspection changes, including pending startup and retired definitions |
capture | The live capture list changes |
layer | A panel or launcher appears, disappears, or changes |
workspace | Workspaces change |
output | Monitors change |
input | Input devices change |
input_activity | The physical device being used changes |
keyboard | The keyboard layout changes |
status | Selected monitor, gaming mode, binding mode, or shortcut inhibition changes |
config | The config reloads |
lock | The screen locks or unlocks |
shutdown | Sweets is exiting |
An event says what changed, not the new value. Query again to get it. For a panel:
- Subscribe.
- Query the current state.
- On each event, query again.
Watching panels and launchers
sweets msg subscribe layer
sweets msg layersEach layer event contains layers, a list of changed IDs. Query layers
again to get their current state. Removed IDs may already be absent.
Events cover geometry, monitor, layer, appearance, and keyboard-interactivity changes. Keyboard interactivity describes what a panel can request, not whether it has focus. Repainting or animating alone sends no event.
Reconnecting
Each event has a sequence number. After a disconnect, resume from the last
one you handled:
sweets msg resume-events 37 workspace windowIf Sweets returns too_old, query the full state again.
Wire protocol
Protocol 90 adds the captures query and capture event.
Earlier protocol frames are refused. Check sweets msg version for capabilities.
To talk to the socket without sweets msg, connect to $SWEETS_SOCKET. Send
one newline-terminated JSON request per connection, then read its response.
Keep the write side open while waiting, the newline completes the request.
Subscriptions keep the same connection open for events.
{"version":92,"id":7,"request":{"workspace":{"number":3,"output":"DP-2"}}}
{"version":92,"id":8,"request":{"action":{"move_window_to_output_id":{"window":42,"output":"DP-2"}}}}
{"version":92,"id":10,"request":{"action":{"move_window_to_workspace":{"window":42,"workspace":3,"output":"DP-2"}}}}
{"version":92,"id":11,"request":{"action":{"set_window_urgent":{"window":42,"urgent":true}}}}
{"version":92,"id":9,"request":"pointer"}Responses use the same id:
{"version":92,"id":9,"outcome":{"status":"success","value":{"type":"pointer","data":{"x":640.0,"y":360.0,"output":"DP-2"}}}}version must match the running compositor exactly. Check it with
sweets msg version.
Errors are invalid_frame, invalid_request, unsupported_version,
limit_exceeded, locked, not_found, ambiguous, too_old,
unavailable, and internal.
Exit codes
| Code | Meaning |
|---|---|
0 | Success, including when nothing changed |
2 | Wrong command usage |
3 | Can't find or connect to the socket |
4 | Server or protocol error |
Render deadline diagnostics
sweets msg frame OUTPUT shows whether the render deadline is active.
Compare render_deadline_misses before and after normal use to check a budget.
See Monitor render deadline for tuning.
Named scratchpad windows report their workspace as { "scratchpad": "terminal" }.
Special workspace collections continue to use { "special": "name" }.