Sweets

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 window

Most 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

CommandReturns
pick-windowClick a window to get its ID
windows, window IDWindows: app ID, title, workspace, monitor, target geometry, state, tab group
workspaces, workspace NUMBER [OUTPUT]Workspaces: monitor, active, urgent, layout, windows
outputs, output IDMonitors: modes, position, scale, power, VRR
inputs, input IDInput devices and their settings
input-activityLast published physical device in an active identification session
layersPanels, launchers, and other layer surfaces
special-workspaceSpecial workspaces and their windows
scratchpads, scratchpad NAMENamed tools: active/retired state, startup, family IDs, shown host and visibility intent
capturesLive screen and window captures
keyboardKeyboard layouts and the active one
pointerPointer position
statusSelected monitor, Overview, lock, gaming mode, binding mode, shortcut inhibition
configConfig sources, reload state, watch coverage, and the last error
binds [MODE]All bindings, with desktop and active-layout shortcuts labeled
window-rule IDWhich window rules matched a window
window-appearance IDA window's resolved opacity, blur, border, and shadow
window-icon ID [SIZE]A window's icon pixels, base64
xwaylandXWayland status
frames, frame OUTPUTFrame timing and direct scanout per monitor
versionCompositor and IPC version
system-infoOS, 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_plane is direct_scanout or composited for the last completed native frame. Native HDR uses a composited primary plane.
  • cursor_plane is hardware or software for that frame, or null if the monitor showed no cursor.
  • direct_scanout_frames counts 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-info

The 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 --json

Pick a window

sweets msg pick-window

Left-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 status

Repeating 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 config

If 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-input

Sweets 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 capture

Each 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.rgba

Window process IDs

windows, window ID, and batch window results include pid.

sweets msg window 42 | jq .data.pid

The 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.parent

A 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_recency

Higher 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 2

Actions

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-close

Directions 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 previous

Indices 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-2

IDs 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
FieldDefaultEffect
width, heightCurrent sizeContent size. Values through 1 are work-area fractions; larger values are logical pixels, up to 16384.
anchorCurrent positioncenter, top-left, top, top-right, left, right, bottom-left, bottom, or bottom-right.
x, y0Inward 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 on

focus-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 grow

Output rotation

sweets msg output-transform DP-2 rotate90

Find 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 off

Changed 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 quit

output-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 '*' on

Quote '*' 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
EventWhen
focusFocus changes
windowA window opens, closes, or moves
window_metadataA title or icon changes
scratchpadNamed tool inspection changes, including pending startup and retired definitions
captureThe live capture list changes
layerA panel or launcher appears, disappears, or changes
workspaceWorkspaces change
outputMonitors change
inputInput devices change
input_activityThe physical device being used changes
keyboardThe keyboard layout changes
statusSelected monitor, gaming mode, binding mode, or shortcut inhibition changes
configThe config reloads
lockThe screen locks or unlocks
shutdownSweets is exiting

An event says what changed, not the new value. Query again to get it. For a panel:

  1. Subscribe.
  2. Query the current state.
  3. On each event, query again.

Watching panels and launchers

sweets msg subscribe layer
sweets msg layers

Each 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 window

If 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

CodeMeaning
0Success, including when nothing changed
2Wrong command usage
3Can't find or connect to the socket
4Server 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" }.

On this page