Crate niri_ipc 

Types for communicating with niri via IPC.

After connecting to the niri socket, you can send Requests. Niri will process them one by one, in order, and to each request it will respond with a single Reply, which is a Result wrapping a Response.

If you send a Request::EventStream, niri will stop reading subsequent Requests, and will start continuously writing compositor Events to the socket. If you’d like to read an event stream and write more requests at the same time, you need to use two IPC sockets.

Requests are always processed separately. Time passes between requests, even when sending multiple requests to the socket at once. For example, sending Request::Workspaces and Request::Windows together may not return consistent results (e.g. a window may open on a new workspace in-between the two responses). This goes for actions too: sending Action::FocusWindow and Action::CloseWindow { id: None } together may close the wrong window because a different window got focused in-between these requests.

You can use the socket::Socket helper if you’re fine with blocking communication. However, it is a fairly simple helper, so if you need async, or if you’re using a different language, you are encouraged to communicate with the socket manually.

1. Read the socket filesystem path from socket::SOCKET_PATH_ENV ($NIRI_SOCKET).
2. Connect to the socket and write a JSON-formatted Request on a single line. You can follow up with a line break and a flush, or just flush and shutdown the write end of the socket.
3. Niri will respond with a single line JSON-formatted Reply.
4. You can keep writing Requests, each on a single line, and read Replys, also each on a separate line.
5. After you request an event stream, niri will keep responding with JSON-formatted Events, on a single line each.

Backwards compatibility

This crate follows the niri version. It is not API-stable in terms of the Rust semver. In particular, expect new struct fields and enum variants to be added in patch version bumps.

Use an exact version requirement to avoid breaking changes:

[dependencies]
niri-ipc = "=25.11.0"

Features

This crate defines the following features:

• json-schema: derives the schemars JsonSchema trait for the types.
• clap: derives the clap CLI parsing traits for some types. Used internally by niri itself.

Modules

socket

Helper for blocking communication over the niri socket.

state

Helpers for keeping track of the event stream state.

Structs

ConfiguredMode

Output mode as set in the config file.

ConfiguredPosition

Output position as set in the config file.

KeyboardLayouts

Configured keyboard layouts.

LayerSurface

A layer-shell surface.

LogicalOutput

Logical output in the compositor’s coordinate space.

Mode

Output mode.

Output

Connected output.

Overview

Overview information.

PickedColor

Color picked from the screen.

Timestamp

A moment in time.

VrrToSet

Output VRR to set.

Window

Toplevel window.

WindowLayout

Position- and size-related properties of a Window.

Workspace

A workspace.

Enums

Action

Actions that niri can perform.

ColumnDisplay

How windows display in a column.

Event

A compositor event.

HSyncPolarity

Modeline horizontal syncing polarity.

Layer

A layer-shell layer.

LayerSurfaceKeyboardInteractivity

Keyboard interactivity modes for a layer-shell surface.

LayoutSwitchTarget

Layout to switch to.

ModeToSet

Output mode to set.

OutputAction

Output actions that niri can perform.

OutputConfigChanged

Output configuration change result.

PositionChange

Change in floating window position.

PositionToSet

Output position to set.

Request

Request from client to niri.

Response

Successful response from niri to client.

ScaleToSet

Output scale to set.

SizeChange

Change in window or column size.

Transform

Output transform, which goes counter-clockwise.

VSyncPolarity

Modeline vertical syncing polarity.

WorkspaceReferenceArg

Workspace reference (id, index or name) to operate on.

Type Aliases

Reply

Reply from niri to client.