IPC Reference

halleyctl and IPC

Versioned command and response reference for Halley's local IPC socket. This page is showing v0.2.0.

Transport

Local socket

halleyctl talks to the running compositor over a framed Unix socket. Use --json on inspection commands when scripts need structured output.

Default path $XDG_RUNTIME_DIR/halley/halley.sock
No Halley-specific override yet. To change the derived location, launch both Halley and halleyctl with the same XDG_RUNTIME_DIR.
ipc examples 
XDG_RUNTIME_DIR=/run/user/1000 halleyctl outputs --json
halleyctl node list --json
halleyctl cluster inspect current --json

Commands

Command Surface

Compositor

Session-level compositor requests and output state.

halleyctl quit

Ask the running compositor to exit.

halleyctl reload

Reload Halley configuration.

halleyctl outputs

Print output state.

JSON
halleyctl dpms off|on|toggle [-o OUTPUT]

Set or toggle output power state.

Capture

Start Halley-native screenshot capture modes.

halleyctl capture menu

Open the native capture menu.

halleyctl capture region [-o OUTPUT]

Start region capture.

halleyctl capture screen [-o OUTPUT]

Capture an output.

halleyctl capture window [-o OUTPUT]

Start window capture.

Nodes

Inspect, focus, move, and close windows represented as Halley nodes.

halleyctl node list [-o OUTPUT] [--json]

List nodes by output.

JSON
halleyctl node info [SELECTOR] [-o OUTPUT] [--json]

Inspect a selected node.

JSON
halleyctl node focus [SELECTOR] [-o OUTPUT]

Focus a selected node.

halleyctl node move left|right|up|down [SELECTOR] [-o OUTPUT]

Move a node in field space.

halleyctl node close [SELECTOR] [-o OUTPUT]

Close a selected node.

Trail

Navigate the focus trail for the focused or selected output.

halleyctl trail prev [-o OUTPUT]

Focus the previous trail entry.

halleyctl trail next [-o OUTPUT]

Focus the next trail entry.

halleyctl trail list [-o OUTPUT] [--json]

List trail entries.

JSON
halleyctl trail goto <TARGET> [-o OUTPUT]

Focus a trail index or node selector.

Monitor

Move focus between configured outputs.

halleyctl monitor focus <left|right|up|down|OUTPUT>

Focus an adjacent monitor or named output.

Bearings

Control the bearings overlay.

halleyctl bearings show

Show bearings.

halleyctl bearings hide

Hide bearings.

halleyctl bearings toggle

Toggle bearings.

halleyctl bearings status

Print current bearings visibility.

Clusters

Inspect and manipulate cluster workspaces.

halleyctl cluster list [-o OUTPUT] [--json]

List clusters by output.

JSON
halleyctl cluster inspect [current|ID] [-o OUTPUT] [--json]

Inspect the active cluster or an id.

JSON
halleyctl cluster layout cycle [-o OUTPUT]

Toggle the active cluster layout.

halleyctl cluster slot <1-10> [-o OUTPUT]

Activate or toggle the cluster in a numbered slot.

Stack

Navigate active stacking decks.

halleyctl stack cycle forward [-o OUTPUT]

Cycle the active stack forward.

halleyctl stack cycle backward [-o OUTPUT]

Cycle the active stack backward.

Tile

Move focus or swap tiles inside active tiled layouts.

halleyctl tile focus left|right|up|down [-o OUTPUT]

Move focus to an adjacent visible tile.

halleyctl tile swap left|right|up|down [-o OUTPUT]

Swap the focused tile with an adjacent visible tile.

Selectors

Node Targets

Node commands and trail goto accept these selectors where a target is needed.

focused

The currently focused node.

latest

The most recently active matching node.

id:<id>

A session-scoped numeric node id.

title:<text>

A title substring match.

app:<app-id>

An app id match.

Responses

JSON Shapes

Important structured response fields exposed by --json commands.

NodeInfo

idtitleapp_idoutputkindstatevisiblefocusedlatestroleprotocol_familymodalparenttransient_forchild_popup_countpos_xpos_ywidthheight

ClusterSummary

slotidnameoutputlayoutmember_countactivefocused

ClusterInfo

slotidnameoutputlayoutmember_countactivefocusedfocused_member_indexfocused_member_idmembers