Next: (maak nix), Previous: (maak net), Up: API
Helpers for talking to a running niri compositor through ‘niri msg’. A task that changes the session – focus a workspace, spawn a program, put a window on another output – can do it in a line rather than in a shell string, and a task that reads the session can ask for JSON and parse it.
Two families are exported. The queries (‘niri-outputs‘, ‘niri-workspaces‘, ‘niri-windows’, ...) are ordinary commands; ‘niri-capture‘ runs any of them and returns what niri printed, which is what a task needs for a decision. The actions (‘niri-focus-workspace‘, ‘niri-spawn‘, ...) are thin wrappers over ‘niri msg action’.
Every helper has an ‘-argv‘ builder where the command has options worth asserting on. The builders are what ‘–dry-run‘ prints and what the tests exercise; no compositor is needed to check the command line.
‘niri msg’ is deliberately not started when this module loads. A task that needs niri checks ‘niri-available?’ first, or lets the missing program be reported by ‘run’ as exit code 127.
Send ARGUMENTS to ‘niri msg’.
This is the escape hatch for subcommands and flags without a wrapper. Nothing is handed to a shell, so a program name or a workspace name with a space in it reaches niri as one argument.
A command that exits non-zero raises a maak error, unless ALLOW-FAILURE? is #t, in which case the call answers #f – the usual ‘run’ contract.
Perform an action with ARGUMENTS, through ‘niri msg action’.
A bare action name is enough for the ones that take no argument, such as
close-window; the others take their reference after it.
(niri-action (list "focus-workspace" "2")) (niri-action (list "spawn" "--" "foot" "-e" "htop"))
Return the argv that performs an action with its ARGUMENTS.
The action name comes first and its own flags follow, so
("focus-workspace" "2") is the argv for ‘focus-workspace 2’.
Return the argv that sends ARGUMENTS to ‘niri msg‘.
With JSON? the global --json flag is inserted before the
subcommand, which is where niri expects it. ARGUMENTS is the subcommand
and its flags: ("outputs"), ("action" "close-window"), and
so on.
Return #t when the niri program can be found on PATH.
Send ARGUMENTS to ‘niri msg’ and return what it printed.
This is the query form: the output is a string a task can trim, split or hand to a JSON parser, rather than a line on the terminal. In dry-run mode nothing runs, the command is printed, and the empty string comes back.
List the screencasts.
Close the focused window.
Focus the column at INDEX.
Focus the monitor NAME.
Focus the window with ID.
Focus the previously focused window.
Focus the workspace REFERENCE, an index or a name.
Focus the previous workspace.
Print information about the focused output.
Print information about the focused window.
Toggle fullscreen on the focused window.
Print the configured keyboard layouts.
List the open layer-shell surfaces.
Move the focused column to the monitor NAME.
Move the focused column to the workspace REFERENCE.
Move the focused window to the monitor NAME.
Move the focused window, or WINDOW-ID, to the workspace REFERENCE.
FOCUS is default unless given: with #t the focus follows the
window, and with #f it stays on the original workspace, which niri
spells as --focus true and --focus false.
Change OUTPUT with ACTION and ARGUMENTS; see ‘niri-output-argv’.
The change is temporary and is not written to niri’s configuration file.
Return the argv that changes OUTPUT with ACTION and ARGUMENTS.
The output name comes first and the action after it, which is the order
‘niri msg output’ requires: niri msg output DP-1 mode
1920x1080@60.
(niri-output-argv "DP-1" "scale" "1.5")
Set OUTPUT’s mode, such as 1920x1080@60.
Turn OUTPUT off.
Turn OUTPUT on.
Set OUTPUT’s position on the desktop to X and Y.
Set OUTPUT’s scale, such as 1.5.
Set OUTPUT’s transform, such as 90 or flipped-180.
List the connected outputs.
Print the overview state.
Pick a color from the screen with the mouse.
Pick a window with the mouse and print information about it.
Power off all monitors via DPMS.
Power on all monitors via DPMS.
Exit niri.
SKIP-CONFIRMATION? is the default because a task that asks niri to quit is not sitting at a keyboard to press Enter.
Ask niri to return an error, which is useful for checking a client’s error handling against a live compositor.
Open the screenshot UI.
Screenshot the focused screen.
Screenshot the focused window.
Change the width of the focused column by CHANGE.
Change the width of the focused window, or of window ID, by CHANGE.
CHANGE is a string such as +10% or 500, exactly as niri’s
command line takes it.
Set the name of the focused workspace to NAME.
Spawn COMMAND, a list of strings, without a shell.
The -- that separates niri’s own flags from the program is added
here, so a program with a flag that looks like niri’s is still passed
through.
Spawn COMMAND through the shell.
Use ‘niri-spawn’ when the program and its arguments are already separate strings; this one is for a line that needs a shell.
Toggle the overview.
Toggle windowed (fake) fullscreen on the focused window.
Unset the name of the focused workspace.
Print the version of the running niri instance.
List the open windows.
List the workspaces.
Next: (maak nix), Previous: (maak net), Up: API