niri/wiki/IPC.md

You can communicate with the running niri instance over an IPC socket. Check niri msg --help for available commands.

The --json flag prints the response in JSON, rather than formatted. For example, niri msg --json outputs.

For programmatic access, check the niri-ipc sub-crate which defines the types. The communication over the IPC socket happens in JSON.

Tip

If you're getting parsing errors from niri msg after upgrading niri, make sure that you've restarted niri itself. You might be trying to run a newer niri msg against an older niri compositor.

Backwards Compatibility

The JSON output should remain stable, as in:

• existing fields and enum variants should not be renamed
• non-optional existing fields should not be removed

However, new fields and enum variants will be added, so you should handle unknown fields or variants gracefully where reasonable.

I am not 100% committing to the stability yet because there aren't many users, and there might be something basic I had missed in the JSON output design.

The formatted/human-readable output (i.e. without --json flag) is not considered stable. Please prefer the JSON output for scripts, since I reserve the right to make any changes to the human-readable output.

The niri-ipc sub-crate (like other niri sub-crates) is not API-stable in terms of the Rust semver; rather, it follows the version of niri itself. In particular, new struct fields and enum variants will be added.