736 lines
14 KiB
Markdown
736 lines
14 KiB
Markdown
# 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.
|
|
|
|
---
|
|
|
|
## JSON Output
|
|
|
|
Most query and status commands can output machine-readable JSON instead of
|
|
human-readable text. Pass the global `--json` flag before the subcommand:
|
|
|
|
```shell
|
|
~$ jay --json randr
|
|
~$ jay --json clients
|
|
~$ jay --json idle
|
|
```
|
|
|
|
Each command prints one or more JSON objects, one per line (JSONL format). This
|
|
makes it easy to process with tools like `jq`:
|
|
|
|
```shell
|
|
~$ jay --json randr | jq '.drm_devices[].connectors[].name'
|
|
~$ jay --json clients | jq 'select(.pid != null) | .pid'
|
|
```
|
|
|
|
By default, fields that are empty arrays, `null`, or `false` are omitted from
|
|
the output to reduce noise. To include every field, pass `--all-json-fields`:
|
|
|
|
```shell
|
|
~$ jay --all-json-fields --json randr
|
|
```
|
|
|
|
### Supported Commands
|
|
|
|
The following commands support `--json`:
|
|
|
|
`jay clients`
|
|
: One JSON object per client.
|
|
|
|
`jay color-management status`
|
|
: Color management enabled/available status.
|
|
|
|
`jay config path`
|
|
: The config file path as a JSON string.
|
|
|
|
`jay idle status`
|
|
: Idle interval, grace period, and inhibitors.
|
|
|
|
`jay input show`, `jay input seat <seat> show`, `jay input device <id> show`
|
|
: Seats and input devices with all properties.
|
|
|
|
`jay log --path`
|
|
: The log file path as a JSON string.
|
|
|
|
`jay pid`
|
|
: The compositor PID as a JSON number.
|
|
|
|
`jay randr show`
|
|
: DRM devices, connectors, outputs, modes, and display properties.
|
|
|
|
`jay seat-test`
|
|
: Streaming JSONL -- one JSON object per input event (key, pointer, touch,
|
|
gesture, tablet, switch).
|
|
|
|
`jay tree query`
|
|
: One JSON object per root node, with children nested recursively.
|
|
|
|
`jay version`
|
|
: The version string as a JSON value.
|
|
|
|
`jay xwayland status`
|
|
: Xwayland scaling mode and implied scale.
|
|
|
|
> [!TIP]
|
|
> Mutating commands (e.g., `jay idle set`, `jay randr output ... enable`)
|
|
> produce no output, so `--json` has no effect on them.
|
|
|
|
---
|
|
|
|
## 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
|
|
```
|