feresaria/docs/ipc.md

feresectl and IPC events

feresectl controls a running Ferese session. Run feresectl --help for commands and feresectl COMMAND --help for arguments.

Queries

Queries print plain text by default. Add -j or --json when passing results to another program. The flag works before or after a subcommand.

feresectl outputs
feresectl windows -j
feresectl -j workspaces
feresectl focused-window
feresectl idle-inhibition
feresectl keybindings
feresectl session-state
feresectl output-profiles
feresectl theme get
feresectl xwayland status
feresectl media

The get-* spellings remain hidden aliases for the corresponding queries and print a deprecation warning on stderr. They use the same output rules: scripts that previously parsed their JSON must add -j. New scripts should use the canonical names. The aliases will be removed in a later release.

Screenshots still write PNG bytes to stdout, including when -j is present:

feresectl screenshot > desktop.png
feresectl screenshot -g '0,0 800x600' > region.png
feresectl screenshot-window 7 > window.png

Window focus

feresectl focus-floating

focus-floating focuses the most recently focused window in the opposite tiled/floating layer on the active workspace. It does nothing when that layer has no candidate. toggle-floating changes placement; focus-floating changes focus.

feresectl move left|right|up|down and feresectl resize left|right|up|down also handle floating windows. Moves use 32 logical pixels. Resizing shrinks width/height with left/up and grows them with right/down by 32 logical pixels, subject to client size limits. Fullscreen and maximized floating windows ignore these actions.

Choose a session

Every feresectl IPC command, including theme commands and subscriptions, resolves its target in this order:

1. --socket PATH
2. A nonempty FERESE_SOCKET
3. $XDG_RUNTIME_DIR/ferese/control.sock

feresectl --socket "$XDG_RUNTIME_DIR/ferese/instances/12345-abcdef/control.sock" outputs
FERESE_SOCKET="$XDG_RUNTIME_DIR/ferese/instances/12345-abcdef/control.sock" feresectl theme get -j

--socket selects an existing server; it does not create one or change where the compositor listens. DRM uses $XDG_RUNTIME_DIR/ferese/control.sock. Nested instances use $XDG_RUNTIME_DIR/ferese/instances/<id>/control.sock; copy the actual path from the compositor's startup log. Each instance removes its own socket and directory on normal shutdown. A forced kill can leave the directory behind; later instances allocate a different one.

Clients launched by a nested compositor inherit its FERESE_SOCKET, so feresectl outputs inside that session connects to that instance. autostart launches desktop entries locally and does not use IPC.

Connection lifetimes

The server permits 64 simultaneous connections. A new connection must begin its first request within five seconds; each frame then has five seconds to finish. Ordinary connections close after 30 idle seconds and blocked response writes expire after two seconds. These bounds release slots held by stalled clients. Accepted portal leases remain connected while idle, and pending long polls and event subscriptions do not have the ordinary idle deadline.

Follow changes

feresectl event-stream
feresectl --socket "$XDG_RUNTIME_DIR/ferese/instances/12345-abcdef/control.sock" event-stream

event-stream writes one JSON value per line and flushes each line. It always uses JSON, so -j is optional. theme subscribe also keeps its newline-delimited JSON output.

The first event is a snapshot containing outputs, workspaces, windows, focus, config status, the logical theme, and lock state. Later events contain replacement values for changed domains:

Type	Payload field
outputs_changed	outputs
workspaces_changed	workspaces
windows_changed	windows
focus_changed	focus
config_changed	config
theme_changed	theme
lock_changed	lock

For example:

{"version":1,"generation":12,"last":true,"type":"focus_changed","focus":{"window":7,"output":1,"workspace":3}}

Event schema version 1 is defined in ferese-ipc::events, independently of the command protocol version. A subscriber requests that version using the framed event-stream command. The server sends a normal response acknowledging the subscription, followed by framed events on the same connection. That connection is then reserved for events.

Changes are sampled after an event-loop dispatch. Output reconciliation must finish before a desktop generation is published. Events from the same dispatch share a generation; only its final event has last: true. Consumers maintaining a desktop model should apply the whole generation together. Intermediate changes within a dispatch are coalesced, so this stream is not an audit log of every input or mutation. Generation numbers may have gaps.

Window events describe identity, title, activation, workspace, floating state, and fullscreen state. They omit visual geometry, animation frames, and client damage. Theme events omit the presented crossfade state and its frame revisions. Config revisions advance when a changed configuration is accepted; rejected reloads leave that revision intact and report an error. Lock events distinguish unlocked, acquiring, locked, and orphaned, and include display sleep state. While locked, snapshots and replacement events redact windows, workspaces, focus, and output workspace/focus fields. Unlocking restores those domains.

Delivery limits

The compositor allows at most 16 event subscribers within its existing limit of 64 IPC connection workers. Each subscriber has a queue of at most 32 events. Publishing uses non-blocking sends. A full or disconnected queue removes that subscriber; socket writes happen on its worker with a two-second write timeout. Idle disconnected streams are checked every 250 milliseconds.

Events are not replayed. An overflow can end a stream partway through a generation. Discard any generation without last: true, reconnect, and replace local state with the new initial snapshot. Socket authentication and the existing one-MiB frame limit also apply to event streams.

When there are no subscribers, event publication does not build desktop snapshots. With subscribers, it compares logical domain snapshots after each dispatch. Ordinary damage, cursor movement, and redraw code do not publish events directly.