docs: add book

2026-03-20 19:14:07 +01:00 · 2026-03-20 19:14:07 +01:00 · d14105eb1a
commit d14105eb1a
parent c9d6fb9e40
43 changed files with 7254 additions and 1204 deletions
--- a/book/src/cli.md
+++ b/book/src/cli.md
@ -0,0 +1,663 @@
+# Command-Line Interface
+
+Jay provides a comprehensive CLI for controlling the compositor, managing
+displays, input devices, clients, and more. All subcommands communicate with
+the running compositor over the Wayland protocol unless otherwise noted.
+
+> [!TIP]
+> Generate shell completions for tab-completion support:
+>
+> ```shell
+> ~$ jay generate-completion bash > ~/.local/share/bash-completion/completions/jay
+> ~$ jay generate-completion zsh > ~/.zfunc/_jay
+> ~$ jay generate-completion fish > ~/.config/fish/completions/jay.fish
+> ~$ jay generate-completion elvish  # pipe to appropriate location
+> ~$ jay generate-completion powershell  # pipe to appropriate location
+> ```
+
+Every subcommand accepts a global `--log-level` option (`trace`, `debug`,
+`info`, `warn`, `error`, `off`) that controls the verbosity of the CLI tool itself.
+
+---
+
+## Running
+
+### `jay run`
+
+Start the compositor.
+
+```shell
+~$ jay run
+```
+
+Optionally specify which backends to try (comma-separated, tried in order):
+
+```shell
+~$ jay run --backends x11,metal,headless
+```
+
+The default order is `x11,metal`. The first backend that can be started is
+used. `metal` is the native DRM/KMS backend for bare-metal sessions.
+
+### `jay quit`
+
+Stop the running compositor.
+
+```shell
+~$ jay quit
+```
+
+### `jay pid`
+
+Print the PID of the running compositor.
+
+```shell
+~$ jay pid
+```
+
+### `jay version`
+
+Print the Jay version.
+
+```shell
+~$ jay version
+```
+
+---
+
+## Configuration
+
+### `jay config init`
+
+Generate a configuration file pre-populated with all defaults.
+
+```shell
+~$ jay config init
+```
+
+If a config already exists, pass `--overwrite` to replace it (the old file is
+backed up):
+
+```shell
+~$ jay config init --overwrite
+```
+
+> [!IMPORTANT]
+> Once a config file exists, the entire built-in default configuration is
+> replaced -- not merged. An empty config file means no shortcuts, no startup
+> actions, nothing. Always use `jay config init` to start with a working
+> configuration.
+
+### `jay config path`
+
+Print the path to the config file.
+
+```shell
+~$ jay config path
+```
+
+### `jay config open-dir`
+
+Open the configuration directory with `xdg-open`.
+
+```shell
+~$ jay config open-dir
+```
+
+---
+
+## Display & Graphics
+
+All display and GPU commands live under `jay randr`.
+
+### Showing Current Settings
+
+```shell
+~$ jay randr
+~$ jay randr show
+~$ jay randr show --modes      # include all available modes
+~$ jay randr show --formats    # include all available framebuffer formats
+```
+
+### GPU / Card Commands
+
+Set the primary (render) GPU:
+
+```shell
+~$ jay randr card card0 primary
+```
+
+Set the graphics API:
+
+```shell
+~$ jay randr card card0 api vulkan
+~$ jay randr card card0 api opengl
+```
+
+Toggle direct scanout:
+
+```shell
+~$ jay randr card card0 direct-scanout enable
+~$ jay randr card card0 direct-scanout disable
+```
+
+Adjust the page-flip margin (in milliseconds, default 1.5):
+
+```shell
+~$ jay randr card card0 timing set-flip-margin 1.5
+```
+
+### Output Commands
+
+Enable or disable an output:
+
+```shell
+~$ jay randr output DP-1 enable
+~$ jay randr output DP-1 disable
+```
+
+Set the position:
+
+```shell
+~$ jay randr output DP-1 position 1920 0
+```
+
+Set the scale (fractional scaling supported):
+
+```shell
+~$ jay randr output DP-1 scale 1.5
+~$ jay randr output DP-1 scale --round-to-float 1.333
+```
+
+Set the mode (width, height, refresh rate in Hz):
+
+```shell
+~$ jay randr output DP-1 mode 2560 1440 144.0
+```
+
+Set the transform:
+
+```shell
+~$ jay randr output DP-1 transform rotate-90
+~$ jay randr output DP-1 transform none
+```
+
+Available transforms: `none`, `rotate-90`, `rotate-180`, `rotate-270`, `flip`,
+`flip-rotate-90`, `flip-rotate-180`, `flip-rotate-270`.
+
+Override the non-desktop setting:
+
+```shell
+~$ jay randr output DP-1 non-desktop true
+~$ jay randr output DP-1 non-desktop default
+```
+
+Configure VRR (variable refresh rate):
+
+```shell
+~$ jay randr output DP-1 vrr set-mode always
+~$ jay randr output DP-1 vrr set-mode variant3
+~$ jay randr output DP-1 vrr set-cursor-hz 240
+~$ jay randr output DP-1 vrr set-cursor-hz none
+```
+
+VRR modes: `never`, `always`, `variant1` (one or more fullscreen apps),
+`variant2` (single fullscreen app), `variant3` (single fullscreen app with
+game/video content type). Pass `none` to `set-cursor-hz` to remove the cursor
+Hz cap.
+
+Configure tearing:
+
+```shell
+~$ jay randr output DP-1 tearing set-mode variant3
+```
+
+Tearing modes: `never`, `always`, `variant1` (one or more applications
+displayed fullscreen), `variant2` (single application displayed fullscreen),
+`variant3` (default -- single displayed application that requested tearing).
+
+Set the framebuffer format:
+
+```shell
+~$ jay randr output DP-1 format set xrgb8888
+```
+
+Set the output color space and EOTF (for HDR):
+
+```shell
+~$ jay randr output DP-1 colors set bt2020 pq
+~$ jay randr output DP-1 colors set default default
+```
+
+Set the brightness (in cd/m^2, or `default`):
+
+```shell
+~$ jay randr output DP-1 brightness 203
+~$ jay randr output DP-1 brightness default
+```
+
+Set the blend space:
+
+```shell
+~$ jay randr output DP-1 blend-space linear
+~$ jay randr output DP-1 blend-space srgb
+```
+
+Enable or disable native gamut usage:
+
+```shell
+~$ jay randr output DP-1 use-native-gamut true
+~$ jay randr output DP-1 use-native-gamut false
+```
+
+### Virtual Outputs
+
+```shell
+~$ jay randr virtual-output create my-virtual-display
+~$ jay randr virtual-output remove my-virtual-display
+```
+
+---
+
+## Input
+
+All input commands live under `jay input`.
+
+### Showing Input Devices
+
+```shell
+~$ jay input
+~$ jay input show
+~$ jay input show -v    # verbose output with device details
+```
+
+### Seat Commands
+
+Show seat information:
+
+```shell
+~$ jay input seat default show
+~$ jay input seat default show -v
+```
+
+Set keyboard repeat rate (repeats per second, initial delay in ms):
+
+```shell
+~$ jay input seat default set-repeat-rate 25 600
+```
+
+Set the keymap from RMLVO names:
+
+```shell
+~$ jay input seat default set-keymap-from-names -l de
+~$ jay input seat default set-keymap-from-names -l us -v intl -o compose:ralt
+```
+
+Set the keymap from a file (or stdin):
+
+```shell
+~$ jay input seat default set-keymap /path/to/keymap.xkb
+```
+
+Retrieve the current keymap:
+
+```shell
+~$ jay input seat default keymap > current.xkb
+```
+
+Toggle hardware cursor:
+
+```shell
+~$ jay input seat default use-hardware-cursor true
+~$ jay input seat default use-hardware-cursor false
+```
+
+Set cursor size:
+
+```shell
+~$ jay input seat default set-cursor-size 24
+```
+
+Configure the simple (XCompose-based) input method:
+
+```shell
+~$ jay input seat default simple-im enable
+~$ jay input seat default simple-im disable
+~$ jay input seat default simple-im reload
+```
+
+### Device Commands
+
+Show device information:
+
+```shell
+~$ jay input device 42 show
+```
+
+Set acceleration profile and speed:
+
+```shell
+~$ jay input device 42 set-accel-profile flat
+~$ jay input device 42 set-accel-profile adaptive
+~$ jay input device 42 set-accel-speed -0.5
+```
+
+Configure tap behavior:
+
+```shell
+~$ jay input device 42 set-tap-enabled true
+~$ jay input device 42 set-tap-drag-enabled true
+~$ jay input device 42 set-tap-drag-lock-enabled false
+```
+
+Set left-handed mode:
+
+```shell
+~$ jay input device 42 set-left-handed true
+```
+
+Set natural scrolling:
+
+```shell
+~$ jay input device 42 set-natural-scrolling true
+```
+
+Set pixels per scroll-wheel step:
+
+```shell
+~$ jay input device 42 set-px-per-wheel-scroll 30.0
+```
+
+Set the transform matrix (2x2):
+
+```shell
+~$ jay input device 42 set-transform-matrix 1.0 0.0 0.0 1.0
+```
+
+Set the calibration matrix (2x3, for touchscreens):
+
+```shell
+~$ jay input device 42 set-calibration-matrix 1.0 0.0 0.0 0.0 1.0 0.0
+```
+
+Set the click method:
+
+```shell
+~$ jay input device 42 set-click-method clickfinger
+~$ jay input device 42 set-click-method button-areas
+~$ jay input device 42 set-click-method none
+```
+
+Toggle middle button emulation:
+
+```shell
+~$ jay input device 42 set-middle-button-emulation true
+```
+
+Set a per-device keymap:
+
+```shell
+~$ jay input device 42 set-keymap /path/to/keymap.xkb
+~$ jay input device 42 set-keymap-from-names -l de
+~$ jay input device 42 keymap > device.xkb
+```
+
+Attach / detach a device from a seat:
+
+```shell
+~$ jay input device 42 attach default
+~$ jay input device 42 detach
+```
+
+Map a device to a specific output:
+
+```shell
+~$ jay input device 42 map-to-output DP-1
+~$ jay input device 42 remove-mapping
+```
+
+---
+
+## Idle & Locking
+
+### `jay idle`
+
+Show idle status, including the current interval, grace period, and active
+inhibitors:
+
+```shell
+~$ jay idle
+~$ jay idle status
+```
+
+### `jay idle set`
+
+Set the idle interval. Durations can be specified in flexible formats:
+
+```shell
+~$ jay idle set 10m
+~$ jay idle set 1m 30s
+~$ jay idle set disabled
+```
+
+### `jay idle set-grace-period`
+
+Set the grace period (screens go black but are not locked/disabled):
+
+```shell
+~$ jay idle set-grace-period 30s
+~$ jay idle set-grace-period disabled
+```
+
+### `jay unlock`
+
+Unlock the compositor. This is useful when the screen locker crashes and the
+session remains locked. Run it from another TTY or via SSH. You must set
+`WAYLAND_DISPLAY` to the socket of the Jay compositor:
+
+```shell
+~$ WAYLAND_DISPLAY=wayland-1 jay unlock
+```
+
+---
+
+## Logging
+
+### `jay log`
+
+Open the log file in `less`:
+
+```shell
+~$ jay log
+~$ jay log -f        # follow mode (like tail -f)
+~$ jay log -e        # jump to end of log
+~$ jay log --path    # print the log file path instead
+```
+
+### `jay set-log-level`
+
+Change the log level at runtime:
+
+```shell
+~$ jay set-log-level debug
+~$ jay set-log-level info
+```
+
+Available levels: `trace`, `debug`, `info`, `warn`, `error`, `off`.
+
+---
+
+## Screenshots
+
+### `jay screenshot`
+
+Take a screenshot of the entire display:
+
+```shell
+~$ jay screenshot
+~$ jay screenshot --format png
+~$ jay screenshot --format qoi
+~$ jay screenshot my-screenshot.png
+```
+
+If no filename is given, the screenshot is saved as
+`%Y-%m-%d-%H%M%S_jay.<ext>` in the current directory. The filename supports
+strftime format specifiers.
+
+---
+
+## Clients & Windows
+
+### `jay clients`
+
+List all connected clients:
+
+```shell
+~$ jay clients
+~$ jay clients show all
+```
+
+Show a specific client by ID:
+
+```shell
+~$ jay clients show id 42
+```
+
+Interactively select a window and show its client:
+
+```shell
+~$ jay clients show select-window
+```
+
+Kill a client by ID:
+
+```shell
+~$ jay clients kill id 42
+```
+
+Interactively select a window and kill its client:
+
+```shell
+~$ jay clients kill select-window
+```
+
+### `jay tree query`
+
+Inspect the compositor's surface tree:
+
+```shell
+~$ jay tree query root
+~$ jay tree query -r root                    # recursive
+~$ jay tree query -r --all-clients root      # show client details for every node
+~$ jay tree query workspace-name main
+~$ jay tree query select-workspace
+~$ jay tree query select-window
+```
+
+---
+
+## Xwayland
+
+### `jay xwayland`
+
+Show Xwayland status (scaling mode, implied scale):
+
+```shell
+~$ jay xwayland
+~$ jay xwayland status
+```
+
+### `jay xwayland set-scaling-mode`
+
+```shell
+~$ jay xwayland set-scaling-mode default
+~$ jay xwayland set-scaling-mode downscaled
+```
+
+In `downscaled` mode, X11 windows are rendered at the highest integer scale and
+then downscaled, which can improve sharpness on HiDPI displays.
+
+---
+
+## Color Management
+
+### `jay color-management`
+
+Show color management status:
+
+```shell
+~$ jay color-management
+~$ jay color-management status
+```
+
+### `jay color-management enable / disable`
+
+```shell
+~$ jay color-management enable
+~$ jay color-management disable
+```
+
+---
+
+## Other Commands
+
+### `jay control-center`
+
+Open the [Control Center](control-center.md) GUI:
+
+```shell
+~$ jay control-center
+```
+
+### `jay portal`
+
+Run the Jay desktop portal (provides screen sharing and other XDG desktop
+portal interfaces):
+
+```shell
+~$ jay portal
+```
+
+Normally the portal is started automatically. This command is for running it
+manually or debugging.
+
+### `jay seat-test`
+
+Test input events from a seat. Prints all keyboard, pointer, touch, gesture,
+tablet, and switch events to stdout:
+
+```shell
+~$ jay seat-test
+~$ jay seat-test default
+~$ jay seat-test -a              # test all seats simultaneously
+```
+
+### `jay run-privileged`
+
+Run a program with access to a privileged Wayland socket:
+
+```shell
+~$ jay run-privileged my-program --arg1
+```
+
+### `jay run-tagged`
+
+Run a program with a tagged Wayland connection. All Wayland connections from the
+spawned process tree will carry the specified tag, which can be matched in
+[client rules](window-rules.md):
+
+```shell
+~$ jay run-tagged my-tag firefox
+```
+
+### `jay generate-completion`
+
+Generate shell completion scripts:
+
+```shell
+~$ jay generate-completion bash
+~$ jay generate-completion zsh
+~$ jay generate-completion fish
+~$ jay generate-completion elvish
+~$ jay generate-completion powershell
+```