IPC Reference

halleyctl and IPC

Versioned command and response reference for Halley's local IPC socket. This page is showing v0.7.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
halleyctl node list --json
halleyctl cluster info current --json

Commands

Command Surface

Compositor

Session-level compositor requests and output state.

halleyctl quit

Open Halley's compositor-owned exit confirmation.

halleyctl reload

Reload Halley configuration.

halleyctl outputs

Print connected outputs, modes, positions, VRR support, and current state.

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

Set or toggle output power state.

Configuration

Edit, verify, migrate, or reload the selected Rune configuration.

halleyctl config edit [-c PATH|--config PATH]

Open the selected config with $VISUAL, $EDITOR, or vi.

halleyctl config verify [-c PATH|--config PATH]

Strictly parse and validate a complete config without applying it.

halleyctl config migrate [--dry-run] [-c PATH|--config PATH]

Apply versioned compatibility entries, validate the result, and retain a timestamped backup. Dry-run prints the proposed result.

Capture

Start Halley-native screenshot capture modes.

halleyctl capture menu [-o OUTPUT]

Open the native capture menu, optionally on an exact output.

halleyctl capture region [-o OUTPUT]

Start region capture.

halleyctl capture screen [-o OUTPUT]

Capture an output.

halleyctl capture window [-o OUTPUT]

Start window capture.

Portal

Inspect Halley's native desktop portal backend.

halleyctl portal status [--json]

Check portal backend discovery, compositor IPC, advertised sources, cursor modes, and version details.

JSON
halleyctl portal version [--json]

Print the installed portal backend and running compositor versions.

JSON

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 collapse [SELECTOR] [-o OUTPUT]

Collapse a selected surface into a node.

halleyctl node restore [SELECTOR] [-o OUTPUT]

Restore a collapsed node to a live surface.

halleyctl node toggle [SELECTOR] [-o OUTPUT]

Toggle a selected surface between live and collapsed states.

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 info [current|ID|id:ID] [-o OUTPUT] [--json]

Inspect the active cluster or an id. inspect remains an accepted alias.

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_idoutputkindstatevisiblefocusedlatestpinnedroleprotocol_familymodalparenttransient_forchild_popup_countxywidthheight

ClusterSummary

idslotnameoutputlayoutmember_countactivefocused

ClusterInfo

summarycore_node_idmembers

TrailInfo

outputcursor_indexentries

OutputInfo

namemodescurrent_modeoffset_xoffset_yvrrvrr_supportedvrr_active