feat(cli): komorebic

The daemon answers on its socket, but a person has no way to write a message on
it. komorebic is that way: each subcommand that asks something of the daemon is
one message, sent with komorebi-client, and a question's answer is printed.
komorebic is a separate program because the daemon takes no input but its
socket, so a key binding, a script and a terminal all drive it the same way.

It has what the daemon can answer so far: state, monitor-information, query,
retile and stop. Around them, start runs the komorebi on the PATH in the
background and passes it what follows a --, such as --fake-backend to try it
without a compositor; log follows the daemon's log, which the daemon now writes
to a file a day in LOG_DIR as well as to stdout; data-directory shows where the
socket is; completions prints a shell completion script. The hidden docgen
writes each subcommand's help to docs/cli, in fences that name their language
and wrapped at 100 columns whatever the width of the terminal, so that the pages
are the same wherever they are generated; just docgen runs it.

The user guide starts here: docs/index.md for KDE Plasma, and a page on running
komorebi. tests/cli.rs runs each subcommand against a socket the test serves in
place of the daemon. In the VM tests the guests get komorebic next to the
daemon, and vm-core-e2e reads the daemon's state with it (the windows it
manages, the one it focuses, after KWin restarts too) and stops it with
komorebic stop, which unloads the bridge and removes the socket.

In the VM test library, Kde.state asks again, a second (times the scale) after
an empty answer or a failed command, up to 10 times. The daemon drops a query
when it cannot take hold of the window manager within a second, and komorebic
then prints an empty line and succeeds; komorebic itself gives the daemon a
second to answer and fails when that is not enough. A daemon busy with the first
windows does either on a machine that is loaded or slow, and a suite that polled
the state died on JSONDecodeError. An answer that is not JSON still fails at
once.
This commit is contained in:
LGUG2Z committed 2026-10-28 07:20:37 -07:00
1 parent 88aa78b874
commit 6f657e53e3
36 files changed
+1320 -39

No files matched your search

+14
View File
@@ -0,0 +1,14 @@
```text
Generate komorebic CLI completions for the target shell
Usage: completions <SHELL>
Arguments:
<SHELL>
[possible values: bash, elvish, fish, powershell, zsh]
Options:
-h, --help
Print help
```
+10
View File
@@ -0,0 +1,10 @@
```text
Show the path to komorebi's data directory, which has its socket
Usage: data-directory
Options:
-h, --help
Print help
```
+10
View File
@@ -0,0 +1,10 @@
```text
Tail komorebi's process logs (cancel with Ctrl-C)
Usage: log
Options:
-h, --help
Print help
```
+10
View File
@@ -0,0 +1,10 @@
```text
Show information about connected monitors
Usage: monitor-information
Options:
-h, --help
Print help
```
+15
View File
@@ -0,0 +1,15 @@
```text
Query the current window manager state
Usage: query <STATE_QUERY>
Arguments:
<STATE_QUERY>
[possible values: focused-monitor-index, focused-workspace-index, focused-container-index,
focused-window-index, focused-workspace-layout, focused-container-kind, version]
Options:
-h, --help
Print help
```
+10
View File
@@ -0,0 +1,10 @@
```text
Force the retiling of all managed windows
Usage: retile
Options:
-h, --help
Print help
```
+14
View File
@@ -0,0 +1,14 @@
```text
Start komorebi as a background process
Usage: start [-- <KOMOREBI_ARGS>...]
Arguments:
[KOMOREBI_ARGS]...
Arguments to pass to komorebi, after a `--`: `komorebic start -- --log-level debug`
Options:
-h, --help
Print help
```
+10
View File
@@ -0,0 +1,10 @@
```text
Show a JSON representation of the current window manager state
Usage: state
Options:
-h, --help
Print help
```
+10
View File
@@ -0,0 +1,10 @@
```text
Stop the komorebi process
Usage: stop
Options:
-h, --help
Print help
```